Send SMS v1

🚧

API Endpoint and Authentication

  • Your API endpoint varies based on where yourWebex Connect 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.For more information refer Generating the JWT token.

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.

Supported Channels

ChannelPrerequisite
SMSSender ID - A Sender ID is a name or number that an SMS appears to come from (‘from address’) when you receive a message on your phone.

A sender ID can be alpha-numeric or a short-code or a long-code depending on demographical restrictions.

Postman Collection

Here is a Postman collection to test our APIs.

Latest Collection: Run in Postman

Archived Collection: Refer Postman Collection

Download Postman from here

Error Codes

Refer to this page

SMS API - Samples

{
	"from":"<from address for the message, for SMS this will be a senderID>",
	"to":"<phone number/msisdn to which the SMS has to be sent>",
	// Global substitutions
  "substitutions":{
	"parameterx":"<global replaceable parameters, destination level parameters take precendence",
	},
  "expireAt":"<ISO8601 date/time>",
	// Call-backs
  "callbackData":"<notify data>",
  "callbackUrl":"https://notify.example.com",
  "content":"<body of the message>",
  //supported values: text, unicode, binary, template
  "contentType": "text", 
  "correlationId": "<correlation id of the destination>",
  "dltTemplateId": "<template ID>",
  // supported values : true or false
  "shortenUrls": true,
  "shortUrlDomain": "<Domain configuration for shortening the links>",
   //supported values : true or false
  "trackShortUrlClicks": true,
  	],
		"gtrId":"rcsgtrid"
}
{
    "from": "12233XXXXXX",
    "to":"+1647XXXXXXX",  //E.164 format required/recommended. Older tenants might still accept other formats.
    "content": "SMS API v1 ",
    "contentType": "text",
    "substitutions": {
        "name": "AVC",
        "env": "XXX",
        "key3": "string",
        "key4": "String"
    },
    "correlationId": "Piority 1",
    "dltTemplateId": "2kRCRhhxOmT28jMn",
    "callbackUrl": "https://abc.com",
    "callbackData": "SMS API v1",
    "shortenUrls": true,
    "shortUrlDomain": "https://abc.com",
    "trackShortUrlClicks": true,
    "expireAt": "2023-03-20T14:24:33.000Z"
}

Body Parameters

ParameterTypeMandatoryDescription
fromstringyessms - Sender ID
tostringyesphone number/msisdn to which the SMS has to be sent
contentstringyes, if template is not providedbody of the message
contentTypestringnoDenotes whether the content string is the actual text content to be sent or a reference to a template ID.

Please note that 'text' supports many common special characters as per the SMS specification and is preferred where possible. Using 'unicode' enables the use of multi-byte encoding, that allows full character set and emoji support, but results in 2 or 3 times more SMS traffic than plain SMS text.
substitutionsJSONObjectnoa JSON object with global substitutions.
correlationId stringnoUser defined ID that is assigned to an individual message
dltTemplateId stringnoSpecifies the DLT template ID used for this message. This is only used in certain regions.
callbackUrl stringnoIf provided, events related to the delivery of this message will be POSTed to this URL.
callbackDatastringnoA string that is returned with each outbound web-hook for the message (delivery, failed etc). Maximum number of characters allowed in callbackData including any spaces is 2000.
expireAtdate/timenoIS08601 time format for when the message has to be expired and failed if not delivered

For example,
2021-06-26T13:47:18.000Z - UTC
2021-06-26T13:47:18.000+05:30 - with timezone
* 1624782447 epoch timestamp
shortenUrlsbooleannoWhen enabled, this shortens any https links found in the body the message request
shortUrlDomainstringnoDomain configuration for shortening the links. Needs to be configured through Support team.
trackShortUrlClicksbooleannoWhen shortenUrls is true, you can receive CLICKED receipts on your notifyUrl if trackShortUrlClicks is true. Clicked format available here

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

Webex Connect RegionCNAMERedirect To
AWS Canadastar-1176184099.ca-central-1.elb.amazonaws.comhttps://track.imiconnect.ca:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Irelandstar-1747495833.eu-west-1.elb.amazonaws.comhttps://track.imiconnect.io:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Londonstar-1656037958.eu-west-2.elb.amazonaws.comhttps://track.imiconnect.eu:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Oregonstar-1571873968.us-west-2.elb.amazonaws.comhttps://track.us.webexconnect.io:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
Azure (US)52.138.107.55 (A Record)https://track.imiconnect.us/ump-sltrack/TrackServlet?p=https://#{host}
AWS Mumbaistar-64546195.ap-south-1.elb.amazonaws.comhttps://track.imiconnect.in:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Sydneystar-131871454.ap-southeast-2.elb.amazonaws.comhttps://track.imiconnect.com.au:443/ump-sltrack/TrackServlet?p=https://#{host}/#{path}

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

Webex Connect RegionCNAMERedirect To
AWS Canadastar-1176184099.ca-central-1.elb.amazonaws.comhttps://track.imiconnect.ca/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Irelandstar-1747495833.eu-west-1.elb.amazonaws.comhttps://track.imiconnect.io/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Londonstar-1656037958.eu-west-2.elb.amazonaws.comhttps://track.imiconnect.eu/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Oregonstar-1571873968.us-west-2.elb.amazonaws.comhttps://track-us.imiconnect.io/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
Azure (US)52.138.107.55 (A Record)https://track.imiconnect.us/ump-sltrack/TrackServlet?p=https://#{host}
AWS Mumbaistar-64546195.ap-south-1.elb.amazonaws.comhttps://track.imiconnect.in/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
AWS Sydneystar-131871454.ap-southeast-2.elb.amazonaws.comhttps://track.imiconnect.com.au/ump-sltrack/TrackServlet?p=https://#{host}/#{path}
Language