Twilio

SMS Provider

Introduction

Twilio is a leading communication platform that empowers businesses to connect with their users through various channels, including SMS. This document highlights the integration of CleverTap and Twilio, empowering businesses to elevate their SMS communication using Twilio's infrastructure.

Prerequisites for Integration

Before you begin with integration, ensure you have:

  • A Twilio account with SMS permissions
  • A CleverTap account with SMS setup enabled

Twilio Setup

This process involves the following three significant steps:

  1. Find Twilio Details
  2. Add Twilio Details on CleverTap Dashboard
  3. Send a Test SMS

Find Twilio Details

CleverTap recommends keeping the Twilio account handy before configuring it on the CleverTap dashboard. To locate these details, navigate to the Console page from the Twilio dashboard:

  • Account SID
  • Auth Token
  • My Twilio phone number
Twilio Account Details

Twilio Account Details

Add Twilio Details on CleverTap Dashboard

To add Twilio details on the CleverTap dashboard:

  1. From the CleverTap Dashboard, navigate to Settings > Channels > SMS.
  2. Click +Add Provider. The Add SMS provider page opens.
Add SMS Provider

Add SMS Provider

  1. Under Setup, enter the following details:
FieldDescription
NicknameUniquely identifies the provider.
Account SIDEnter your account identifier from the Twilio dashboard. This is a unique key to distinguish a specific Twilio parent account or subaccount. For more information, refer to Twilio Account SID.
Auth tokenEnter the Auth Token (Password) obtained from the Twilio dashboard. For more information, refer to Auth Token.
Callback URLEnter the URL where delivery or error callbacks must be posted after sending the SMS. By default, CleverTap's callback URL will be pre-populated. If you wish to send the callbacks to a custom URL instead, you can also set it here. For more information on setting a custom callback URL, refer to Custom callback URL.

Note: This feature is currently in Public Beta.
RestoreClick Restore to reinstate CleverTap's callback URL. This will remove any custom callback URLs.
From NumberEnter phone numbers obtained under the Twilio console → Manage-numbersActive number section.
Service SID (Copilot)Enter Service SID details obtained from the Twilio dashboard. The Copilot Service SID, a Twilio identifier, streamlines message management. It automates number selection and formatting, enhancing engagement by optimizing message delivery based on location and carrier requirements.
Template IDIt is a unique template ID for each SMS template that you want to use. Selecting this option will make it mandatory to input the template ID when saving the provider.
Mark as defaultSelect Mark this as default to make this SMS provider the default provider to send the SMS.
Add Twilio as a SMS Provider

Add Twilio as an SMS Provider

  1. Click Save to save the details.

Send a Test SMS

To ensure that the integration is successful, send a test SMS as follows:

  1. Click the Send Test SMS hyperlink before creating SMS campaigns and journeys.
  2. Enter the following details:
    • Country Code and Mobile Number: Enter the country code and mobile number to which you want to send the message.
    • Message: This is a test message.
Send a Test SMS

Send a Test SMS

🚧

Twilio Trial Account

With a Twilio trial account, you can only send SMS campaigns only to numbers registered on the Twilio dashboard.

📘

Encoding

The messages sent out from CleverTap are encoded in the UTF-8 charset.

Twilio Callbacks

📘

Public Beta

Currently, this feature is in Public Beta.

The Twilio callback functionality enhances the tracking of SMS interactions originating from the CleverTap dashboard. Twilio's webhooks allow your Twilio phone number to receive incoming text messages. Within CleverTap's setup, the Callback URL is seamlessly generated and prefilled in the provider configuration under Settings > Channels > Email > +Provider. Users can replace this URL with their own, which must be configured on our end to receive callbacks.

The callback mechanism between Twilio and CleverTap is designed to facilitate communication regarding SMS status updates. The Clevertap callback URL tracks for Delivered (SMS delivered to the user), Failed (SMS delivery error), and Replied (user response to SMS) events from Twilio.

Default Callback URL

In the default setup, Twilio directly sends the information to CleverTap's callback URL. The flow involves the following steps:

  1. Twilio generates the callback.
  2. Twilio sends the callback directly to CleverTap on the default URL.
  3. CleverTap processes the callback.
  4. Upon receiving callbacks from Twilio, the comprehensive stats are displayed on the CleverTap dashboard. For more information, refer to Stats.
SMS Default Callback Working

Twilio SMS Callback Working for Default URL

Custom Callback URL

Twilio sends the callback to a custom URL, which may belong to your customer. The customer is then responsible for replaying the callback to CleverTap. The flow is as follows:

  1. Twilio generates the callback.
  2. Twilio sends the callback directly to the customer's custom URL.
  3. The customer's custom URL relays the callback to CleverTap.
  4. CleverTap processes the callback.
  5. Upon receiving callbacks from Twilio, the comprehensive stats are displayed on the CleverTap dashboard. For more information, refer to Stats.
SMS Custom Callback Working

Twilio SMS Callback Working for Custom URL

📘

Callback Data Passing

When the callback is sent through a custom URL, CleverTap's callback endpoint requires all fields from the request payload received from Twilio to be relayed back exactly as received.

Set Up Message Payload

In the Twilio callback integration with CleverTap, you can access dynamic parameters provided by Twilio in callback updates. This applies specifically when using a custom callback URL. Twilio provides meta details that should be forwarded to CleverTap as part of the integration.

  • Key Name: meta
  • Description: Denotes information that CleverTap uses for attributing delivery, failure, etc., to specific campaigns, profiles, and SMS providers is included in the callback update by CleverTap. CleverTap passes this parameter in the ongoing SMS to Twilio, and Twilio, in turn, passes the same parameter back to the callback URL.
  • Sample Value: 919101699729.1200000000.1691686363.20230810.0.wzrk_default.-493000

Sample Request Payload

This section provides information about the sample request payload sent to SMS providers.

Delivered

The following is a sample request payload for Delivered from Twilio.

curl --location 'https://sk1.cb.wzrkt.com/sms/twilio?account=ABC-DEF-WWRZ&meta=9999999999.1200000000.1691686363.20230810.0.wzrk_default.-4930006' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'RawDlrDoneDate=2308102223' \
--data-urlencode 'SmsSid=SMXXXXXXXXXXXXX' \
--data-urlencode 'SmsStatus=delivered' \
--data-urlencode 'MessageStatus=delivered' \
--data-urlencode 'To=00000000000' \
--data-urlencode 'MessagingServiceSid=MGXXXXXXXXXXXX' \
--data-urlencode 'MessageSid=SMXXXXXXXXXXXX' \
--data-urlencode 'AccountSid=AC0000000000' \
--data-urlencode 'From=0000000000' \
--data-urlencode 'ApiVersion=2010-04-0'

Replied

The following is a sample request payload for Replied from Twilio.

curl --location 'https://sk1.cb.wzrkt.com/sms/twilio?account=ABC-DEF-WWRZ&meta=000000000.1200000000.1691686363.20230810.0.wzrk_default.-4930006' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'ToCountry=US' \
--dat	a-urlencode 'ToState=MA' \
--data-urlencode 'SmsSid=SMXXXXXXXXXXXXX' \
--data-urlencode 'FromState=CA' \
--data-urlencode 'FromCity=SAN+FRANCISCO' \
--data-urlencode 'FromCountry=US' \
--data-urlencode 'SmsStatus=received' \
--data-urlencode 'Body=Test+Reply+Message+2' \
--data-urlencode 'To=00000000000' \
--data-urlencode 'MessagingServiceSid=MGXXXXXXXXXXXX' \
--data-urlencode 'MessageSid=SMXXXXXXXXXXXX' \
--data-urlencode 'AccountSid=AC000000000000' \
--data-urlencode 'From=00000000000' \
--data-urlencode 'ApiVersion=2010-04-0'

The following table provides information about the key-value pair present in the above sample request:

Key NameDescriptionSample Value
RawDlrDoneDate
  • Available on SMS Delivered or Undelivered events only.
  • This parameter is a passthrough of the Done Date included on the DLR (Delivery Receipt) that Twilio receives from its carrier partners.
  • It takes the format of YYMMDDhhmm where: YY = last two digits of the year (00-99), MM = month (01-12), DD = day (01-31), hh = hour (00-23), mm = minute (00-59)
  • 2302172359
    SmsSid
  • Same value as MessageSid.
  • Deprecated and included for backward compatibility.
  • SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    MessageStatus
  • Indicates the status of the message.
  • The following are the possible values: be sent, failed, delivered, undelivered, and received.
  • delivered
    SmsStatus
  • Same as the MessageStatus value.
  • Deprecated and included for backward compatibility.
  • delivered
    AccountSidThe 34-character ID of the Account the message is associated with.ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    MessagingServiceSidThe 34-character ID of the Messaging Service associated with the message.MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    FromThe phone number or channel address that sent this message.+14017122661
    ToThe phone number or channel address of the recipient.+15558675310
    NumMediaThe number of media items associated with your message0
    FromCityThe city of the sender.SAN FRANCISCO
    FromStateThe state or province of the sender.CA
    FromZipThe postal code of the called sender.94103
    FromCountryThe country of the named sender.US
    ToCityThe city of the recipient.SAUSALITO
    ToStateThe state or province of the recipient.CA
    ToZipThe postal code of the recipient.94965
    ToCountryThe country of the recipient.US

    For more information, refer to Twilio's request parameter.

    Incoming Payload Mapping to System Events

    CleverTap maps the following incoming payloads with their respective system events. You can view these on the CleverTap dashboard.

    EventSample Payload StructureMapping to CleverTap System Events
    Notification Deliveredcurl --location 'https://sk1.cb.wzrkt.com/sms/twilio?account=ABC-DEF-WWRZ&meta=9999999999.1200000000.1691686363.20230810.0.wzrk_default.-4930006' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'RawDlrDoneDate=2308102223' --data-urlencode 'SmsSid=SMXXXXXXXXXXXXX' --data-urlencode 'SmsStatus=delivered' --data-urlencode 'MessageStatus=delivered' --data-urlencode 'To=00000000000' --data-urlencode 'MessagingServiceSid=MGXXXXXXXXXXXX' --data-urlencode 'MessageSid=SMXXXXXXXXXXXX' --data-urlencode 'AccountSid=AC0000000000' --data-urlencode 'From=0000000000' --data-urlencode 'ApiVersion=2010-04-0'Maps to Notification Delivered event. For more information, refer to Events.
    Notification Repliedcurl --location 'https://sk1.cb.wzrkt.com/sms/twilio?account=ABC-DEF-WWRZ&meta=000000000.1200000000.1691686363.20230810.0.wzrk_default.-4930006'
    --header 'Content-Type: application/x-www-form-urlencoded'
    --data-urlencode 'ToCountry=US'
    --dat a-urlencode 'ToState=MA'
    --data-urlencode 'SmsSid=SMXXXXXXXXXXXXX'
    --data-urlencode 'FromState=CA'
    --data-urlencode 'FromCity=SAN+FRANCISCO'
    --data-urlencode 'FromCountry=US'
    --data-urlencode 'SmsStatus=received'
    --data-urlencode 'Body=Test+Reply+Message+2'
    --data-urlencode 'To=00000000000'
    --data-urlencode 'MessagingServiceSid=MGXXXXXXXXXXXX'
    --data-urlencode 'MessageSid=SMXXXXXXXXXXXX'
    --data-urlencode 'AccountSid=AC000000000000'
    --data-urlencode 'From=00000000000'
    --data-urlencode 'ApiVersion=2010-04-0'
    Value of Body in the payload is populated in the Notification Replied event. For more information, refer to Events.

    Error Codes

    If there is an error in the SMS delivery, these error codes indicate the nature of an error encountered. Each error code corresponds to a specific error description. The error descriptions are displayed within the Errors tab in the campaign stats section in case of delivery-related failures. The following table provides information about the acceptable error codes:

    Error CodesError DescriptionDetails
    30001Queue overflowIndicates that the rate limit was exceeded for sending messages, causing the queue to overflow. To resolve this issue, please wait a while before sending your message again.
    30002Account suspendedIndicates that the account was temporarily suspended between sending the message and its delivery. Kindly get in touch with Twilio for further assistance.
    30003Unreachable destination handsetIndicates that the recipient's mobile device is either turned off or presently not reachable.
    30004Message blockedIndicates that the recipient's number you are attempting to contact is blocked from receiving this message, possibly due to being blacklisted.
    30005Unknown destination handsetIndicates that the attempt to reach the specified number encounters an unfamiliar recipient, which may suggest an invalid or non-existent contact.
    30006Landline or unreachable carrierIndicates that the destination number is unable to receive this message. This can arise when contacting a landline or encountering an unreachable carrier, particularly with shortcodes.
    30007Carrier violationIndicates that the carrier has detected the message content as objectionable, prompting the activation of content or spam filtering to safeguard their subscribers. For a deeper understanding of carrier filtering, consult supplementary resources.
    30008Unknown errorThis error does not conform to any predefined categories mentioned above.
    30009Missing segmentIndicates that one or more segments associated with your multipart inbound message were not received.
    30010Message price exceeds the max priceIndicates that the cost of the message surpasses the maximum price parameter set.
    21614Invalid Mobile NumberIndicates that the user's number is not valid.
    21610Unsubscribed recipientIndicates that the individual you are attempting to message has chosen not to receive messages from your Twilio phone number, Channels sender, or Messaging Service.

    Sample Payload

    The following is a sample error payload:

    curl --location 'https://sk1.cb.wzrkt.com/sms/twilio?account=WWW-WWW-WWRZ&meta=000000000.1200000000.1691686363.20230810.0.wzrk_default.-4930006' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'ErrorCode=30005' \
    --data-urlencode 'SmsSid=SMXXXXXXXXXXXXXXXXXXXXXXX' \
    --data-urlencode 'SmsStatus=failed' \
    --data-urlencode 'MessageStatus=failed' \
    --data-urlencode 'To=000000000000' \
    --data-urlencode 'MessagingServiceSid=MGXXXXXXXXXXXX' \
    --data-urlencode 'MessageSid=SMXXXXXXXXXXXXXXX' \
    --data-urlencode 'AccountSid=AAAAAAA000000' \
    --data-urlencode 'From=0000000000' \
    --data-urlencode 'ApiVersion=2010-04-0'
    

    Stats

    CleverTap displays comprehensive stats such as Errors, Delivered, Clicked, and CTRs upon receiving callbacks from Twilio. After setting up the provider on the CleverTap dashboard, you can view these statistics from the following pages on the CleverTap dashboard:

    • Stats tab of the Campaigns. For more information, refer to SMS Stats.
    Twilio Campaign Stats

    Twilio Campaign Stats

    📘

    Note

    The stats for Clicked event is available only if you use CleverTap's Click Tracking feature.

    • Stats tab under Provider setup. For more information, refer to the Provider Stats.
    Twilio Campaign Stats

    Twilio Provider Stats

    You can also analyze the Notification Delivered and Notification Replied events by navigating to the Analytics > Events page, as shown in the following image:

    Analyze Notification Delivered

    Analyze Notification Delivered

    Analyze Incoming Text

    Analyze Notification Replied