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

You will also need a MongoDB Stitch incoming webhook to receive requests from Twilio. However, your app may send messages to Twilio without a webhook.

Add a Twilio Service to Your MongoDB Stitch App

Use the following procedure to add a Twilio service to your MongoDB Stitch app:

A. Get Twilio Account Info

1

Login to Twilio.

Go to Twilio and either:

  • Create a new account and your Twilio project, or
  • Log in with your existing credentials and select an existing Twilio project or create a new Twilio project.
2

Get Accout SID and Auth Token.

From you project’s dashboard, retrieve the:

  • Account SID, and
  • Auth Token.

B. Add Twilio Service to the MongoDB Stitch App

1

Go to the MongoDB Atlas project associated with your MongoDB Stitch application.

Tip

If you have not set up your cluster or set up your MongoDB Stitch application, see Getting Started.

  1. Log into Atlas.
  2. Navigate to the project associated with your MongoDB Stitch application.
  3. Select Stitch Apps in the left-hand nav panel.
  4. Select the application you wish to integrate with the Twilio Service. You will be redirected to the MongoDB Stitch console.
2

Add the Twilio service.

  1. In the MongoDB Stitch console, click Add service in the left-hand nav panel.
  2. Select Twilio.
  3. Enter a name for your Twilio service.
  4. Click Add service

C. Configure the Twilio Service

1

Click Config for your added service.

2

Enter your Twilio Accout SID and Auth Token.

Enter the Account SID and Auth Token with the values retrieved in an earlier step.

3

Click Save.

D. Create a MongoDB Stitch Incoming Webhook

A MongoDB Stitch incoming webhook is a callback URL used by a third-party service, such as Twilio, to execute a MongoDB Stitch pipeline. MongoDB Stitch pipelines provide developers the flexibility to concatenate multiple services in the same app. A pipeline defines one or more stages, where each stage consists of the following:

  • A MongoDB Stitch service defined for the app
  • An action for the specified service
  • Arguments to pass to the service

Use the following procedure to create a MongoDB Stitch incoming webhook for your app:

1

Click the Incoming Webhooks tab for your added Twilio service.

2

Click New Webhook.

3

Enter the following properties for the webhook.

Property Action
Name Enter the name for your new webhook.
Respond with Result Optional. Switch to enabled to send responses to URLs that invoke the incoming webhook.
Output Type

Select the output type for the webhook pipeline:

  • Select Array to return all documents from the pipeline.
  • Select Single Document to return a single document from the pipeline.
  • Select Boolean to return a boolean value indicating whether the pipeline returned any output.
4

Specify the webhook pipeline stage(s).

For the displayed pipeline stage, hover over the stage to reveal the EDIT and DELETE buttons.

Click Edit and edit the following:

Field Action
Service Select the service for the stage.
Action

Select the action for the service. For a list of actions available, see Service Actions.

In the text box below the Action, enter the arguments to the specified action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

For example, if the specified is the built-in action literal, you would specify an argument that defines items:

{"items": ["%%vars"]}
Bind data to %%vars

Optional. Switch Bind data to %%vars to enabled to define variables to use as arguments to the action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

In the Bind data to %%vars text box, specify the variables.

{
  "text": "%%args.Body",
  "sender": "%%args.From"
}

You can reference these variables in the action arguments section as "%%vars.text" and "%%vars.sender" or you can reference the whole variables document with the expansion %%vars.

For more details on Twilio message parameters, see Twilio message.

Click Done.

To add more stages to the pipeline, click Add Stage and repeat this step.

5

Click Create.

Upon successful creation of the webhook, its Webhook URL is displayed.

For example, the following incoming webhook pipeline consists of two stages:

  • The first stage defines documents using information from the request message.
  • The second stage inserts these documents into the requestlogs collection in the test database:
Service Action Args Let (Bind data to %%vars)
built-in literal { "items": [ "%%vars" ] }
{
  "text": "%%args.Body",
  "sender": "%%args.From"
}
mongodb-atlas insert
{
  "database": "test",
  "collection": "requestlogs"
}
 

E. Create a Twilio Messaging Service

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

1

Login to Twilio.

2

Go to the Programmable SMS Dashboard.

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.

#. Enter the name and use case to create the service. Once created, you will be redirected to the service configuration page.

  1. In the configuration page, check the PROCESS INBOUND MESSAGES box.
  2. Enter the MongoDB Stitch incoming webhook URL in the Request URL box.
  3. 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.

For an example, see Integrate ToDo with Twilio.

Pipelines and Twilio Service

With MongoDB Stitch, you can define a sequence of actions to perform as a pipeline of stages. For the Twilio service, MongoDB Stitch provides the following actions:

Action Description
send Sends an email message to a specified address.

Note

A pipeline can consist of stages that use different MongoDB Stitch services.

←   Slack Service Rules  →