• Stitch >
• External Services >
• Built-In Services

Twilio Service

Overview

Twilio provides messaging, voice, and chat services for web and mobile apps. The Stitch Twilio service supports integrating Twilio’s Programmable SMS service into your application.

• To send an outbound text message, use the send() action.
• To handle and optionally respond to incoming text messages, create an incoming webhook and add it to a Twilio messaging service. See the incoming webhooks section on this page for an example.

Note

To use Twilio with Stitch, you must have a Twilio Phone Number registered to a messaging service associated with your Twilio account. You can create a new number from the Numbers page of the Twilio dashboard, or by following Twilio’s Programmable SMS Quickstart guide.

Configuration Parameters

You will need to provide values for the following parameters when you create a Twilio service interface:

• Stitch UI
• Import/Export

<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "twilio",
  "config": {
    "sid": <Twilio Account SID>
  },
  "secret_config": {
    "auth_token": "<Secret Name>"
  }
}

Parameter	Description
Service Name config.name	The name of this Twilio service interface. This must be unique from all other service interfaces in your application.
Twilio Account SID config.sid	A unique identifier for your Twilio account. You can find this value on your Twilio account dashboard.
Twilio Authorization Token secret_config.auth_token	The name of a Secret that stores a Twilio authorization token, which proves that you are the owner of a Twilio account. You can find this value on your Twilio account dashboard.

Service Actions

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

For instructions on using a service action, see Call a Service Action.

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

Incoming Webhooks

Incoming webhooks for the Twilio service enable your Stitch app to handle incoming text messages. Once you’ve created an incoming webhook, you can add it to a Twilio messaging service to handle incoming messages for that service.

Configuration

• Stitch UI
• Import/Export

You will need to provide values for the following parameters when you create a Twilio incoming webhook:

You will need to provide a configuration file of the following form when you create a Twilio incoming webhook:

copy

{
  "name": <string>,
  "respond_result": <boolean>,
  "run_as_user_id": <string>,
  "run_as_user_id_script_source": <string>,
}

Configuration Value	Description
Webhook Name name	Required. The name of the webhook. Note Each incoming webhook in a Twilio service interface must have a unique name.
Respond With Result respond_result	Required. If true, Stitch sends the return value of the webhook function to Twilio in the response body. Note Twilio will automatically send a text message containing the webhook response’s body to the phone number that sent the initial message.
Run Webhook As run_as_user_id run_as_user_id_script_source	Optional. The id of the Stitch user that executes the webhook function when the webhook is called. There are three ways to configure the execution user: System: The execution user is a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions. User Id: You select a specific application user to execute the function. Script: You define a function that returns the id of the execution user. You can specify the user id directly in run_as_user_id or provide a stringified Stitch function that accepts the webhook payload and returns the user id in run_as_user_id_script_source. If you do not specify a specific user id or a function that resolves to a user id, Stitch executes the webhook function as a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.

Request Payload

Stitch automatically passes a payload document as the first argument to incoming webhook functions. In a Twilio Service incoming webhook the payload object represents an incoming SMS message and has the following form:

copy

{
   "From": "<Sender's Phone Number>",
   "To":   "<Receiver's Phone Number>",
   "Body": "<SMS Body>"
}

Field	Description
From	A string that contains the E.164-formatted phone number that sent the incoming text message.
To	A string that contains the E.164-formatted phone number associated with your Twilio messaging service that the incoming text message was sent to.
Body	A string that contains the content of the incoming text message.

Example

A text message sent from the phone number (555)867-5309 to the Twilio phone number (805)716-6646 with the message "Hello! How are you?" would be represented by the following payload document:

copy

{
  "From": "+15558675309",
  "To": "+18057166646",
  "Body": "Hello! How are you?"
}

Example Webhook Function

The following webhook function stores text messages sent to a Twilio phone number in a MongoDB collection and sends a text message response to the phone number that sent the text.

copy

exports = async function(payload, response) {
  // const { To, From, Body } = payload;
  const mongodb = context.services.get("mongodb-atlas");
  const texts = mongodb.db("demo").collection("texts");

  try {
    // Save the text message body, to number, and from number
    const { insertedId } = await texts.insertOne(payload);
    // Send the user a confirmation text message
    response.setBody(`Saved your text message with _id: ${insertedId}`);
  } catch (error) {
    // Send the user an error notification text message
    response.setBody(`Failed to save your text message: ${error}`);
  }
}

Configure Twilio

Create a Messaging Service

1. Log in to Twilio.
2. Click Programmable SMS in the left-hand navigation of your Twilio project.
3. Click SMS > Messaging Services.
4. Click Create new Messaging Service.
5. Enter a Friendly Name and Use Case
6. Click Create

Add a Webhook to a Twilio Project

1. Click Programmable SMS in the left-hand navigation of your Twilio project.
2. Click SMS > Messaging Services.
3. Click the messaging service that you want to use.
4. On the messaging service configuration page, check the PROCESS INBOUND MESSAGES box.
5. Enter the incoming webhook URL in the Request URL box.
6. 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.

←   Send Mobile Push Notifications twilio.send()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.