API Endpoint and Authentication
Your API endpoint varies based on where your Webex 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.
The messaging 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 messaging API TPS configuration is 10 you can send messages to up to 10 destinations at once.
Prerequisites
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 |
You will need to set up an Email app within Webex Connectand verify your domain before you are able to send emails. Please contact the Support team for any assistance in setting up Email app | |
RCS | RCS chatbot needs to be created on all operators in geography before RCS messages can be sent. This setup takes at least 7 days after submission on the UI under the apps section of Webex Connect |
Messaging API v2 - Samples
{
"appid":"<channel asset specific App ID available in Assets page>", //This is required only for Push, In-App, Messenger, WhatsApp, and Apple Messages for Business
"channel":"<channel name - v2 API currently supports sms, email and rcs",
"from":"<from address for the message, for SMS this will be a senderID, for email the sender address and for all OTT channels it will be appId available on the UI>",
"to":[
{
"msisdn/email":[
"single/multiple destination objects of the same type" //MSISDN i.e., phone numbers in E.164 format
],
],
"gtrId":["rcsgtrid"]
//"gtrids must match the number of destination objects "
"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/email":[
"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",
},
// Message scheduling
"sendAt":"<ISO8601 date/time>",
//max 7 days from current time
// Only 1 of these 2 can be used. If both come then it's a 400 Bad request
"expireAt":"<ISO8601 date/time>",
"validity":"time period in seconds",
// Channel specific message options
"options":{
object(smsOptions)||object(emailOptions)||Object(rcsOptions)
},
// Call-backs
"callbackData":"<notify data>",
"notifyUrl":"https://notify.example.com",
"requestedReceipts":[
"DELIVERED",
"READ"
],
// Union field message can be only one of content or template
"content":{
object(smsMessage)||object(emailMessage)||object(rcsMessage)
},
"template":{
"id":"<unique template ID fom the UI"
}
//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”
}
{
"channel": "sms",
"from": "{{from}}", //E.164 format required/recommended.
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
]
}
],
"substitutions": {
"{{sms_parameter1}}": "{{sms_value1}}",
"{{sms_parameter2}}": "{{sms_value2}}"
},
"options": {
"trackClicks": "true",
"shortenLinks": "true",
"domain": "https://s.imiconnect.co"
},
"requestedReceipts": [
"SENT",
"DELIVERED",
"CLICKED"
],
"content": {
"type": "unicode",
"text": "£ ¥ ¿ Ä Å Æ Ç É Ñ Ö Ø Ü Ü ß à ä å æ è é\n with JWT token https://www.google.com"
},
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "",
"sendAt": "<ISO8601 date/time>",
"expireAt": "<ISO8601 date/time>",
"validity": "time period in seconds",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "email", //channel used for messaging.
"from": "{{fromEmailAddress}}", //Email id of the sender.
"to": [
{
"email": [
"{{toEmailAddress}}"
], //email id of the recipients
"substitutions": {
"{{param1}}": "{{param1Value}}",
"{{param2}}": "{{param2Value}}"
}
}
],
"substitutions": {
"{{param3}}": "{{param3Value}}",
"{{param4}}": "{{param4Value}}"
},
"cc": [], //Email id of the copied recipients.
"bcc": [], //Email id of the bcc recipients.
"options": {
"fromName": "{{emailSendername}}" //A string that will appear next to the from address in most email inboxes
},
"content": {
"type": "text", //Either text or html. Use text while sending text emails.
"encoding": "utf-8", //Character encoding used for email text. Use this for rendering items such as emoticons as part of text emails.
"subject": "{{subject}}", //Subject of the email
"replyTo": "{{replyToEmailAddress}}", //Reply path for the email when the customer responds
"text": "Simple text content" //Text content of the email
},
"requestedReceipts": [
"submitted",
"delivered",
"read",
"clicked",
"bounced",
"not verified",
"invalid",
"complaint",
"failed"
], //JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following: "submitted", "delivered", "not verified", "invalid", "bounced", "complaint", "read", "clicked", "failed". Check Outbound Webhooks for more information on receipts. Note: All the above receipts are relevant for email via AWS SES. For email via SMTP, only "submitted" receipt is applicable
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "", //Provide a URL to get notifications on message delivery status. Use requestedReceipts block to specify list of messages status you want to track.
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "text",
"text": "This is the message. Reply Yes or No.",
"suggestions": [
{
"type": "reply",
"displayText": "Yes",
"postbackData": "usr_msg_yes"
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"correlationId": "", //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.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
Postman Collection
Here is a Postman collection to test our APIs. Make sure you change the key in the header to your service key.
Archived Collection:Refer Postman Collection
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 V2.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
Parameter | Type | Mandatory | Description |
---|---|---|---|
channel | enum | yes | sms * rcs |
from | string | yes | sms - Sender ID email - [email protected] (domain needs to be registered in apps) * rcs - app ID generated on the UI |
to | JSONArray | yes | array of destination JSON objects that contain the channel specific destination and personalized substitutions for each destination object. MSISDN i.e., phone numbers should be in E.164 format. Channel wise destinations - sms - msisdn email - email * rcs - msisdn |
substitutions | JSONObject | no | a JSON object with global substitutions. If a variable exists both in personalized substitutions and global substitutions, the personalized substitution takes preference |
sendAt | date/time | yes | IS08601 time format for when the message has to be delivered (max 7 days) For example, 2021-06-26T13:47:18.000Z - UTC 2021-06-26T13:47:18.000+05:30 - with timezone * 1624782447 - epoch timestamp |
expireAt | date/time | yes | IS08601 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 |
validity | string | yes | Time period 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. |
options | JSONObject | no | a JSON object that contains additional channel specific options in API. More information under each channel below |
callbackData | string | no | A 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. |
notifyUrl | string | no | a HTTPS endpoint for message delivery web-hooks |
requestedReceipts | JSONArray | no | a JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following for each channel sms - ": "channel", "h-0": "Parameter", " email - "Parameter", "h-1": "Type", "h-2": "Mandatory", "h-3": "Descriptio * rcs - ": "Type", "h-2": "Mandatory", Check Outbound Webhooks for more information on receipts |
content | JSONObject | yes, if template is not provided | contains the content of the message for each channel. see below for more examples |
template | JSONObject | yes, if content is not provided | contains the template id for each channel that's configured on the UI |
SMS Channel
smsOptions Block
parameter | type | description |
---|---|---|
shortenLinks | boolean | When enabled, this shortens HTTPS links found in the body of the message request, excluding any Smart Links. |
domain | string | Domain configuration for shortening the links. |
trackClicks | boolean | You 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 ‘False’ by default. Clicked format available here |
{
"shortenLinks":true, //shortens https links found in the body of the request, excluding smart links
"domain":"https://me.co.uk", //domain for the shorternedLink must be preconfigured.
"trackClicks":true //when shorten links is true, clicks can be tracked and clicked events can be received on your notifyURL
}
smsMessage
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | text or 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, that allows full character set and emoji support, but results in 2 or 3 times more SMS traffic than plain SMS text. |
text | string | yes | body of the message upto 1024 chars |
{
"type":"text or unicode",
"text":"Hi $(name), this is a text message ${field2}" //body of the message with variables represented as $(variable)
}
Note
Please refer to the chapter SMS Length and Encoding for more information on Text (GSM) vs Unicode implications and supported characters.
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.
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 Region | CNAME |
---|---|
AWS Canada | star-1176184099.ca-central-1.elb.amazonaws.com |
AWS Ireland | star-1747495833.eu-west-1.elb.amazonaws.com |
AWS London | star-1656037958.eu-west-2.elb.amazonaws.com |
AWS Oregon | star-1571873968.us-west-2.elb.amazonaws.com |
Azure (US) | 52.138.107.55 (A Record) |
AWS Mumbai | star-64546195.ap-south-1.elb.amazonaws.com |
AWS Sydney | star-131871454.ap-southeast-2.elb.amazonaws.com |
AWS Singapore | star-581943434.ap-southeast-1.elb.amazonaws.com |
Email Channel
emailMessage
{
"channel": "email", //channel used for messaging.
"from": "{{fromEmailAddress}}", //Email id of the sender.
"to": [
{
"email": [
"{{toEmailAddress}}"
], //email id of the recipients
"substitutions": {
"{{param1}}": "{{param1Value}}",
"{{param2}}": "{{param2Value}}"
}
}
],
"substitutions": {
"{{param3}}": "{{param3Value}}",
"{{param4}}": "{{param4Value}}"
},
"cc": [], //Email id of the copied recipients.
"bcc": [], //Email id of the bcc recipients.
"options": {
"fromName": "{{emailSendername}}", //A string that will appear next to the from address in most email inboxes
"listUnsubscribeUrl": "https://www.domain.tld/<<topic_id>>/<<sender_id>>/unsubscribe",// to add one-click unsubcribe URL
"unsubscribeEmailAddress": "[email protected]",// to add unsubcribe mailto address
"unsubscribeEmailSubject": "Request to Unsubscribe"// to add unsubcribe email subject
},
"content": {
"type": "text", //Either text or html. Use text while sending text emails.
"encoding": "utf-8", //Character encoding used for email text. Use this for rendering items such as emoticons as part of text emails.
"subject": "{{subject}}", //Subject of the email
"replyTo": "{{replyToEmailAddress}}", //Reply path for the email when the customer responds
"text": "Simple text content" //Text content of the email
},
"requestedReceipts": [
"submitted",
"delivered",
"read",
"clicked",
"bounced",
"not verified",
"invalid",
"complaint",
"failed"
], //JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following: "submitted", "delivered", "not verified", "invalid", "bounced", "complaint", "read", "clicked", "failed". Check Outbound Webhooks for more information on receipts. Note: All the above receipts are relevant for email via AWS SES. For email via SMTP, only "submitted" receipt is applicable
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "", //Provide a URL to get notifications on message delivery status. Use requestedReceipts block to specify list of messages status you want to track.
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "email", //channel used for messaging.
"from": "{{fromEmailAddress}}", //Email id of the sender.
"to": [
{
"email": [
"{{toEmailAddress}}"
], //email id of the recipients
"substitutions": {
"{{param1}}": "{{param1Value}}",
"{{param2}}": "{{param2Value}}"
}
}
],
"substitutions": {
"{{param3}}": "{{param3Value}}",
"{{param4}}": "{{param4Value}}"
},
"cc": [], //Email id of the copied recipients.
"bcc": [], //Email id of the bcc recipients.
"options": {
"fromName": "{{emailSendername}}", //string that will appear next to the from address in most email inboxes
"trackClicks": true, //When enabled, this tracks all links in the HTML body unless a link is tagged as no-track-connect within the anchor tags. Link tracking is supported only for Email app assets configured using AWS SES.
"trackOpens": true, //When enabled, this tracks opens of the email. Open tracking is supported only for Email app assets configured using AWS SES.
"listUnsubscribeUrl": "https://www.domain.tld/<<topic_id>>/<<sender_id>>/unsubscribe",// to add one-click unsubcribe URL
"unsubscribeEmailAddress": "[email protected]",// to add unsubcribe mailto address
"unsubscribeEmailSubject": "Request to Unsubscribe"// to add unsubcribe email subject
},
"content": {
"type": "html", //Either text or html. Use html while sending html emails.
"encoding": "utf-8", //Character encoding used for email text. Use this for rendering items such as emoticons as part of text emails.
"subject": "{{subject}}", //Subject of the email
"replyTo": "{{replyToEmailAddress}}", //Reply path for the email when the customer responds
"text": "Fallback text in the event the email client does not support HTML emails", //Text content of the email
"html": "<a track_enable href=\"http://example.com\">link text</a><footer><a data-mce-href='$(unsubscribe)' href='$(unsubscribe)' target='_blank' rel='noopener'><span st-unsubscribe='' style='text-decoration: none; color: #0088cc;' data-mce-style='text-decoration: none; color: #0088cc;'>unsubscribe</span></a></footer>" //Raw HTML for the email. Up to 350 kbps in size.
},
"requestedReceipts": [
"submitted",
"delivered",
"read",
"clicked",
"bounced",
"not verified",
"invalid",
"complaint",
"failed"
], //JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following: "submitted", "delivered", "not verified", "invalid", "bounced", "complaint", "read", "clicked", "failed". Check Outbound Webhooks for more information on receipts. Note: All the above receipts are relevant for email via AWS SES. For email via SMTP, only "submitted" receipt is applicable
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "", //Provide a URL to get notifications on message delivery status. Use requestedReceipts block to specify list of messages status you want to track.
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "email",
"from": "[email protected]",
"notifyUrl": "https://webhook.site/f023c932-6d17-4a45-9a43-822e8c6e6f97",
"multipleToRecipients": true,
"requestedReceipts": [],
"to": [
{
"email": [
"[email protected]",
"[email protected]"
],
"correlationId": "",
"substitutions": {
"area": "",
"accountNumber": ""
}
}
],
"substitutions": {
"offerName": "",
"value": ""
},
"cc": [
""
],
"bcc": [
""
],
"options": {
"fromName": "apiv2",
"trackClicks": true,
"trackOpens": true,
},
"content": {
"type": "html",
"encoding": "utf-8",
"subject": "We are reaching you through web 465 because",
"replyTo": "",
"text": "We are reaching you for next SSL genre if",
"html": ""
}
}
{
"channel": "email", //channel used for messaging.
"from": "{{fromEmailAddress}}", //Email id of the sender.
"to": [
{
"email": [
"{{toEmailAddress}}"
], //email id of the recipients
"substitutions": {
"{{param1}}": "{{param1Value}}",
"{{param2}}": "{{param2Value}}"
}
}
],
"substitutions": {
"{{param3}}": "{{param3Value}}",
"{{param4}}": "{{param4Value}}"
},
"options": {
"trackClicks": true, //When enabled, this tracks all links in the HTML body unless a link is tagged as no-track-connect within the anchor tags. Link tracking is supported only for Email app assets configured using AWS SES.
"trackOpens": true, //When enabled, this tracks opens of the email. Open tracking is supported only for Email app assets configured using AWS SES.
"fromName": "{{emailSendername}}" //A string that will appear next to the from address in most email inboxes
},
"content": {
"type": "html", //Either text or html.
"subject": "{{subject}}", //Subject of the email
"text": "Fallback text in the event the email client does not support HTML emails", //Text content of the email Note:yes, when type=text optional, when type=html
"attachments": [
{
"mimetype": "image/png", //Supported mimeTpes
"name": "Flower", //Name of the attachments
"mediaUrl": "" //Direct URL pointing to the media file. The URL should end with specified file-format.
}
]
},
"requestedReceipts": [
"submitted",
"delivered",
"read",
"clicked",
"bounced",
"not verified",
"invalid",
"complaint",
"failed"
], //JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following: "submitted", "delivered", "not verified", "invalid", "bounced", "complaint", "read", "clicked", "failed". Check Outbound Webhooks for more information on receipts. Note: All the above receipts are relevant for email via AWS SES. For email via SMTP, only "submitted" receipt is applicable
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "", //Provide a URL to get notifications on message delivery status. Use requestedReceipts block to specify list of messages status you want to track.
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "email", //channel used for messaging.
"from": "{{fromEmailAddress}}", //Email id of the sender.
"to": [
{
"email": [
"{{toEmailAddress}}"
], //email id of the recipients
"substitutions": {
"{{param1}}": "{{param1Value}}",
"{{param2}}": "{{param2Value}}"
}
}
],
"substitutions": {
"{{param3}}": "{{param3Value}}",
"{{param4}}": "{{param4Value}}",
"{{param5}}": "{{param5Value}}",
"{{param6}}": "{{param6Value}}"
},
"template": {
"id": "{{templateId}}", //Unique identifier of the email template used for constructing the email
"encoding": "utf-8", //Character encoding used for email text. Use this for rendering items such as emoticons as part of text emails.
"subject": "{{subject}}" //Subject of the email
},
"requestedReceipts": [
"submitted",
"delivered",
"read",
"clicked",
"bounced",
"not verified",
"invalid",
"complaint",
"failed"
], //JSON array that can filter message delivery web-hooks to the notifyURL. Can contain one or more of the following: "submitted", "delivered", "not verified", "invalid", "bounced", "complaint", "read", "clicked", "failed". Check Outbound Webhooks for more information on receipts. Note: All the above receipts are relevant for email via AWS SES. For email via SMTP, only "submitted" receipt is applicable
"correlationid": "", //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": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyurl": "", //Provide a URL to get notifications on message delivery status. Use requestedReceipts block to specify list of messages status you want to track.
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
Multiple 'To' Recipients
- You have the ability to send emails to multiple ‘To’ recipients in a single email transaction using Messaging API v2. This would require you to pass an additional parameter ‘multipleToRecipients’ to be passed as part of the request with its value set to ‘true’. When multiple email IDs are mentioned in the “Email” parameter of the “To” block, Webex Connect submits a single request to AWS SES or to SMTP server to send the concerned email to all - To, CC, and BCC. In this case, the API response will contain only one transaction ID for all recipients. Refer API reference for more information.
- When Webex Connect is used to send emails to multiple email recipients (To, CC, BCC), the message submitted count reflects the total number of emails sent (counting each of the recipient in To, CC, and BCC fields individually). These changes will reflect in the ‘Reports’ and in the ‘Usage’ sections for email transactions.
- For email transactions with multiple recipients, the Status field in Debug Console and Export Logs, and Error Codes details, will only be updated for entries with the ‘Submitted’ Status. Email delivery status for each of the individual recipients will need to be tracked using Outbound Webhooks. Separate outbound notifications will be sent for email delivery or failure to each of the recipients mentioned in To, CC, and BCC sections with the same transaction ID. For outbound email transactions, destination will contain an email ID for scenarios where only one email ID has been mentioned (that can in be in either of to, bcc, or cc fields but overall one email ID is mentioned in one outbound request).
- Read receipts are not generated for emails sent as plain text, i.e., when the email type is text.
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | Text or HTML |
subject | string | yes | Subject of the email |
replyTo | string | no | Reply path for the email when the customer responds |
attachments | JSONArray | no | Attachment sizes are subject to overall email message size limitations mentioned below. |
text | string | yes, when type=text optional, when type=html | Text content of the email |
html | string | yes, when type=html | Raw HTML for the email. Up to 500 KB in size. |
multipleTorecipients | boolean | no | When the flag is set to true, the platform sends a single email to multiple recipients in the 'To' field list. When the flag is set to false, the platform sends separate emails to multiple recipients in the 'To' field list. |
Email Size Limitations
The default email size limit for AWS SES based email assets in Webex Connect is 10 MB. This is the overall email size limit including (including the email text, images, attachments and the MIME encoding). Please note that the size increases post MIME encoding. If you attach a 5MB file in your email, the attachment size after MIME encoding will be ~6.85MB (about 137% of the original file size).
emailOptions
{
"trackClicks":true, //to track clicks in the email
"trackOpens":true, //to track email opens
"fromName":"Webex Connect UK", //from name that appears in the email inbox
"listUnsubscribeUrl": "https://www.domain.tld/<<topic_id>>/<<sender_id>>/unsubscribe",// to add one-click unsubcribe URL
"unsubscribeEmailAddress": "[email protected]",// to add unsubcribe mailto address
"unsubscribeEmailSubject": "Request to Unsubscribe"// to add unsubcribe email subject
}
parameter | type | description |
---|---|---|
trackClicks | boolean | When enabled, this tracks all links in the HTML body unless a link is tagged as no-track-connect within the anchor tags |
trackOpens | boolean | When enabled, this tracks opens of the email |
fromName | string | Appears next to the from address in most email inboxes. |
listUnsubscribeUrl | string | Allows you to pass the link to your own subscription management portal, as part of the list-unsubscribe headers, instead of using Webex Connect subscription management capability. |
unsubscribeEmailAddress | string | Contains the email address to which the unsubscribe email will be sent, when the customer sends unsubscribe request via mail to unsubscribe route. |
unsubscribeEmailSubject | string | Specify the subject that you would like to use for the email unsubscribe requests triggered via mail to unsubscribe route. |
Note
There is an option to pass list-unsubscribe headers when sending emails using Webex Connect Messaging API v2. This will allow you to pass the links to your own unsubscribe management portal as part of the list-unsubscribe headers instead of using Webex Connectunsubscribe management capability. The following headers can be passed:
- listUnsubscribeUrl
- unsubscribeEmailAddress
- unsubscribeEmailSubject
When the list-unsubscribe URL and/or unsubscribe mailto address are added, the Webex Connect platform will overwrite the asset setting with the values provided in the Messaging API, even for the assets for which the platform manages unsubscriptions. In such cases, the Webex Connect platform will no longer have control over the Outbound Webhook notifications for the unsubscribe events originated from the list-unsubscribe header. Therefore, you are recommended to use these options only when you have a mechanism to handle unsubscriptions (including one-click unsubscription) on your own.
Since it’s an email compliance requirement, the one-click unsubscribe header will be added to the outbound email, every time the list-unsubscribe URL is added in the Messaging API. You are expected to handle one-click unsubscriptions, i.e., receive postback from the email clients, perform action (add user email address to unsubscribe list), and respond with appropriate success status.
RCS Channel
Best Practices
- Send one of textMessage, fileMessage, audioMessage, richcardMessage, or richCardCarousel to a subscriber at a time, allowing for necessary delivery and response time between messages.
- One and only one suggestedChipList can be used together with one and only one of textMessage, fileMessage, audioMessage, geolocationPushMessage, or richcardMessage. Note that suggestion actions available today are reply, calendar, map location, open URL, and dial. Different suggestion action types can be combined in a single suggestedChipList.
- A suggestedChipList shall not be sent without an accompanying message.
- Single rich card messages can be configured as short, medium, or tall with a suggestion. Rich card carousels are limited to short or medium rich cards with a suggestion.
- Some mobile network RCS service providers wait for a delivery receipt for a text message prior to sending any related suggestion. Ensure your test plans include each carrier your program will terminate to.
- The fileMessage and richCardMessage parameter fileSize requested is related to image and videos contained in URLs. The measurement shall be in bytes and while not all MaaPs require an accurate fileSize, the size shall not be 0.
- Please note that the substitutions apply only to text field.
rcsOptions
parameter | type | description |
---|---|---|
smsFallback | boolean | when true, auto SMS fallback will be tried for RCS failures. If this parameter is not passed, SMS fallback will be disabled by default. Refer to the note below for details on how it works. |
smsSenderId | string | Sender ID that is already configured on your account |
text | string | text message up-to 1024 chars |
carrierId | string | if you already know the carrier of the end customer, you can pass this as an optional parameter. increases the throughput of RCS outbound messagesfor list of carrierIds, check here |
Limitation
The routing of SMS messages will be handled by the standard routing rules configured for your tenant. Please reach out to your account manager for more information.
smsFallback Parameter
If the smsFallback parameter is set to 'true' in the Webex Connect messaging API to enable SMS fallback for RCS messages, then the smsSenderId and text fields become mandatory, to ensure that the fallback message is sent successfully.
For more information on how the feature works, refer to the FAQs chapter.
{
"smsFallback":true, //to enable sms fallback if user is not RCS enabled
"smsSenderId":"senderaddress",
"text":"fallback text",
"carrierId":"12"
}
rcsMessage
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | text, media, standalone, carousel, agentEvent |
text | string | yes, if type = text | up to 3072 chars |
mediaContentUrl | string | yes, if type = media | a publicly accessible direct media Url ending in the attachment mimeType |
richCard | JSONObject | yes, if type = standalone | a JSON object containing rich card data and suggestions |
width | string | yes, if type = carousel | a parameter that indicates the width of carousel cards |
cards | JSONArray | yes, if type = carousel | a JSON array containing carousel card objects and their suggestions |
event | string | yes, if type = agentEvent | a typing or a read event to be sent to the customer |
suggestions | JSONArray | no | a JSON array that can contain upto 10 suggestions with a message, 2 when within a carousel and 4 when within a richcard reply viewLocation shareLocation openUrl calendarEvent dialPhone |
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "text",
"text": "This is the message. Reply Yes or No.",
"suggestions": [
{
"type": "reply",
"displayText": "Yes",
"postbackData": "usr_msg_yes"
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "media",
"mediaContentUrl": "https://asset.com/asset.jpg",
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "standalone",
"richCard": {
"title": "",
"description": "",
"orientation": "",
"thumbnailAlignment": "LEFT",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2J5i2x0"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "carousel",
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
],
"width": "SMALL/MEDIUM",
"cards": [
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2J5i2x0"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2P5Q9dK"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "agentEvent",
"event": "IS_TYPING"
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
} "latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
],
"width": "SMALL/MEDIUM",
"cards": [
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2J5i2x0"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2P5Q9dK"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
}
]
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
{
"channel": "rcs",
"from": "{{rcsAppId}}",
"to": [
{
"msisdn": [
"{{msisdn}}" //E.164 format required/recommended.
],
"correlationId": "", //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": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
}
}
],
"substitutions": {
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [
"DELIVERED"
],
"content": {
"type": "agentEvent",
"event": "READ",
"messageId": ""
},
"callbackData": "", //Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "",
"contactPolicy": {
"contactPolicyGroup": "", //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”
}
}
Suggestions
reply
Suggested replies help your chatbot guide users through conversations by providing responses that the chatbot knows how to react to. Your agent sends replies in suggestion chip lists or rich cards.viewLocation
The View location action displays a location in the user's default map app. You can specify the location either by latitude and longitude or with a query based on the user's current location. You can also set a custom label for the pin that displays in the map app.shareLocation
The Share location action lets the user send a location to your chatbot.openUrl
The Open URL action opens the user's web browser to the specified URL. If an app is registered as a default handler for the URL, the app opens instead, and the icon for the action is the app's icon.calendarEvent
The Create calendar event action opens the user's calendar app and begins to create a new event with the specified information.dialPhone
The Dial action guides the user to dial a phone number that your chatbot specifies.