Overview
The Twilio SMS connector sends SMS and MMS messages from RPI through Twilio. RPI calls the Twilio API directly with the credentials on each channel. Twilio reports delivery statuses to the RPI Callback Service, and RPI reads replies from Twilio when channel synchronization runs.
To help you find all relevant content in the same place, this connector guide replaces the Twilio content that was previously located in the Best Practices section (including the Functional guide), the External configuration guide, and the Reference guide channel configuration (Channel specific tab section).
If you’re using the Twilio connector in RPI v7.8.20261113.1905 or later, refer to Twilio connector guide (RPI v7.8.20261113.1905 and later) instead.
Key capabilities
-
Send SMS and MMS messages from an offer activity in an interaction workflow, or from a queue listener.
-
Track delivery states for each contact: Queued, Sent, Delivered, Undelivered, Failed, and Invalid Numbers.
-
Capture opt-out, opt-in, and help keywords, and skip opted-out numbers automatically.
-
Capture survey responses based on keywords you define in the offer.
-
Retry sends automatically when Twilio returns certain temporary errors.
-
Use the resulting states as inputs to downstream workflow activities and reporting.
Architecture
Components
|
Component |
Role |
|---|---|
|
Execution Service |
Sends batch, seed, and test messages through the Twilio API. Runs channel synchronization, which turns delivery statuses and replies into states, suppression records, and counts. |
|
Queue Reader |
Sends queue listener messages through the Twilio API. Writes the delivery statuses the Callback Service receives into your data warehouse. |
|
Node Manager |
Schedules channel synchronization and assigns it to an Execution Service. |
|
Callback Service |
Receives Twilio's delivery status webhooks at a public address and puts them on the callback queue. |
|
Queue provider |
Holds the personalized content queue that each send uses, and the callback queue. |
|
Twilio |
Delivers messages to carriers, reports delivery statuses through webhooks, and keeps the message history RPI reads replies from. |
Each Twilio channel holds its own Account SID and Auth token, so channels can use different Twilio accounts or subaccounts.
How data flows
-
The Execution Service personalizes each message and sends it through the Twilio API. For queue listener sends, the Queue Reader does this.
-
Twilio delivers the message.
-
Twilio posts each delivery status to the Callback Service.
-
The Callback Service puts the status on the callback queue, and the Queue Reader writes it to the
RPI_TwilioEventstable in your data warehouse. -
Channel synchronization reads those events, polls Twilio for replies to your sender numbers, and writes states, suppression records, and counts.
Network paths
|
From |
To |
Purpose |
|---|---|---|
|
Execution Service and Queue Reader |
The Twilio API ( |
Sending messages, reading the Messaging Service's sender numbers, reading replies, and requesting bulk exports. |
|
Twilio |
The Callback Service's public address, over HTTPS |
Delivery statuses. |
|
Twilio |
Each MMS image's public URL, over HTTPS |
Twilio downloads MMS images. |
|
RPI services and the Callback Service |
The queue provider |
The personalized content queue and the callback queue. |
The Callback Service accepts every request and doesn't check Twilio's signature.
Set up Twilio messaging
Setup happens in this order:
-
You prepare your Twilio account: the Account SID and Auth token, sender numbers, and a Messaging Service.
-
You point the Messaging Service's delivery status callback at the RPI Callback Service.
-
You configure the Twilio SMS channel in RPI, including a personalized content queue.
Twilio Console labels change over time. If a menu has moved, refer to Twilio's own documentation.
When Redpoint hosts RPI (Redpoint CDP), choose who manages the Twilio account:
-
Redpoint created and client managed (recommended): Redpoint creates a Twilio subaccount for you and gives you its login, so you can finish the setup in Twilio.
-
Redpoint managed: Redpoint does all of the Twilio setup, and you don't have access to Twilio.
-
Client managed: you bring your own Twilio account.
Get the Account SID and Auth token
You enter these on the Twilio SMS channel in RPI.
-
Sign up for a Twilio account and log in.
-
Once your account is verified and has a phone number, go to your Account management page.
-
In the submenu, select API keys & tokens. Scroll down to Auth Tokens to see your live credentials (Account SID and Auth Token).
-
Select the lock icon to show the Auth token.
Create a subaccount (optional)
Subaccounts are like accounts, but they're owned and managed by a parent account. A subaccount has its own Auth tokens. If a subaccount's token is compromised, it can't be used to reach the parent account or other subaccounts.
-
From the Account menu, select Subaccounts.
-
Select Create subaccount.
-
Enter a friendly name for the subaccount, then select Create subaccount.
-
Select the new subaccount, so that the numbers and Messaging Service you create next belong to it.
To use a subaccount, enter its Account SID and Auth token on the channel instead of the parent account's.
Get sender numbers
-
On the Develop tab, select Phone Numbers > Manage > Active numbers to see the numbers you have.
-
To add a number, select Phone Numbers > Manage > Buy a number, then select Buy on the number you want.
In the U.S., Twilio requires A2P 10DLC registration for long codes and verification for toll-free numbers before they can send messages. Unregistered numbers fail to send.
On a Twilio trial account, Twilio sends messages only to verified phone numbers. To test from a trial account, add your test phones under Phone Numbers > Manage > Verified Caller IDs. Twilio verifies each one with a one-time passcode.
Create a Messaging Service
A Messaging Service bundles sender numbers and messaging settings, which helps with high-volume sending. RPI sends every message through a Messaging Service; you can't send from a single number.
-
In the Console, from the Develop tab, select Messaging, then Services.
-
Select Create Messaging Service, add your sender numbers to its sender pool, and finish the setup.
-
After setup, copy the Messaging Service SID from the Properties page into the channel's Message Service ID field.
Set the delivery status callback
-
In the Console, open the Messaging Service and select Integration.
-
Set Delivery Status Callback to
https://<callback server>:<port>/api/PostEvents?channelLabel=Twilio%20SMS.
RPI doesn't send this address to Twilio with each message, so it must be set on the Messaging Service.
channelLabel must be exactly Twilio SMS, the connector type, not the name you gave your channel. If it's wrong or missing, the Callback Service drops Twilio's events without reporting an error.
The Callback Service must run in queue mode, on the same queue provider as RPI, and put events on the queue set by the CallbackServiceQueuePath System Configuration setting (default RPICallbackService). In file mode, Twilio events are never imported. See Appendix D: Callback Service Configuration.
You don't need an incoming messages webhook: RPI reads replies from Twilio's message history. The only effect of also posting incoming messages to the Callback Service is on the keyword and Mobile Originated counts (see State synchronization).
Configure the channel in RPI
-
Go to Configuration > Channels.
-
Select the green plus button, then Mobile > Add new Twilio SMS channel.
-
On the General tab, name the channel for your client or resolution level.
-
On the Channel Specific tab, set the fields in the following table.
|
Field |
Description |
Default and limits |
|---|---|---|
|
Recipient phone |
The attribute that holds each contact's mobile number. Browse for it with the recent items chooser or the File System Dialog, or drag it from the toolbox. Numbers must start with |
Must be a text attribute based on a database column. The channel can be saved without it, but a send then fails with "No recipient number has been configured for this channel or offer" unless the offer supplies its own recipient attribute. |
|
Account SID |
Your Twilio Account SID. |
Required. Maximum 100 characters. |
|
Authorization token |
Your Twilio Auth token. You can type it or reference a secret in your key vault. |
Required. Masked. Maximum 100 characters. |
|
Message Service ID |
The SID of the Twilio Messaging Service to send from (it starts with |
Required. Maximum 34 characters. |
|
Auto-suppress |
Exclude contacts listed in the channel's suppression table from the audience. This is separate from the Twilio opt-out check at send time, which doesn't depend on this setting (see Outbound fulfillment). |
On. |
|
Custom suppression table |
Use your own suppression table instead of the one named by the |
Off. |
|
Suppression table name |
The name of your custom suppression table. Available only when Custom suppression table is selected. |
Required when available. Maximum 50 characters. Must be a valid table name that doesn't start with a number. Can't be |
|
Allow survey responses |
Allow offers on this channel to use survey keywords. |
Off. |
|
Maximum API call retry attempts |
How many times RPI retries a send after a retryable Twilio error (see Outbound fulfillment). |
10. Range 1 to 100. |
|
Minimum API call retry delay |
Sets how fast the wait between retries can grow, in seconds. Before retry *n*, RPI waits a random time of up to half the minimum delay times *n*, so the wait can be shorter than the minimum. With the defaults, the longest wait is 5 seconds. |
1. Range 1 to 600. |
|
Maximum API call retry delay |
The longest wait between retries, in seconds. |
10. Range 1 to 600. |
|
Event import batch size |
The number of rows RPI writes to the data warehouse at a time during synchronization. Every event is still processed on each run. |
10,000. Range 5,000 to 20,000. |
|
Import historical data |
Read the part of the Retrieval period window older than 400 days from Twilio bulk exports. |
On. |
|
Retrieval period window |
How far back the first synchronization reads replies, in months or days. RPI reads up to 400 days from Twilio's message history, and anything older from bulk exports when Import historical data is selected. 13 months is treated as 400 days; other month values count as 30 days each. |
13 months. Range 0 to 10,000 (the validation message says 1 to 10,000, but 0 is accepted). |
|
Email address |
Where Twilio sends a notification when a bulk export job finishes. |
Optional. Must be a valid email address. |
|
Image folder |
The external content provider folder that RPI uploads MMS images to. Select Choose image folder to pick a folder. Only FTP, Amazon S3, Azure Storage, Box, WebDAM, and WebDAV folders are listed. |
Required for MMS offers that use RPI image assets (see Send MMS). |
|
Callback service URL |
Not used by RPI. The delivery status callback is set on the Messaging Service (see Set the delivery status callback). |
Required. Maximum 200 characters. Must be an absolute URL. |
The defaults for retries, event import batch size, and retrieval period come from cluster settings (see Deployment settings). A channel saved by an earlier version with retry values of 0 uses those defaults.
Advanced tab
On the Advanced tab, set Personalized content queue and Personalized content queue path.
-
Personalized content queue and Personalized content queue path: required. Each send renders its messages onto this queue and sends them from it. RabbitMQ is the only supported queue provider for personalized content queues.
-
Enable trace: logs each request RPI sends to Twilio (address, method, and body) as a Plugin Trace entry in the RPI log, for sends, connectivity tests, and synchronization. Twilio's responses aren't logged. The Auth token is never written, but recipient numbers and message text are. When you select it, RPI warns: "Enabling this option can impact performance and potentially persist PII data within the trace data".
-
No. of days fulfillment active: how many days after a send RPI keeps updating its states and counts. The default is 30 days.
Web Adapters tab
You can add URL shortener web adapters only, such as Bitly or Rebrandly. Saving with any other adapter fails with "Only URL shortener adapters are supported with this channel". Twilio warns that shortened links, especially on shared public shortener domains, can increase carrier filtering. Use a branded domain where you can, and monitor delivery rates.
Saving the channel
When you create a channel, or change its Recipient phone or suppression table settings, RPI shows "The database will be validated when these channels are saved." When you save, RPI starts a Validate channels job, which you can follow in My Jobs.
Send messages
Send SMS from an interaction
-
Create an interaction (Orchestration > Interactions > Create New Interaction) and name it.
-
Add a workflow control (for example, a manual control), a targeting activity (for example, a batch audience), and an offer activity.
-
In the offer activity, assign a mobile offer.
-
Under Channels, select Configure, then Add Channel, and choose your Twilio channel.
-
Select Done in the dialog, then Done on the offer activity, and save the interaction.
-
To check an offer before sending, select Send Test SMS Message in the mobile offer designer. Test messages don't get delivery states, and a message Twilio rejects isn't reported back: the test looks successful, and the rejection appears only in
Twilio_FailedSmsSends. MMS images aren't attached to test messages.
A queue listener that uses a Twilio channel sends each trigger's messages one by one. If one of the trigger's numbers is invalid or opted out, the remaining sends for that trigger stop and its offer history is rolled back (see Troubleshooting).
Send MMS
-
In the mobile offer, set Mobile Messaging Type to MMS.
-
Add images to the offer.
-
If the offer uses RPI image assets, make sure the channel has an Image folder.
How RPI gets each image to Twilio depends on where the image comes from:
-
RPI image assets: RPI uploads the image to the channel's image folder and sends Twilio the uploaded file's URL.
-
Files from an external content provider: RPI sends Twilio the file's own URL and doesn't upload it.
Either way, Twilio downloads the image from its URL, so the URL must be publicly reachable over HTTPS without signing in. An MMS offer can contain at most 10 inserted items; attributes and links count as well as images.
On an SMS offer, images are ignored, and RPI warns: "The images on the offer will be ignored for SMS mobile messaging type".
Message content
-
Personalization: attributes are merged into the text, with their date, number, and currency formats.
-
Dynamic content: supported, except table content, which is dropped.
-
Links: links can carry attribute parameters and can be shortened by the channel's URL shortener web adapter. A URL shortener selected on the offer overrides the channel's. If the adapter has a website URL set, only links that start with it are shortened.
-
Length: RPI doesn't check or split long messages. Twilio splits them into segments and bills each segment; a message over Twilio's maximum length is rejected and recorded as a failed send.
Delivery and opt-out tracking
Outbound fulfillment
-
Audience: while RPI selects the contacts, it removes duplicates by contact key (the Recipient phone), and, if Auto-suppress is selected, excludes contacts in the channel's suppression table. Deduplication is skipped when the audience's resolution key is the same column, or when contact-key deduplication is turned off on the channel.
-
Connectivity test: RPI checks that it can read the Messaging Service with the channel's Account SID and Auth token, and writes and reads a test message on the personalized content queue. It tries up to 10 times, one minute apart, before stopping the activity.
-
Preparation: RPI personalizes each message and, for MMS, uploads the images.
-
Queueing: RPI puts the messages on the personalized content queue in batches (see
MaxContactPerPersonalizeContentGenerationunder Deployment settings), then reads them back with 10 parallel readers. A batch that fails is moved to a queue whose name ends inFailed_n. -
For each message:
-
Opt-out check: RPI reads the Messaging Service's sender numbers and skips any number whose most recent keyword to one of them, in
TwilioSMS_Suppression, was an opt-out. This check applies whatever the Auto-suppress setting. Numbers are compared as text, so they must be stored exactly as Twilio reports them (+and country code, no spaces). -
Number check: a number that doesn't start with
+isn't sent (see States and keywords). -
Send: RPI sends one request per message, up to 10 at a time for batch sends (queue listeners send one at a time); Twilio's messaging API doesn't batch. If Twilio returns error 20429 (too many requests), 21603, 21604, 21612, 30003, 30017, 52181, 63008, 63010, 63011, 63012, or 63023, RPI waits and retries, within the channel's retry settings. Any other Twilio error, or a network error, fails the message at once.
-
Tracking: RPI stores the Twilio message ID in
Twilio_MessageIDs. Messages Twilio rejects are recorded inTwilio_FailedSmsSendsand as Invalid Numbers.
-
-
Seeds: sent last, with the same checks. A seed that fails is logged and skipped without failing the activity.
State synchronization
Channel synchronization is a system task named "Channel <name> data synchronization". The Node Manager schedules it, every 10 minutes by default, or once a day at a fixed time (01:00 by default), and an Execution Service runs it. To change the schedule, open Operations > System Tasks, edit the channel's data synchronization task to poll at a different interval or run at a fixed time each day, and save. It works only on the channel's active sends: a send is active for the channel's No. of days fulfillment active (see Advanced tab). A queue listener's send stays active while the listener is active, and each of its messages is tracked for 30 days after it's sent. When a channel has no active sends, synchronization does nothing, and no replies are imported.
Each run:
-
Delivery states: for each active send, newest first, RPI reads the delivery statuses stored in
RPI_TwilioEventsfor the messages it's still tracking, and keeps the furthest state each message reached: Queued, then Sent, then Delivered or Undelivered. Failed replaces only Queued. Each new state is added as a row, so a delivered contact also has Queued and Sent rows. Messages that reached Delivered, Undelivered, or Failed stop being tracked; messages with no stored status are checked again on every run while the send is active. -
Survey responses: for offers with survey keywords, RPI reads replies to the sender numbers recorded when the offer was sent.
-
Replies: RPI reads Twilio's message history for every number in the Messaging Service's sender pool, since the last synchronization. The first run reads back as far as the Retrieval period window. Every opt-out, opt-in, and help keyword read in a run is stored in
TwilioSMS_Suppression. -
Channel suppression table: RPI adds a number to the channel's suppression table only when its most recent keyword to every sender number in the Messaging Service is an opt-out, and removes it only when the most recent keyword to every sender number is an opt-in.
-
Counts: RPI updates the channel execution result counts. Delivery state counts are the number of contacts that ever reached each state. Survey Response counts are the number of matching replies, not contacts. The keyword and Mobile Originated counts come from messages the Callback Service received for the sender number, so they stay at 0 unless the Messaging Service's incoming messages webhook also points at the Callback Service. These counts aren't per send.
A keyword reply is recorded once for each active send that included that number. The reply doesn't have to answer an RPI message: any keyword sent to a number in the Messaging Service counts.
Where data is stored
|
Table |
Database |
Contents |
|---|---|---|
|
|
Data warehouse |
Every event the Callback Service received for Twilio SMS, from all Twilio channels in the tenant. |
|
|
Data warehouse |
Twilio message IDs RPI is tracking. Messages that never reach a final state stay here. |
|
|
Data warehouse |
Messages Twilio rejected when RPI sent them, with the error code and message (up to 500 characters). Later Failed or Undelivered states aren't recorded here. |
|
|
Data warehouse |
Every opt-out, opt-in, and help keyword received, per phone number and sender number. Shared by all Twilio channels. |
|
|
Data warehouse |
Messages sent by queue listeners. |
|
|
Data warehouse |
The sender numbers used by offers with survey keywords. |
|
Offer history states table |
Data warehouse |
Per-contact states used by reporting and downstream activities. |
|
|
Data warehouse |
Temporary tables created during synchronization and dropped afterward. |
|
|
File output directory |
Downloaded Twilio bulk export files. |
RPI creates these tables automatically when it first needs them. It removes messages from Twilio_MessageIDs once they reach a final state, drops the temporary tables after each run, and otherwise doesn't delete rows or bulk export files.
States and keywords
|
State |
Type |
Meaning |
|---|---|---|
|
Queued |
Delivery |
Twilio reported the message as queued. |
|
Sent |
Delivery |
Twilio reported the message as sent to the carrier. |
|
Delivered |
Delivery |
The carrier confirmed delivery. |
|
Undelivered |
Delivery |
The carrier couldn't deliver the message. The event name holds the Twilio error code, followed by |
|
Failed |
Delivery |
The message failed after Twilio accepted it. The event name is as for Undelivered. |
|
Invalid Numbers |
Delivery |
The number didn't start with |
|
Stop, StopAll, Unsubscribe, Cancel, End, Quit, OptOut, Revoke |
Opt-out keyword |
The recipient opted out. |
|
Start, Yes, Unstop |
Opt-in keyword |
The recipient opted back in. |
|
Help, Info |
Help keyword |
Recorded only. |
|
Survey Response |
Survey |
The reply contained the offer's primary survey keyword and at least one additional keyword. The event name holds the matched additional keyword. |
Twilio's "sending" status isn't recorded. Mobile Originated is a count only, not a state you can select contacts by.
Opt-out, opt-in, and help keywords match only when the whole reply is the keyword, ignoring case and surrounding spaces; "STOP ALL" and "OPT-OUT" aren't recognized. Survey keywords match anywhere in the reply, in any case.
State timestamps
|
State comes from |
Timestamp |
|---|---|
|
A delivery status, or a survey response |
The local time on the server that ran the synchronization, when it processed the event. Not the time Twilio reported it. |
|
A keyword reply |
The time Twilio recorded for the reply. |
Deployment settings
These cluster settings are set under Plugins:Twilio.
|
Setting |
Purpose |
Default |
|---|---|---|
|
|
Defaults for a new channel's retry fields. |
The channel field's default. |
|
|
Default for a new channel's Event import batch size. |
The channel field's default. |
|
|
Default for a new channel's Retrieval period window, in months. |
The channel field's default. |
|
|
How many messages RPI reads per request when it reads Twilio's message history. |
1000 |
|
|
How many contacts go into each batch on the personalized content queue. |
10000 |
|
|
How many times RPI retries reading the personalized content queue. |
10 |
|
|
Skip the Twilio part of the connectivity test. The queue check still runs. |
|
|
|
Skip reading the Messaging Service's sender numbers. This turns off the opt-out check at send time. |
|
|
|
Stop batch and seed sends. Activities log "SMS campaign is currently disabled" and complete without sending. |
|
Limitations
-
No RCS: RPI sends SMS and MMS only. The new Twilio Messaging Service (available as of RPI v7.8.xxx) does support RCS.
-
Opt-out wording: RPI doesn't add opt-out instructions to Twilio messages, even when the offer's Purpose is Marketing. Include them in the offer.
-
Link clicks: there's no link click state.
-
Document data warehouses: with a document (NoSQL) data warehouse, messages are sent, but delivery statuses aren't imported, and channel synchronization fails on every run while the channel has active sends, so no states, replies, or opt-outs are recorded.
-
Twilio Inbound SMS channel: isn't available in these builds; it can't be created or edited.
Activity log
At the end of a send with at least one targeted contact, the activity log shows a summary like this:
-
Total records processed:- {n}, Invalid SMS Numbers={n}, Unsubscribed SMS Numbers={n} -
Total records sent to queue:- Success={n}, Failed={n} -
Total records sent to Twilio:- Success={n}, Failed={n}
Invalid SMS Numbers counts contacts with a blank number and contacts recorded as Invalid Numbers (see States and keywords). The Twilio Success count includes opted-out numbers that were skipped. Failed counts queue batches, not recipients. Seeds aren't included.
Other messages you may see include Testing channel availability, attempt {n}, Connect to Twilio: - Success, Deduplicating on contact key, Sending SMS not successful. Now retrying... (once per retry), Current channel is initializing to upload images, Channel total embedded images uploaded: {n}, and Some batches could not be sent to the provider and have been moved to the '{queue}' queue.
Troubleshooting
|
Message or symptom |
What to do |
|---|---|
|
|
The connectivity test failed 10 times. Check the earlier activity log messages for the cause. |
|
|
RPI couldn't read the Messaging Service. Check Message Service ID, that the Messaging Service belongs to the account in Account SID, the Authorization token, and network access to Twilio. |
|
|
Set Personalized content queue on the channel's Advanced tab. |
|
|
Use a RabbitMQ queue provider (see Advanced tab). |
|
|
Set Recipient phone on the channel, or a recipient attribute on the offer. |
|
|
Queue listener sends only. The number has no |
|
|
Queue listener sends only. The number is opted out; it's sent to again only after the recipient opts back in. |
|
|
The personalized message is empty. Check the offer content and the attributes it uses. |
|
|
Select Allow survey responses on the channel, or remove keywords from the offer. |
|
|
Reduce the offer to 10 inserted items or fewer (see Send MMS). |
|
|
Set Image folder on the channel. |
|
|
Enter an absolute URL of 200 characters or fewer in Callback service URL (see Configure the channel in RPI). |
|
|
Fill in the field. |
|
|
Enter a value from 5,000 to 20,000. |
|
|
Correct the Email address, or clear it. |
|
|
Remove any web adapter that isn't a URL shortener from the Web Adapters tab. |
|
|
Choose a different Suppression table name. |
|
|
Choose a Recipient phone attribute based on a database column. |
|
|
Base the channel's filter on a resolution level in the main database, or remove the filter. |
|
|
|
|
States stay at Sent or never appear |
Check the settings in Set the delivery status callback, and that the send is still active (see State synchronization). |
|
Keyword and Mobile Originated counts stay at 0 |
Point the Messaging Service's incoming messages webhook at the Callback Service as well, or rely on the keyword states (see State synchronization). |
FAQs
-
A send fails with error 429 "Too Many Requests". What does this mean?
Twilio is rate-limiting RPI. RPI already retries rate-limited sends (Twilio error 20429); the error is recorded inTwilio_FailedSmsSendsonly when every retry was also rate-limited. Raise the channel's minimum retry delay and retry count. -
Twilio shows error 30007 "Message filtered". What can I do?
Twilio's filtering or a carrier blocked the message as spam or unwanted. Make sure your messaging complies with Twilio's Messaging Policy, that your sender numbers are registered (see Get sender numbers), and that your shortened links follow the Web Adapters tab advice. If you believe the messages comply, send Twilio Support three or more message SIDs that failed with 30007. See Twilio's 30007 error page.