Twilio Service [Deprecated]
On this page
Third party services in MongoDB Realm have been deprecated in favor of creating HTTP endpoints that use external dependencies.
You can no longer create new third-party services, but existing services will continue to work until December 2022.
Because third party services are now deprecated, they have been removed by default from the Realm UI. If you need to manage an existing third party service, you can add third party services back to the UI by doing the following:
- In the left navigation, under the Manage section, click App Settings.
- Enable the toggle switch next to Temporarily Re-Enable 3rd Party Services, and then save your changes.
Overview
Twilio provides messaging, voice, and chat services for web and mobile apps. The MongoDB Realm 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.
To use Twilio with Realm, 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:
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 Realm 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 |
|---|---|
Sends a text message to a specified phone number. |
Incoming Webhooks
Incoming webhooks for the Twilio service enable your Realm 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
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 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 Realm user that executes the webhook function when the webhook is called. |
Request Payload
Realm 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:
{ "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. |
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:
{ "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.
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
- Log in to Twilio.
- Click Programmable SMS in the left navigation menu of your Twilio project.
- Click SMS > Messaging Services.
- Click Create new Messaging Service.
- Enter a Friendly Name and Use Case
- Click Create
Add a Webhook to a Twilio Project
- Click Programmable SMS in the left navigation menu of your Twilio project.
- Click SMS > Messaging Services.
- Click the messaging service that you want to use.
- On the messaging service configuration page, check the PROCESS INBOUND MESSAGES box.
- Enter the incoming webhook URL in the Request URL box.
- Click Save.
Your Realm 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 Realm app.