Nitric logo

Guides

Integrating Twilio with Nitric

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.

twilio dashboard credentials

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.ts

import 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.

npm install 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.ts

import { 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.

npm install 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=14f7e9a0b95d11ec84220242ac120002
TWILIO_AUTH_TOKEN=6f20cb2ae2764be8b615d6fad4accec4
TWILIO_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.ts

import { 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.ts

textApi.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:

npm run dev

Note: the dev script in the template starts the Nitric Server using nitric start and runs your functions.

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

Previous
Stripe