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.

3. Under Provider, select Other (Generic) and enter the following details:

📘

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.

📘

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.

4. 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.

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.

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.

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:

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:

*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 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:

JSON

[{
	"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.

📘

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:

📘

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.

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