Send Message API v2

Understand how you can use Send Message API v2 for sending SMS messages.

📘

API Endpoint & Postman Collection

SMS channel is supported via Send SMS API v1, Send Message API v2, and Send Message API v1. Refer to this page for information on which API is best suited for your use case.

API endpoint for it is:[https://{YourRegion}.webexconnect.io/v2/messages].

Please modify YourRegion in the URL to reflect your tenant’s region. See Know your endpoint page.

Refer to our Postman Collection here for trying Send Message API v2.

Authentication

Refer this page for information on API Authentication.

📘

API Response and Error Codes

The Send Message API v2 API is an asynchronous API. The HTTP response confirming acceptance of your request is sent as soon as you invoke the API. However, the subsequent request processing details are notified via the callback i.e., notify URL mentioned in your API request. Refer to this pagefor more information.

Request Body to Send SMS Using Send Message API v2

{
	"channel": "sms", //Mandatory. 
	"from": "{{from}}", //Mandatory. E.164 format required/recommended.
	"to": [
		{
			"msisdn": [
				"{{msisdn}}" //Mandatory. E.164 format required/recommended.
			],
			"substitutions": { //Optional. Takes precedence over the substitutions block that is outside the 'to' block, in case these values are provided in both the places. Typically useful when using SMS batching with the need to personalize SMS for each recipient.
				"{{sms_parameter1}}": "{{sms_value1}}",
				"{{sms_parameter2}}": "{{sms_value2}}"
			},
			"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
		}
	],
	"substitutions": { //Optional.
		"{{sms_parameter3}}": "{{sms_value3}}",
		"{{sms_parameter4}}": "{{sms_value4}}"
	},
	"options": { //Optional.
		"trackClicks": "true",
		"shortenLinks": "true",
		"domain": "https://s.imiconnect.co"
	},
	"requestedReceipts": [ //Optional.
		"SUBMITTED",
    "SENT",
		"DELIVERED",
		"CLICKED", //Applicable only when shortenLinks and trackClicks feature is being used.
    "FAILED"
	],
	"content": {
		"type": "text", //Mandatory. 
		"text": "This is sample content" //Mandatory.
	},
	"sendAt": "{{TimeinUTC}}", //Optional. For e.g., YYYY-MM-DDThh:mm:ss.sZ
	"expireAt": "{{TimeinUTC}}", //Optional. For e.g., YYYY-MM-DDThh:mm:ss.sZ
	"validity": "time period in seconds", //Optional. For e.g., 60 for 60 seconds
	"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
	"notifyUrl": "", //Optional.
	"contactPolicy": { //Optional. JSON Object to specify contact policy checks before sending the outbound SMS. 
		"contactPolicyGroup": "", //The GroupID to be applied. Required if any of the following options are included and set to true.
		"channelCheckConsent": true, //Optional. Assumed false if not specified. Set to true to require opt-in before sending the message. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
		"channelApplyFrequencyCap": true //Optional. Assumed false if not specified. Set to true to enforce group frequency cap for that channel. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
	}
}

Send Message API v2 Body Parameters

The following are the parameters of the request body:

ParameterTypeMandatoryDescription
channelstringyesThe value needs to be 'sms' when sending SMS messages.
fromstringyesSMS Sender ID, i.e., the long code, short code, or the Sender ID to be used for sending the message.
toJSONArrayyesAn array of destination JSON objects that contain the mandatory destination msisdn, optional personalised substitutions, and correlationId for each destination object.
msisdnJSONArrayyesPhone number, i.e., msisdn to which the SMS has to be sent in E.164 format e.g., +44XXXXXXXXXX

Note: If +E.164 format is enabled for your tenant - all the numbers in the to field should follow the "+E.164" format.
This format displays the number with a "+" followed by the country code and the phone number.
+E.164 format does not apply to the numbers in the from field.
correlationIdstringnoUser defined ID that is assigned to an individual message for unique identification.
substitutionsJSONObjectnoList of key-value pairs for dynamic fields in the SMS message content. They are typically used for specifying the values for dynamic fields in an SMS template.
optionsJSONObjectnoA JSON object that contains additional, SMS-specific options such as trackClicks, shortenLinks, and domain in the API.
trackClicksbooleannoYou can receive ‘CLICKED’ notifications for shorten links on your notifyUrl by enabling trackClicks. You can also receive them on your SMS webhook if the ‘Clicked’ option is selected.
The ‘trackClicks’ option is set to ‘false’ by default.
Clicked format available here .
shortenLinksbooleannoWhen enabled, this shortens any HTTPS links in the message request's body. For more information, refer to configure shortenLinks section .
domainstringyesIt is the domain configuration for shortening the links.
Note: 'domain' is mandatory only when 'options' object is used in the payload.
requestedReceiptsJSONArraynoA JSON array that can filter message delivery webhooks to the notifyUrl.

Can contain one or more of the following:
"SUBMITTED",
"SENT",
"DELIVERED",
"CLICKED",
"FAILED"

Check Outbound Webhooks for delivery receipt samples.
contentJSONObjectyes, if the template is not providedIt is the JSON object that contains mandatory parameters 'type' and 'text' for SMS channel.
typestringyesUsed for specifying the message content type. Acceptable values are: 'text' and 'unicode'.

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, which allows full character set and emoji support, but results in 2 or 3 times more SMS traffic than plain SMS text.
textstringyesThe SMS message content. A maximum of 1024 characters can be supported.
sendAtstringyesThe timestamp for sending the message when scheduling ahead of time. You can schedule a message upto 7 days in advance.

For example, 2024-09-26T13:47:18.000Z - UTC
expireAtstringyesTimestamp post which the message has to be expired and not sent to the intended recipient, in case the Send SMS request is yet to be processed.

For example, 2024-09-26T13:47:18.000Z - UTC
validitystringyesThe time period is in seconds. E.g., 60 for sixty seconds.

Only one of 'expireAt' or 'validity' should be sent in the request. The request will not be accepted if both values are present in the payload.

If both, 'sendAt' and 'validity parameters' are present in the same request, the validity time period will be added to the 'sendAt time' to decide the expiry time.
callbackDatastringnoA string that is returned with each outbound webhook for the message (delivery, failed, etc.). The maximum number of characters allowed in callbackData including any spaces is 2000.
notifyUrlstringnoIf provided, updates related to the delivery status of this message will be posted to this URL. Refer to this page for notification samples.
templateJSONObjectyes, if content is not providedThis is a JSON object which contains the mandatory 'ID' parameter. The value for the 'ID' parameter is the unique template ID of the configured SMS template on the UI.
contactPolicyJSONObjectnoJSON Object to specify contact policy checks before sending the outbound SMS. Contact Policy App should be configured to use this feature as a prerequisite.
contactPolicyGroupstringyes (if you want to apply Contact Policy checks before sending the message)The GroupID is to be applied. It is required if any of the following options are included and set to true.
channelCheckConsentbooleannoOptional, assumed false if not specified. Set to true to require opt-in before sending the message. At least one of the “channelCheckConsent” or “channelApplyFrequencyCap” parameters should be set to “true”.
channelApplyFrequencyCapbooleannoOptional, assumed false. Set to true to enforce group frequency cap for that channel. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”.

Sample Response Body

{
    "requestTimestamp": "2024-09-05T00:03:01.708-04:00",
    "messageId": "a770f205-1234-3x5x-x5x3-6dc3e388b9b5",
    "correlationId": "12345",
    "status": "queued"
}
   {
        "code": "7000",
        "message": "Invalid JSON"
    }
No response body

Examples

Sending SMS Using Templates

{
	"channel": "sms", //Mandatory. 
	"from": "{{from}}", //Mandatory. E.164 format required/recommended.
	"to": [
		{
			"msisdn": [
				"{{msisdn}}" //Mandatory. E.164 format required/recommended.
			],
			"correlationId": "", //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
			"substitutions": { //Optional.
				"{{sms_parameter1}}": "{{sms_value1}}"
			}
		}
	],
	"substitutions": { //Optional.
		"{{sms_parameter2}}": "{{sms_value2}}"
	},
	"template": {
		"id": "5S2XXXXFNR"
	},
	"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
	"notifyUrl": "", //Optional.
	"contactPolicy": { //Optional.JSON Object to specify contact policy checks before sending the outbound SMS. 
		"contactPolicyGroup": "", //The GroupID to be applied. Required if any of the following options are included and set to true.
		"channelCheckConsent": true, //optional,assumed false if not specified. Set to true to require opt-in before sending the message. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
		"channelApplyFrequencyCap": true //optional, assumed false. Set to true to enforce group frequency cap for that channel. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
	}
}

Following are the parameters required for sending message using templates:

parametertypemandatorydescription
templateJSONObjectyes, if content is not providedThis is a JSON object which contains the mandatory 'ID' parameter. The value for the 'ID' parameter is the unique template ID of the configured SMS template on the UI.
idstringyes (when using templates)Unique templated ID of the SMS template configured on the UI.

Sending SMS with Smartlinks

{
	"channel": "sms", //Mandatory. 
	"from": "{{from}}", //Mandatory. E.164 format required/recommended.
	"to": [
		{
			"msisdn": [
				"{{msisdn}}" //Mandatory. E.164 format required/recommended.
			],
			"substitutions": { //Optional.
				"{{sms_parameter1}}": "{{sms_value1}}",
				"{{sms_parameter2}}": "{{sms_value2}}"
			},
			"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
		}
	],
	"substitutions": { //Optional.
		"{{sms_parameter3}}": "{{sms_value3}}",
		"{{sms_parameter4}}": "{{sms_value4}}"
	},
	"smartlinks": [
		{
			"smartlinkId": {{smartlinkID}},
			"validity": 1
		}
	],
	"content": {
		"type": "text", //Mandatory. 
		"text": "Hi {{smartlink_4371}}, API V2 with smartlink" //Mandatory. 
	},
	"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
	"notifyUrl": "", //Optional.
	"contactPolicy": { //Optional.JSON Object to specify contact policy checks before sending the outbound SMS. 
		"contactPolicyGroup": "", //The GroupID to be applied. Required if any of the following options are included and set to true.
		"channelCheckConsent": true, //optional,assumed false if not specified. Set to true to require opt-in before sending the message. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
		"channelApplyFrequencyCap": true //optional, assumed false. Set to true to enforce group frequency cap for that channel. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameter should be set to “true”. 
	}
}

The following are the parameters required to send messages using Smartlink. 'Smartlinks' need to be mentioned in the SMS text field, as shown in the payload sample above.

parametertypemandatorydescription
smartlinksJSONObjectyes, if you want to use smartlinksThis is a JSON object which contains the mandatory fields required for using smartlinks.
smartlinkIdstringyesUnique smartlink ID. This value is generated within Webex Connectplatform, when you configure a smartlink.
validitystringyesValidity of the smartlink

Steps for configuring branded / short URLs for SmartLinks & 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.

📘

Note

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.


Webex Connect RegionCNAME
AWS Canadastar-1176184099.ca-central-1.elb.amazonaws.com
AWS Irelandstar-1747495833.eu-west-1.elb.amazonaws.com
AWS Londonstar-1656037958.eu-west-2.elb.amazonaws.com
AWS Oregonstar-1571873968.us-west-2.elb.amazonaws.com
Azure (US)52.138.107.55 (A Record)
AWS Mumbaistar-64546195.ap-south-1.elb.amazonaws.com
AWS Sydneystar-131871454.ap-southeast-2.elb.amazonaws.com
AWS Singaporestar-581943434.ap-southeast-1.elb.amazonaws.com