Twilio SMS/MMS

Twilio Messaging SMS/MMS integration allows you to send and receive SMS/MMS messages through Twilio's scalable messaging service using Bloomreach Engagement's standard SMS messaging functionality. You can find it in Integrations > + Add new integration.

With the Twilio Super Network providing connections to 4,800+ carrier partners, you can confidently send messages and build customer relationships globally.


Initial setup

Twilio Messaging (SMS/MMS) integration has to be initially set up by our SMS specialist. Reach out to your CSM/CS team to integrate and being using Twilio SMS/MMS.


Before proceeding with this integration, you must have your Twilio account set up. If you don't have a Twilio account yet, reach out to your CSM to help get yours created. You will also need the following credentials from your Twilio account:

  • Account SID – Your unique 34-character Twilio Account SID (begins with “AC”) acts as a username to identify your Twilio Account. This can be found in the Twilio Console.
  • Auth token – Your authentication token, which is provided for each service plan. This can be found in the Twilio Console.
  • API Key SID – Your API Key SID to authenticate access to your Twilio account. Ensure your API Key's permissions are granted the necessary access levels.
  • API Key Secret – Your API Key Secret to authenticate access to your Twilio account.

Integration setup

Follow these steps to set up your Twilio Messaging SMS/MMS provider integration:

  1. Open your Bloomreach Engagement project, go to Data & Assets > Integrations > + Add new integration and search for "Twilio Messaging". Next, click + Add integration.
  2. On the next screen, you will need to populate the fields shown with your Twilio account credentials mentioned above. This will connect your Twilio account with your project.
  1. Click the Save integration button to complete your registration.
  2. You can begin using Twilio Messaging SMS/MMS integration, and configure any project level settings.

(Optional) Set default SMS provider

If your project has multiple SMS provider integrations configured, you can optionally set a default provider. Once set, all SMS campaigns will be using this one selected integration.

If you would like to set your default SMS provider, go to Project settings > Channels > SMS/MMS and select your integration of choice from the SMS provider integration drop-down field. Your user role must have admin rights to do so.

Event tracking

By default, event tracking for the Twilio Messaging SMS/MMS integration are mapped to the campaign event with action_type=sms. Alternatively, event tracking can be mapped to a different event if desired by configuring this within Project settings > Campaigns > Mapping > Campaign events.

When Bloomreach Engagement sends a SMS message with Twilio, it tracks the response. Twilio Messaging either accepts the message for delivery or rejects it. Look for error explanations in case of rejected messages.

Bloomreach Engagement tracks campaign event (or mapped event) with these properties:

event propertyvaluedescription
The message was (enqueued) or was not (enqueue_failed) successfully forwarded to the SMS provider for delivery.
status"delivered"The message was successfully delivered from the SMS provider to the recipient's handset.
The message was rejected by the SMS provider or delivery to the recipient's handset failed
number_of_message_partsNumberCount of message parts
status_codenumerical codeSee Twilio's Error and Warning Dictionary
errore.g. "syntax_invalid_parameter_format"Error code - failed requests. Error and Warning Dictionary
commente.g. "The format of a field value is invalid. For example if a MSISDN is not correctly formatted."Error message - failed requests. Error and Warning Dictionary

Twilio delivery event statuses

Twilio Messaging SMS/MMS communicates with Bloomreach Engagement to notify us about SMS message delivery event status changes. In particular, Twilio calls Bloomreach Engagement's callback with delivery reports in real-time when the end recipient's operator responds about the delivery.

Delivery events provide clarity about how many messages and when they have been delivered to recipients' handsets. Delivery events can also be used in campaign evaluation.

Engagement has the following SMS message status values listed below:

enqueuedEnqueued the SMS message to the service provider
enqueue_failedCould not enqueue the SMS message
deliveredSMS message was successfully delivered from the service provider to the end customer’s handset
sentSMS message was submitted to the network for delivery
failedSMS message not delivered, typically due to a failure or temporary problem.
rejectedSMS message was rejected for delivery by the service provider
incoming_messageInbound SMS message or reply from a campaign recipient (upon activating Two-way Messaging)
clickedCustomer clicked on a link inside the SMS (using the Campaign Link Shortener).

For additional information on error explanations in case of rejected or failed messages, see the Twilio Error and Warning Dictionary.


Waiting period

Some delivery reports may take up to 4 days to receive, depending on the operator. However, users shall not expect delivery reports to be delivered after four days after dispatching because delivery reports are tracked in the first four days after dispatching the message.


Delivery status restrictions

Some countries shall not provide delivery status reports, including these: Bangladesh, Benin, Brazil, Burundi, Cambodia, Germany, Guadeloupe, Guam, Hong Kong, Indonesia, Kuwait, Malaysia, Marshall Islands, Mauritania, Mexico, Nauru, Northern Mariana Islands, Pakistan, Panama, Papua New Guinea, Peru, Samoa, Solomon Islands, South Sudan, Sri Lanka, Sudan, Tajikistan, Timor-Leste, Tonga, Tuvalu, Uzbekistan, Venezuela, Vietnam, Wallis & Futuna Islands.