Generic SMS

Overview

CleverTap supports any SMS provider via an HTTP integration, provided they support receiving messages via the HTTP protocol. In addition to this, CleverTap Generic SMS integration also supports setting up callbacks that help track detailed reports of every SMS being sent from the CleverTap dashboard like Clicked, Delivered, Replied, and Delivery-related errors.

Integrate an SMS Provider

To integrate an SMS provider, perform the following steps:

  1. In the CleverTap dashboard, navigate to Settings > Engage > Channels > SMS.
  2. Click + Add Provider.
  1. Under Provider, select Other (Generic) and enter the following details:
FieldDescription
NicknameUniquely identifies the provider
Callback URLThe delivery callback data for SMS campaigns are received on this URL. Customers must configure this URL in their SMS Provider Settings. For more information, refer to SMS Callbacks.
Request TypeSelect the GET or POST option depending on which HTTP protocol your SMS provider supports, then enter the HTTP API endpoint of the provider. For a POST request under Parameters, select your request type in:
  • Key-value pair: Enter .your keys and values.
  • JSON: Enter your entire JSON payload structure. If the service provider supports batching, you can enable batching by specifying the key name and the number of records per batch.
  • HTTP EndpointEnter the API endpoint of the provider.
    AuthenticationUnder Authentication, select one of the following options:
  • No Authentication
  • Basic Authentication: Enter the username and password.
  • Auth 2.0: Enter client URL, client ID, secret key, and key-value pairs (optional).
  • HeadersSelect Headers to pass along any HTTP headers which will be added to the HTTP request sent to the API endpoint.

    📘

    OAuth 2.0 Authentication

    In case of failure to authenticate the OAuth 2.0 credentials due to invalid or expired credentials, the CleverTap system will retry after every 120 seconds. All SMSs will fall under Dispatch Error until we successfully validate the credentials.

    Authentication Parameter for type Auth 2.0

    Authentication Parameter for type Auth 2.0

    Parameters under POST Request Type

    Parameters under POST Request Type

    📘

    Single Batch Limit

    A single batch can have a maximum of 1,000 records.

    Set Up Your Message Payload

    To determine the parameters your SMS provider supports, you can ask for a curl request from your SMS service provider or check the payload structure defined in the provider documentation.

    To set up your message payload, perform the following steps:

    1. In the CleverTap dashboard, navigate to Settings > Engage > Channels > SMS.
    2. Click on the + Add Provider button.
    3. Under Provider, select Other (Generic).
    4. If the provider specifies all information, such as a phone number, a message body, or a template, should be passed under Headers, then under Headers, enter key and value pairs.
    1. If the provider specifies all information, such as a phone number, a message body, or a template, should be passed under Body, then under Parameters, select the supported encoding:
      • x-www-form-urlencoded: Within this format, all values are passed as key-value pairs, which are used when creating campaigns.
    • JSON: Within this format, the exact payload is defined in a JSON structure. This is used to define the payload structure for all outgoing requests of this particular provider.
    JSON Payload Structure for Outgoing Requests

    JSON Payload Structure for Outgoing Requests

    System Dynamic Replacements

    You can use the following five dynamic replacements within the key-value pairs in the headers or parameters tabs:

    • $$To: A mandatory replacement value used to signify the key where the phone number is added to the payload.
    • $$Body: An optional replacement value used to signify the key where the body of the message is added to the payload. Every configuration needs to have $$Body or $$TemplateID key as a mandatory replacement.
    • $$TemplateID: An optional replacement value used to signify the key where the TemplateID of the message is added to the payload. Every configuration needs to have $$TemplateID or $$Body key as a mandatory replacement. This variable is optional and only applicable for campaigns targeted to Indian mobile numbers. Refer to the Regulation Impact guide to learn more.
    • $$TemplateVariables: An optional replacement value used to signify the key where the template variables of the message are added to the payload.
    • $$CampaignID: An optional replacement value used to signify the key where the CleverTap campaign ID is added to the payload.
    • $$MessageID: A dynamic replacement parameter replaced by CleverTap with a specific value in the outgoing SMS payload to the provider's endpoint. The provider must send the same value in the callback request to CleverTap's callback URL in the meta key. This is mandatory in case of DLR (clicks, delivered, replied, and delivery-related errors) tracking.

    Custom Dynamic Replacements

    In addition to system dynamic replacements, any configuration can have a custom dynamic replacement which is available on the campaign creation flow as a mandatory input.

    The following is an example of a configuration to better understand the setup:

    {
      "hid": "$$hid", //Global Key-Value pair
      "tid": "$$TemplateID",
      "cid": "$$CampaignID",
      "type": "template",
      "msgs": [
        {
          "seq": 1,
          "to": "$$To",
          "mid": "$$MessageID", //to be added for configuring callbacks
          "uid": "$$uid", //Message Body Key-Value pair
          "variables": "$$TemplateVariables",
          "enc": "utf8"
        }
      ]
    }
    

    The entire payload has two parts:

    1. Message Body Key-Value Pairs: The keys are seq, to, uid, variables, and enc.
    2. Global Key-Value Pairs: The keys are hid, tid, cid, and type.

    In this configuration, a single msg record will be set up in the key msgs and all the message body key-value pairs are used with a user-level personalization. On the other hand, $$hid is a custom dynamic replacement that cannot be personalized on a user level, but the value can be set for each campaign.

    Here is another example without batching:

    {
      "hid": "$$hid",//Message Body Key-Value pair
      "tid": "$$TemplateID",
      "cid": "$$CampaignID",
      "type": "template",
      "seq": 1,
      "to": "$$To",
      "mid": "$$MessageID", //to be added for configuring callbacks
      "uid": "$$uid",//Message Body Key-Value pair
      "variables": "$$TemplateVariables",
      "enc": "utf8"
    }
    

    In the example above, there is no bifurcation of the payload. Global and message key-value pairs are on the same level, and therefore, no batching is possible as each record will ping the provider individually. All dynamic replacements would be available for user-level personalization.

    📘

    Encoding

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

    SMS Callbacks

    SMS callbacks help you track detailed reports of every SMS being sent from the CleverTap dashboard. All this information is received on the Callback URL present under the Provider Setup tab on the CleverTap dashboard. For now, this feature is available only for Generic SMS Integration. If you already have a provider saved, you must set up a new one with the same configuration details along with additional information for SMS callbacks explained in the Configure SMS Callback section.

    676

    Callback URL on CleverTap Dashboard

    Configure SMS Callback

    During the SMS provider setup process, you must specify the mid key (you can have a custom name for this key) with $$MessageID as the value. $$MessageID is the dynamic replacement parameter, replaced by CleverTap with the specific value in the outgoing SMS payload to the provider's endpoint. The provider must send the same value in the callback request to CleverTap's callback URL in the meta key mentioned under Send Callback Events section.

    SMS Callback Working

    SMS Callback Working

    Sample Request

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

    Sample Request with Batching

    The following is a sample request payload structure with batching:

    {
    	"tid": "$$TemplateID",
    	"msgs": [{
    		"seq": 1,
    		"to": "$$To",
        "mid": "$$MessageID",
    		"uid": "$$uid",
    		"body": "$$Body",
    		"enc": "utf8"
    	}]
    }
    

    📘

    Batch Size Limit

    CleverTap supports a maximum batch size of 100 records.

    Sample Request without Batching

    The following is a sample request payload structure without batching:

    {
    	"tid": "$$TemplateID",
    	"to": "$$To",
    	"uid": "$$uid",
      "mid": "$$MessageID",
    	"body": "$$Body",
    	"enc": "utf8"
    }
    

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

    Key NameDescriptionSample Value (Case Sensitive)
    tidDenotes Template ID.
    An optional replacement value used to signify the key where the TemplateID of the message is added to the payload.
    Every configuration must have $$TemplateID or $$Body key as a mandatory replacement.
    This variable is optional and only applicable for campaigns targeted to Indian mobile numbers.
    Replacement - $$TemplateID

    For example, 1107160016156755389
    midDenotes Message ID.
    Metadata that CleverTap sends to the provider and receives in the incoming payload if the callbacks are configured.
    CleverTap dynamically replaces the mid with the required metadata, which is used to consume callback events and display them on the CleverTap dashboard.
    Replacement - $$MessageID

    For example, 9999999999.1200000000.1654002362.20220531.0.wzrk_default.-1.
    toA mandatory replacement value used to signify the key where the phone number is added to the payload.$$To
    bodyA replacement value used to signify the key where the Body of the message is added to the payload$$Body

    Send Callback Events

    To send callback events to CleverTap, customers must send a POST request to CleverTap's callback URL. The following is the acceptable callback payload structure:

    [{
            "event": "failed", //in the case of errors in delivery
            "data": [{
                    "ts": <10-digit Epoch Timstamp in seconds>,
                    "meta": "<replaced by value received in $$MessageID in the outbound SMS payload>",
                    "code": "<ErrorCode>",
                    "description": "<error description>"
                },
                {
                    "ts": <10-digit Epoch Timstamp in seconds>,
                    "meta": "<replaced by value received in $$MessageID in the outbound SMS payload>",
                    "code": "<ErrorCode>",
                    "description": "<error description>"
                }
            ]
        },
     {
            "event": "replied", //in the case of response from the SMS recipient
            "data": [{
                "ts": <10-digit Epoch Timstamp in seconds>,
                "meta": "<replaced by value received in $$MessageID in the outbound SMS payload>",
                "toPhone": "<The number to which the user replied>",
          			"incomingText": "<Reciepient's response text>"
            }
        ]
        },
        {
            "event": "delivered", //in the case of successful delivery. 
            "data": [{
                "ts": <10-digit Epoch Timstamp in seconds>,
                "meta": "<replaced by value received in $$MessageID in the outbound SMS payload>",
                "description": "Delivered to handset"
            }]
        },
        {
            "event": "clicked", //when the user clicks on the links in the SMS.
            "data": [{
                "ts": <10-digit Epoch Timstamp in seconds>,
                "meta": "<replaced by value received in $$MessageID in the outbound SMS payload>",
                "url": "www.CleverTap.com", //This is the original URL
                "shortUrl": "<short URL from the provider shortened using URL Link shortener>" 
            }]
        }
    ]
    

    The following table provides a brief description of the keys present in the callback payload:

    Key NameDescriptionSample Values
    event*Denotes the event name.failed/replied/clicked
    ts*Denotes the timestamp in Unix Epoch format.1654512921
    meta*Denotes information that CleverTap uses for attributing delivered, clicked, errors, etc., to respective campaigns, profiles, and sms providers. Must be passed as is to CleverTap callback URL.9999999999.1200000000.165263328.20220606.0.wzrk_default.1.
    code*Includes error code in case of an error in SMS delivery.900, 901
    description*Description of callback event in case of failure or successful delivery.For example: “sender blocked by DLT”
    toPhoneThe number to which the user replied.5555
    incomingText*User-originated message text. It is the reply string in case of a replied event. This key is mandatory in case of a replied event.STOP, START
    url*URL in case of the click eventwww.CleverTap.com
    shorturlShort URL in case the outbound URL has been shortened.https://bit.ly/3OjG22B

    *The asterisk mark against the key name indicates that keys are mandatory in the callback payload.

    📘

    Note

    If the payload includes additional key-value pairs apart from the ones that are defined in the acceptable sample payload for each event, CleverTap does not throw any errors, but simply disregards those.

    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 within the campaign stats section in case of any delivery-related failures. The following table provides information about the acceptable error codes:

    Error CodeError DescriptionDetails
    901DND failureDND Failure refers to a scenario where a text message was not delivered to a recipient due to their phone number being registered on the national Do Not Disturb (DND) registry, which contains a list of phone numbers that have opted out of receiving promotional or marketing messages.
    902Failed spam detectedOne of the most common reasons for SMS delivery failure is carrier-level spam filters. Carriers have added systems and algorithms that detect spam content and then block these messages. Unfortunately, these filters are hidden, subject to carrier preferences, vary from carrier to carrier, and can be changed without notice.
    903Failed rejected blacklistThe user has already sent a STOP/DND opt-out message and no longer wishes to receive messages from you. Other reasons could be illegal use of the number, nonpayment of bills, number belonging to VIPs, government order to stop SMS to the number, complaints from other mobile users about that number, or user complains to the operator/TRAI regarding unsolicited SMS being received.
    904Failed system errorSMS failed while processing within your SMS Providers system.
    905Failed subscriber errorProblems with subscribers or recipients that are not related to their device, such as a lack of mobile balance or poor network to receive the SMS.
    906Blocked by DLTApplicable only for SMS sent to Indian destination numbers via domestic lines. Sender ID (Header) is blocked or failed at the DLT platform by the operator due to mismatch, non-registration, template not linked with Sender (header), etc.
    907Entity blocked by DLTApplicable only for SMS sent to Indian destination numbers via domestic lines. Entity (DLT Entity ID) is blocked or failed at the DLT platform by the operator due to DLT Entity ID not being passed in API or configured on your SMS Providers Dashboard, values are mismatching, etc.
    908Template blocked by DLTApplicable only for SMS sent to Indian destination numbers via domestic lines. Template (Template ID) is blocked or failed at DLT due to Template ID not set in API or configured on your SMS Providers Dashboard, content is not exactly matching, non-registration of the template, etc.
    909Failed DLT consent errorThe SMS DLT consent registration is required for you to continue sending SMS to your customers. Applicable only for SMS sent to Indian destination numbers via domestic lines.
    910Invalid subscriberInvalid/Inactive number. The number is either not a valid phone number, or it is no longer active.
    912Message Inbox FullThe user's inbox was full at the time of delivery.
    913NDNC RejectedNumber registered in NCPR database as DND.
    914UndeliveredMessage delivery failed after multiple retries due to operator/end-user issues.
    915DroppedNumber banned by Indian Govt as it belongs to J&K (Jammu and Kashmir) series. Other reasons could be SMS dropping by the operator due to no usage of SIM i.e. no voice calls (incoming and outgoing), SMS, and data continuously for 60 days from the date of the first call.
    916ExpiredThe message was undelivered after multiple retries from the Operator because of the issues at the operator's end.
    917Force ExpiredThe message dropped due to one of the following reasons:
  • SMS provider’s rule
  • Invalid numbers in the uploaded base, or
  • The client has requested to drop.
  • 918Duplicate Message DropThe SMS provider dropped the duplicate message, as the same message content was attempted to be sent on the same mobile number within 30 minutes.
    919DLT FailureFailed due to some issue at the DLT platform level.

    🚧

    Error Code 900

    Any errors not specified in the above table must be sent with the status code 900 along with the corresponding error description in the incoming payload. The following is the sample payload for error code 900:

    [{
    	"event": "failed",
    	"data": [{
    		"ts": 1435322805,
    		"meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
    		"code": "900",
    		"description": "Not able to send message to this phone"
    	}]
    }]
    

    Sample Payload

    The following is the acceptable sample payload:

    [{
            "event": "failed", //in the case of errors in delivery 
            "data": [{
                    "ts": 1654512921,
                    "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
                    "code": "901",
                    "description": "DND Failure"
                },
                {
                    "ts": 1654512921,
                    "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
                    "code": "902",
                    "description": "Failed spam detected"
                }
            ]
        },
     {
            "event": "replied",
            "data": [{
                "ts": 1435322805,
                "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
                "toPhone": "5555",
          			"incomingText": "STOP"
            }
        ]
        },
        {
            "event": "delivered", //in the case of successful delivery. 
            "data": [{
                "ts": 1435322805,
                "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
                "description": "Delivered to handset"
            }]
        },
        {
            "event": "clicked", //when the user clicks on the links in the SMS.
            "data": [{
                "ts": 1435322805,
                "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
                "url": "www.CleverTap.com", //This is the original URL
                "shortUrl": "https://bit.ly/3OjG22B" 
            }]
        }
    ]
    

    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.

    Event NameSample Payload StructureMapping to CleverTap System Events
    Notification Delivered[{
    "event": "delivered",
    "data": [{
    "ts": 1435322805,
    "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
    "description": "Delivered to handset"
    }]
    }]
    Maps to Notification Delivered event. For more information, refer to Events.
    Notification Clicked[{
    "event": "clicked",
    "data": [{
    "ts": 1435322805,
    "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
    "url": "www.CleverTap.com",
    "shorturl": "ct9.io/12345"
    }]
    }]
  • Value of the url key in the payload is populated in the wzrk_c2a event property of the Notification Clicked event.
  • Value of the shorturl key in the payload is populated in the wzrk_c2a_short_url event property of the Notification Clicked event.
  • For more information, refer to Events.
  • Notification Replied[{
    "event": "replied",
    "data": [{
    "ts": 1435322805,
    "meta": "9999999999.1200000000.165263328.20220606.0.wzrk_default.1.",
    "toPhone": "5555”,
    "incomingText": "This is the user's response(512 chars only)"
    }]
    }]
    Value of incomingText in the payload is populated in the Notification Replied event. For more information, refer to Events.

    📘

    Notification Replied

    CleverTap trims the string within the incomingText parameter of the Notification Replied event containing more than 512 characters.

    Response Codes

    CleverTap sends the following status codes and descriptions as a response to the SMS provider upon receiving callbacks:

    Status CodeDescriptionExplanation
    200-Success.
    400Bad request. Some mandatory parameter was missing.Occurs when any of the mandatory keys are missing from the payload or n case of issues in the payload format.
    500Server errorCleverTap internal server error. Contact CleverTap support if the issue persists.
    503Service UnavailableCleverTap internal server error. Contact CleverTap support if the issue persists.

    📘

    Retry Mechanism for Errors

    In case of HTTP 5XX errors, we recommend retrying after 10 minutes with exponential backoff as CleverTap does not deduplicate requests.

    Sample Payload

    The following is the payload structure sent by CleverTap to the providers upon receiving the payload:

    {
    	"status": "<success, partial, fail>",
    	"processed": "<count// should be sent as long int>",
    	"unprocessed": [{
    	"status": "fail",
    	"code": "<error code>",
    	"error": "<error description>",
    	"record": "<record>"
    	}]
    }
    

    The following is the sample success payload:

    {
        "status": "success",
        "processed": 1,
        "unprocessed": []
    }
    

    The following is the sample error payload:

    {
        "status": "fail",
        "processed": 0,
        "unprocessed": [
            {
                "status": "fail",
                "code": 400,
                "error": "Bad Request. Some mandatory parameter was missing",
                "record": {
                    "event": "failed",
                    "data": [
                        {
                            "ts": 1686138005,
                            "meta": "919632453300.1656678144.1686137940.20230607.0.wzrk_default.-1092441.",
                            "description": "NDNCRejected"
                        }
                    ]
                }
            }
        ]
    }
    

    Stats

    CleverTap displays comprehensive stats such as Errors, Delivered, Clicked, and CTRs upon receiving callbacks from the SMS service provider. 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 Setup.
    SMS Campaign Stats

    SMS Campaign Stats

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