Integrating Twilio with Nitric
Build a serverless application with Twilio and Nitric for AWS, Google Cloud, or Azure
What we'll be doing
In this guide we'll use the Nitric Framework with Twilio to build a serverless API that can send SMS to users. This won't include a frontend, however you can look at how to integrate a Nitric API in one of our other comprehensive guides.
Getting Started
Create a Project
Create a new project using:
nitric new? What is the name of the project? nitric-twilio? Choose a template: official/TypeScript - Starter? Glob for the function handlers? functions/*.ts
This will scaffold the project ready for defining your API.
Create a Twilio Account
To integrate with Twilio, it's important to create a Twilio account. If you don't already have an account, there's an option to start a free trial here. This trial doesn't ask for any payment details and provides a decent amount of free credits.
Once you've gone through the account creation and verification, you'll arrive at the dashboard. There is a section which contains the important API credentials. These are used to connect to the API so keep them in mind.
Create the Messenger Class
The messenger class acts as a helper wrapper for sending text messages. It accepts the account SID and the auth token and creates a client. This client is then used in the single method send
which accepts a text message object and creates it.
// common/messenger.tsimport twilio, { Twilio } from 'twilio';class Messenger {private client: Twilio;constructor(twilioAccountSID: string, twilioAuthToken: string) {this.client = twilio(twilioAccountSID, twilioAuthToken);}async send(text): Promise<string> {try {const message = await this.client.messages.create(text);return `${message.dateCreated}: Successfully sent text message`;} catch (err) {return `An error occured: ${err}`;}}}export default Messenger;
You will need to add the twilio module using your preferred package manager.
yarn add twilio
Create the API
For the API we will have a single POST route send
. This done by creating an API resource using the Nitric SDK and defining a new route.
// functions/text.tsimport { api } from '@nitric/sdk';const textApi = api('text');textApi.post('/send', async (ctx) => {});
The next step is pulling the environment variables in and constructing our messenger. We will use the dotenv
module.
yarn add dotenv
We can create a .env
file in root of the project with the twilio API information that's sitting on your Twilio dashboard.
TWILIO_ACCOUNT_SID=14f7e9a0b95d11ec84220242ac120002TWILIO_AUTH_TOKEN=6f20cb2ae2764be8b615d6fad4accec4TWILIO_PHONE_NUMBER=+1234567890
The dotenv.config
call will load the variables from the .env
file into the process.env
object. You can then use the variables to construct the messenger.
// functions/text.tsimport { api } from '@nitric/sdk';import Messenger from '../common/messenger';require('dotenv').config();const textApi = api('text');const twilioAccountSID = process.env.TWILIO_ACCOUNT_SID;const twilioAuthToken = process.env.TWILIO_AUTH_TOKEN;textApi.post('/sendMessage', async (ctx) => {const messenger = new Messenger(twilioAccountSID, twilioAuthToken);});
We'll fill in the logic for the route. First, pull the data from the POST request. This data will look like so:
{"to": "+16505130514","message": "Test Message from Twilio!"}
And can be extracted from the context like this:
const { to, message } = ctx.req.json();
Secondly, convert this data to an SMS object:
{to,body: message ?? '',from: process.env.TWILIO_PHONE_NUMBER}
Finally, putting all these components all together, we get a functional text messaging endpoint ready for testing:
// functions/text.tstextApi.post('/send', async (ctx) => {const messenger = new Messenger(twilioAccountSID, twilioAuthToken);const { to, message } = ctx.req.json();const resp = await messenger.send({to,body: message ?? '',from: process.env.TWILIO_PHONE_NUMBER,});ctx.res.body = resp;return ctx;});
Test the API
This API can easily be tested using the local Nitric dev environment. This is started with the following command:
nitric run
Which will output our locally hosted endpoint:
SUCCESS Configuration gathered (18s)SUCCESS Created Dev Image! (1s)SUCCESS Started Local Services! (8s)SUCCESS Started Functions! (2s)Local running, use ctrl-C to stopApi | Endpointtext | http://localhost:9001/apis/text
We can then use a tool like postman
or curl
to test the endpoint.
curl -X POST -d '{"to":"+16505130514", "message": "Test Message from Twilio!"}' http://localhost:9001/apis/text/send
If everything has been set up correctly, and the 'to' field on the JSON request body is replaced with a phone number you own, you will get a text that looks something like:
Sent from your Twilio trial account -Test Message from Twilio!
Thats it! If you want to deploy the API you can using our deployment docs. If you want to attach a frontend to the application so its a bit more user friendly, you can use any framework you want or follow our Next.js guide