Send Message v2

Understand how you can use Send Message API v2

🚧

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

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
EmailYou 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
RCSRCS 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
MMS

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
            ],
            "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": "{{TimeinUTC}}",
    //max 7 days from current time
    "expireAt": "{{TimeinUTC}}", //Either(expireAt/validity)one can be passed.If both are provided then you will receive a 400 Bad request.
    "validity": "time period in seconds", //For e.g., 60 for 60 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” 
    }
}

Postman Collection

Here is a Postman collection to test our APIs. Make sure you change the key in the header to your service key.

Latest Collection: Run in Postman

Archived Collection:Refer Postman Collection

Download Postman from here

👍

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

ParameterTypeMandatoryDescription
channelenumyesemail
* rcs
fromstringyes_ email - [email protected] (domain needs to be registered in apps)
* rcs - app ID generated on the UI
toJSONArrayyesarray 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 -
_ email - email
* rcs - msisdn
substitutionsJSONObjectnoa JSON object with global substitutions. If a variable exists both in personalized substitutions and global substitutions, the personalized substitution takes preference
sendAtdate/timeyesThe timestamp of the message to be delivered (maximum 7 days)

For example,
_ 2021-06-26T13:47:18.000Z - UTC
expireAtdate/timeyesThe time format for when the message has to be expired and failed if not delivered

For example,
_ 2021-06-26T13:47:18.000Z - UTC
validitystringyesTime 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.
optionsJSONObjectnoa JSON object that contains additional channel specific options in API. More information under each channel below
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.
notifyUrlstringnoa HTTPS endpoint for message delivery web-hooks
requestedReceiptsJSONArraynoa JSON array that can filter message delivery web-hooks to the notifyURL.

Can contain one or more of the following for each channel
_ email - "Parameter",
"h-1": "Type",
"h-2": "Mandatory",
"h-3": "Descriptio
* rcs - ": "Type",
"h-2": "Mandatory",

Check Outbound Webhooks for more information on receipts
contentJSONObjectyes, if template is not providedcontains the content of the message for each channel. see below for more examples
templateJSONObjectyes, if content is not providedcontains the template id for each channel that's configured on the UI
Language
Click Try It! to start a request and see the response here!