Send Message API v1

Understand how you can use Send Message API v1 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.

The endpoint for it is: [https://{YourRegion}.webexconnect.io/resources/v1/messaging].

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

Refer to our Postman Collection for trying Send Message API v1.

Authentication

Refer this page for information on API Authentication.

🚧

While Send Message API v1 supports SMS as one of the channels, we do not recommend using this API for any new SMS services. We continue to support it to avoid any impact on the previously configured services. We no longer add any new capabilities to this API for the SMS channel.

📘

API Response and Error Codes

This API is an asynchronous API. The HTTP response confirming acceptance of your request is send 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 this pagefor more information.

Request Body to Send SMS Using Send Message API v1

{
	"deliverychannel": "sms", //Mandatory. 
	"destination": [
		{
			"msisdn": [
				"{{msisdn}}" //Mandatory. 
			]
		}
	],
	"channels": {
		"sms": {
			"senderid": "{{SENDERID}}", //Mandatory. 
			"text": "Sending first SMS using Webex Connect" //Mandatory. 
		}
	},
	"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.
	"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 v1 Parameters

The following are the parameters of the request body:

ParameterTypeMandatoryDescription
deliverychannelstringyesChannel used to send the message, i.e., 'sms'.
destinationarray of objectsyesArray of destination IDs, i.e., the phone numbers to which the SMS messages are to be sent.
msisdnJSON ArrayyesPhone number i.e., MSISDN to which the SMS has to be sent in the E.164 format. e.g., +44XXXXXXXXXX

Note: If +E.164 format is enabled for your tenant - all the numbers in the destination(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 senderid(from) field.
channelsJSON ObjectyesJSON object that contains mandatory 'sms' JSON object parameter.
smsJSON ObjectyesJSON object that contains mandatory 'sender ID' and 'text' parameters.
textstringyesThe SMS message content. A maximum of 1024 characters can be supported.
senderidstringyesSMS Sender ID, i.e., the long code, short code, or the Sender ID to be used for sending the message.

Note: The senderid asset must be pre-configured and associated with the channel.
typestringNoUsed for specifying the message content type. Acceptable values are: '1', '2', '3', and '4'.
The following are the supported message types that depict (1, 2, 3, 4) as below:
1 – Text (default)
2 – Flash
3 – Binary
4 – Unicode

If no parameter is specified, type defaults to 'Text'.

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.
bodystringYes (when type is set to 3)When type is set to 3, the body shall contain hexadecimal content for binary type message.
correlationidstringNoUser-defined ID that is assigned to an individual message for unique identification.
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.
contactPolicyJSON ObjectNoJSON Object to specify contact policy checks before sending the outbound SMS. Contact Policy App should be configured to use this feature as a prerequisite.
contactPolicyGroupstringNoThe GroupID is to be applied. 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” parameters should be set to “true”.

Sample Response Body

{
  "response": [
    {
      "code": "1001",
      "transid": "3f09295d-9xx3-4x8x-4xx5-a3272e5f00c1",
      "description": "Queued"
    }
  ]
}
{
  "response": {
    "code": "7001",
    "description": "Authentication failed.",
    "transid": "7670c9a8-123x-4566-xx15-17f6109340d6"
  }
}
{
  "response": {
    "code": "7000",
    "description": "Invalid JSON",
    "transid": "2b2c0bfb-1234-1234x-456x-44ee007c130f"
  }
}

Example

Sending SMS with Smartlink

{
	"deliverychannel": "sms", //Mandatory. 
	"destination": [
		{
			"msisdn": [
				"{{msisdn}}" //Mandatory. 
			]
		}
	],
	"channels": {
		"smartlinks": [
			{
				"linkid": "",
				"validity": ""
			}
		],
		"sms": {
			"senderid": "{{SENDERID}}", //Mandatory. 
			"type": "1",
			"text": "Sending first SMS with smart link using Webex Connect. Click the link to get surprise gift {{link_5}}" //Mandatory. 
		}
	},
	"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.
	"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.
linkidstringyesUnique smartlink ID. This value is generated within Webex Connectplatform, when you configure a smartlink.
validitystringyesValidity of the smartlink