Send Message v1

Supported Channels

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
VoiceCLI - 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 MessagingMobile/Web App - You will need to integrate our SDK into your Android/iOS apps or on your website
Push NotificationsMobile/Web App - You will need to integrate our SDK into your Android/iOS apps or on your website
Facebook MessengerFacebook 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 BusinessApple Messages for Business App - You will need to register your company on Apple Business Register and select Webex Connect as your CS
WhatsAppWhatsApp 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.

Latest Collection: Run in Postman

Archived Collection: Refer Postman Collection

Download Postman from here

Body Parameters

The following are the parameters of the request body:

ParameterTypeMandatoryDescription
deliverychannelstringyessms
voice
appmessaging
push
fb
whatsapp
applebusinesschat
correlationidstringnoA 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.
notifyurlstringnoThe 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.
callbackDataStringnoAn identifier or data that will be sent alongside notifications to the notifyurl. This can serve as identifying notifications.
expirystringnoExpiry 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.
messageJSONObjectnoThe 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.
destinationJSONArrayYesThe 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.
channelsJSONObjectYesContains 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"]
     }
  ]
}
ParameterTypeMandatoryDescription
textStringYesText message up to 1024 characters.
senderidStringNoThe Sender ID for this message.

Note: The senderid asset must be pre-configured and associated with the channel.
typeStringNoFollowing are the supported message types:

1 – Text (default)
2 – Flash
3 – Binary
4 – Unicode

If no parameter is specified, type defaults to Text.
bodyStringYes (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

ParameterTypeMandatoryDescription
callflowidStringYes*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.
promptidStringYes*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.
cliStringNoCaller 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"
}
Language
Authorization
Header