Send SMS v1

🚧

API Endpoint and Authentication

• Your API endpoint varies based on where your imiconnect account is hosted. Visit Know Your API Endpoint section to know more.

• You can use either Service Key or JSON Web Tokens (JWT) for authentication. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.

The SMS API supports batching. You can send personalized messages to a maximum of 1000 destinations at once (subject to your TPS limits). E.g., if your SMS API TPS configuration is 10 you can send messages to up to 10 destinations at once.

Prerequisites

SMS API - Samples

{
    "from":"<from address for the message, for SMS this will be a senderID>",
    "to":[
        {
            "msisdn":[
                "single/multiple destination objects of the same type"
            ],
            "correlationId":"<correlationId for this array of destination objects>",
            "substitutions":{
                "parameter1":"<substitutions for this array of destination objects> ",
                "parametern":"<substitutions for this array of destination objects> "
            }
        },
        // Pass multiple objects in a single destination array for bulk messaging
 
                // Pass one object in each destination array for personalized messaging     
                 {
            "msisdn":[
                "single/multiple destination objects of the same type"
            ],
            "correlationId":"<correlationId for this array of destination objects>",
            "substitutions":{
                "parameter1":"<substitutions for this array of destination objects> ",
                "parametern":"<substitutions for this array of destination objects> "
            }
        }
    ],
    // Global substitutions
   "substitutions":{
        "parameterx":"<global replaceable parameters, destination level parameters take precendence",

    },
 "expireAt":"<ISO8601 date/time>",
// Channel specific message options
    "options":{
        object(smsOptions)
    },
    // Call-backs
 "callbackData":"<notify data>",
"callbackUrl":"https://notify.example.com",
   "content":{
    object(smsMessage)
   },
    }  
}

{
    "from": "12233XXXXXX",
    "to": "1647XXXXXX",
    "content": "SMS API v1 ",
    "contentType": "text",
    "substitutions": {
        "name": "AVC",
        "env": "XXX",
        "key3": "string",
        "key4": "String"
    },
    "correlationId": "Piority 1",
    "callbackUrl": "https://abc.com",
    "callbackData": "SMS API v1",
    "shortenUrls": true,
    "shortUrlDomain": "https://abc.com",
    "trackShortUrlClicks": true
}

Postman Collection

Try our APIs using the Postman collection here:

👍

Generating the JWT Token

Connect uses a subset of the JWT fields, described here:

alg
A string used in the header, identifying the algorithm used to encode the payload. The alg value is always HS256 when exchanging messages with Business Chat.

iss
A claim that is a string identifying the principal that issued the JWT. The value is always the Service ID when exchanging messages with API v1.

iat
A claim that is a numeric date—that is, an integer—identifying the time at which the JWT was issued. The value is the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date and time, ignoring leap seconds. For more information, see the Terminology section in RFC 7519.

A Service Secret that is a Base64-encoded string. Decode the string before using the key to sign the JWT

A decoded JWT token should contain the following -

header
{
  "alg": HS256,
}
claims
{
  "iss": <Service ID>,
  "iat": <issued at unix-timestamp (in seconds)>
}

Body Parameters

SMS Channel

smsOptions

{
    "shortenLinks":true, //shortens any https links found in the body of the request
    "domain":"https://me.co.uk", //domain for the shorternedLink  must be preconfigured.Please reach out to the support team.
        "trackClicks":true //when shorten links is true, clicks can be tracked

}

smsMessage

Steps for configuring branded / short URLs for using 'shortenLinks' capability:

• Work with your IT team to procure the short URL you want to use.
• Add a CNAME record with relevant redirection based on your Webex Connect tenant location (table below).
• If you need HTTPS redirection (highly recommended), reach out to Webex Connect customer support team and provide the domain certificate to add to the Certificate Manager (ACM) for this purpose. This typically requires some lead time hence we recommend you to plan ahead of time for getting this set-up done and leave some time for end-to-end testing.
• Once the backend set-up has been completed by Webex Connect team, you will be notified over email post which you can start using this.

📘

Please note that usage of short domains for SMS links can have an impact on deliverability in some cases. Operators and aggregators implement various firewalls and fraud mitigation services in order to protect customers from fraud. This means URL shortening techniques can sometimes be blocked with no warning, particularly if the words around them seem fraudulent or related to a popular brand or financial entities.

Existing APIs (these APIs will continue to work for existing tenants):

New API endpoints (we recommend you use these for new tenants and services post v6.0 release):

smsMessage

{
    "type":"text or unicode",
    "text":"Hi $(name), this is a text message ${field2}" //body of the message with variables represented as $(variable)
}