Supported Channels
Channel | Prerequisite |
---|---|
SMS | Sender 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 |
Voice | CLI - You will need to buy a voice-enabled long-code under the Numbers section. This will be your caller-ID for the outbound call |
Live Chat /In-app Messaging | Mobile/Web App - You will need to integrate our SDK into your Android/iOS apps or on your website |
Push Notifications | Mobile/Web App - You will need to integrate our SDK into your Android/iOS apps or on your website |
Facebook Messenger | Facebook App - You will need to be an admin of Facebook page and give Connect permission to access page messages through the Facebook app registration UI on Webex Connect under the apps section |
Apple Messages for Business | Apple Messages for Business App - You will need to register your company on Apple Business Register and select Webex Connect as your CS |
WhatsApp App - You will need to register here to get approval from WhatsApp and talk to your account manager for subsequent steps Note: We have created individual channel pages. We encourage you to refer to this WhatsApp page. |
Error Codes
Refer to this page.
Batching Requests
The messaging API supports batching. You can send personalized messages to a maximum of 1000 destinations at once (subject to the messaging API TPS limit for your account).
Know Your Endpoint
Based on the domain you use to log in to Webex Connect, the endpoint for your API varies. See the endpoint section to understand which endpoint to use for your domain.
Messaging API v1 - Samples
{
"appid":"", // This is required only for Push, In-App, Messenger, WhatsApp, and Apple Messages for Business
"correlationid":"SMSMTusingmsisdn", //optional; Unique transaction ID from the client end
"callbackData":"smstesting", //optional; Identifier sent alongside notifications to the notifyurl
"notifyurl":"",//If an invalid URL is passed in API request, then such request will not be considered eligible for retries.
"deliverychannel":"sms", //Channels such as sms/voice/push/rt/fb/AppleBusinessChat/whatsapp
"channels":{
"sms":{
"text":"SMS message content with {{link_linkid}}",
"senderid":"SENDER", //Phone number, short code, or alphanumeric sender ID for sending the SMS
"type":"1",
"extras":{
"dlt_templateid":"1107158158796985790" //Required for SMS Comms in India as mandated by TRAI TCCCPR regulations.
}
},
//Optional array if you want to use SmartLinks
"smartlinks":[
{
"linkid": 5,
"validity": 30
}
],
//Optional object if you want to use Contact Policy
"contactPolicy": {
“contactPolicyGroup” : "xKa4xfM3S_a9bP98ryCw8w", //the GroupID to be applied. Required if any of the following options are included and set to true
“channelCheckConsent” : true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
“channelApplyFrequencyCap” : true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
},
"voice":{object(voiceMessage)
},
"appmessaging":{object(appMessage)
},
"push":{object(pushMessage)
},
"OTT-Messaging":{
"fb":{object(fbMessage)
},
"wa":{object(whatsappMessage)
},
},
"AppleBusinessChat":{object(appleBusinessChatMessage)
},
},
"destination":[
{
"customerid/msisdn/email/android_pushid/ios_pushid/chrome_pushid/safari_pushid/psid/waid/abcUserId":[ "<value1>","<value2>"],
"correlationid":"<A unique transaction ID up to 50 bytes used by Client to match requests with responses. Will override correlationid given in request body.>"
}
],
"gtrId":["rcsgtrid"]
//"gtrids must match the number of destination objects "
"icmessage": "true" //imiconnect gateway sends "icmessage=true" by default to indicate that the push or in-app message was sent by imiconnect. This happens only when co-existence of SDKs is enabled.>
}
{
"deliverychannel":"sms",
"channels":{
//Smartlink array must be available to replace {{link_<linkid>}} information
"smartlinks":[
{
"linkid": 5,
"validity": 30
}
],
"sms":{
"text":"Sending first SMS with smart link using imiconnect. Click the link to download the mobile app {{link_5}}",
"senderid":"SENDER"
}
},
"destination":[
{
"msisdn":["+4490XXXXX009"] //E.164 format required/recommended. Older tenants might still accept other formats.
}
]
}
Postman Collection
Here is a Postman collection to test our APIs.
Archived Collection: Refer Postman Collection
Body Parameters
The following are the parameters of the request body:
Parameter | Type | Mandatory | Description |
---|---|---|---|
deliverychannel | string | yes | sms voice appmessaging push fb applebusinesschat |
correlationid | string | no | A client-side identifier chosen by the Service Provider to correlate requests and their subsequent responses. The correlation-id can be up to 50 bytes long. |
notifyurl | string | no | The Webex Connect platform will send notifications to the URL specified in the notifyurl parameter. The URL is used to retrieve the status of the message sent. The notifyurl can also be configured while creating a service. If the URL is specified in both the service and the messaging API, preference will be given to the messaging API request. |
callbackData | String | no | An identifier or data that will be sent alongside notifications to the notifyurl. This can serve as identifying notifications. |
expiry | string | no | Expiry time in UTC format, after which messages will not be pushed. For example, 2015-04-12T13:00:19.456Z or 2015-04-12T18:30:19.456+5:30. |
message | JSONObject | no | The message parameter block references a template via the template ID which is created within the Webex Connect platform. The amount of sub-parameters in the parameters block depends on the number of parameters expected in the template. These parameters are supplied to the template for substitution in the final message. { "message": { "template": "<Template ID>", "parameters": { "parameter1": "<value>", "parameter2": "<value>", "parameter3": "<value>" } } } Note: If you use message templates, then the parameter name should match with the parameter specified in the template. The parameters in this message block are overridden if a channel specific parameter block is also used. Message length is limited to 1024 bytes per SMS. |
destination | JSONArray | Yes | The destination parameter is an array of up to 1,000 entries. Messages can be sent to single or multiple recipients in a single request. Destination/Recipient MSISDN numbers i.e., phone numbers need to be provided in E.164 format. For more details, refer to destination array. |
channels | JSONObject | Yes | Contains one of the following - smsMessage voiceMessage appMessage pushMessage fbMessage whatsappMessage applebusinesschat |
Smart Links Support
Please note that Smart Links is supported for text message type in SMS, In-App Messaging and Live Chat, Facebook Messenger, and WhatsApp.
Channels
The channels parameter block configures channel communication parameters and will override the service's default values and the parameters in the base request.
SMS Message
{
"deliverychannel":"sms",
"channels":{
//Smartlink array must be available to replace {{link_<linkid>}} information
"smartlinks":[
{
"linkid": 5,
"validity": 30
}
],
"sms":{
"text":"Sending first SMS with smart link using webexconnect. Click the link to download the mobile app {{link_5}}",
"senderid":"SENDER"
}
},
"destination":[
{
"msisdn":["4490XXXXX009"]
}
]
}
Parameter | Type | Mandatory | Description |
---|---|---|---|
text | String | Yes | Text message up to 1024 characters. |
senderid | String | No | The Sender ID for this message. Note: The senderid asset must be pre-configured and associated with the channel. |
type | String | No | Following are the supported message types: 1 – Text (default) 2 – Flash 3 – Binary 4 – Unicode If no parameter is specified, type defaults to Text. |
body | String | Yes (when type is set to 3) | When type is set to 3, the body shall contain hexadecimal content for binary type message. |
{
"text":"<Channel specific message text>",
"type":"<Message type 1– Text, 2- Flash, 3– Binary, 4– Unicode>",
"senderid":"<Predefined Sender ID for this message>",
"body":"<Hexadecimal content for binary type message>"
}
{
"text":"Sending first SMS using imiconnect",
"senderid":"CONNCT"
}
{
"text":"Sending first SMS with smart link using imiconnect. Click the link to get surprise gift {{link_5}}",
"senderid":"CONNCT"
}
//for the link to work smartlinks array has to be passed under channels as well. Refer further down in the documentation for smartlinks array definition
Voice Message
Parameter | Type | Mandatory | Description |
---|---|---|---|
callflowid | String | Yes* | The callflowid created for voice flow using flow builder. If specified, the IVR flow setup is used for sending the voice message. Note: *If 'callflowid' is specified, 'media' field must not be used. |
promptid | String | Yes* | Prompt ID of the audio file uploaded in Tools > Voice media. Each file uploaded into the voice media folders on the UI is assigned a unique prompt id. If specified, the audio file located in the specified path is used to send the voice message. Note: *If 'media' is specified, 'callflowid' field must not be used. |
cli | String | No | Caller Line ID to initiate the call. Note: Contact the Support Team using the details mentioned in the ‘Contact Support’ section within your Webex Connect account, for more info on setting up your own custom CLI. |
{
"callflowid":"voice flow ID",
"media":"name of media uploaded",
"cli":"predefined CLI bought under Numebrs section"
}
{
"promptid":"354" //Prompt ID of the uploaded audio file
}
{
"callflowid":"184", //the voice flowid assgined by the flow builder
"cli":"0453745878"
}