Navigation

Twilio Service

Twilio provides messaging, voice, and chat services for web and mobile apps. MongoDB Stitch supports integrating apps with Twilio’s Programmable SMS service.

You will need the following to integrate Twilio with your MongoDB Stitch app:

  • Twilio account SID
  • Twilio authorization token
  • Twilio phone number

If you want to simply send text messages, you will only need to use the Twilio Service actions. However, if you would like to handle incoming messages from Twilio, you will need to set up an incoming webhook.

Add a Twilio Service

To set up a Twilio service in MongoDB Stitch:

  1. Retrieve your Twilio account information:
    1. Go to Twilio and either:
      • Create a new account and Twilio project, or
      • Log in with your existing credentials and select an existing Twilio project or create a new Twilio project.
    2. From you project’s dashboard, retrieve the:
      • Account SID
      • Auth Token.
  2. Click Services in the left navigation pane and click Add a Service.
  3. Select Twilio.
  4. Enter a name for your service in the Service Name box.
  5. Enter the Account SID and Auth Token with the values retrieved in the first step.
  6. Click Add Service.

Service Actions

The Twilio service in MongoDB Stitch provides the following actions which are available in functions and in the SDKs:

Action Description
twilioService.send() Sends a text message to a specified phone number.

For general information on service actions and how to use them, see Service Actions.

Service Rules

You must specify rules to enable the Twilio send action. A rule must evaluate to true to enable the action. For general information on service rule construction and syntax, see Service Rules.

The following arguments are permitted in Twilio service rules, and they can be accessed with the "%%args" expansion:

Field Type Description
to String The destination phone number in E.164 format, such as "+15551112222".
from String The originating phone number in E.164 format, such as "+15551112222".
body String The body of the message.

Example

Actions When
send
{
  "to" : { "%in": "%%values.confirmedNumbers" }
}

This rule ensures that applications can only perform a send action when the to argument is a string listed in confirmedNumbers, where confirmedNumbers is a user-defined constant. For more information on defining constants, see Values.

Incoming Webhooks

A MongoDB Stitch incoming webhook is a callback URL used by third-party service providers to execute a function in your Stitch app. The documentation page on Service Webhooks describes how to create an incoming webhook.

Incoming webhooks for the Twilio service enable your Stitch app to handle incoming text messages. There are no additional settings necessary when configuring a Twilio webhook, so once you’ve created a webhook, you can add it to your Twilio project.

Adding your Webhook to a Twilio Project

Use the following procedure to add your MongoDB Stitch incoming webhook to your Twilio Programmable SMS messaging service:

  1. Login to Twilio.
  2. In the left-hand navigation pane for your Twilio project, click the ellipses icon and Programmable SMS.
  3. Create a Messaging Service
    1. If this is the first messaging service for your Twilio account, click Get Started to first get a Twilio phone number.
    2. Once you have your number, click Messaging Services.
    3. If this is your first messaging service, click Create new Messaging Service. Otherwise, click the plus sign to create a new messaging service.
    4. Enter the name and use case to create the service. Once created, you will be redirected to the service configuration page.
    5. In the configuration page, check the PROCESS INBOUND MESSAGES box.
    6. Enter the MongoDB Stitch incoming webhook URL in the Request URL box. The documentation page on Service Webhooks describes where to find this URL for a particular webhook.
    7. Click Save.

Your MongoDB Stitch app is now integrated with Twilio’s SMS messaging service. Send a message to your Twilio phone number to invoke the incoming webhook for your MongoDB Stitch app.

Example Webhook Function

The following webhook function inserts incoming data into a MongoDB collection.

exports = function(payload, response) {
  const mongodb = context.services.get("mongodb-atlas");
  const requestLogs = mongodb.db("test").collection("requestlogs");

  requestLogs.insertOne({
    "body": payload.Body,
    "from": payload.From
  }).then(result => {
    response.setBody(result.insertedId)
  })
}

The payload document is passed by the Twilio service and contains information from the request.

For a more comprehensive example of webhooks being used in a MongoDB Stitch application, see Integrate the ToDo App with Twilio.