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 imiconnect 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 imiconnect, 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, 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 imiconnect. 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. If the senderid is not configured, a default senderid CONNCT can be used to send the message.
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 [email protected] 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"
}

Push Message

ParameterTypeMandatoryDescription
androidJSONObjectNoThis is a parameter block with Android specific Push settings.
iosJSONObjectNoThis is a parameter block with iOS specific Push settings.
interactiveJSONObjectNoThis is a parameter block with the following:

pushref
device_types
ios
android
windows
category
actions (array block)
pos
action
value
webJSONObjectNoThis is a parameter block with web browser specific Push settings.

title
text
url
actionText
platform_types
extras
time_to_live
collapse_key
customtags

📘

Note

Either android or ios or web parameter must be passed.

📘

Note

The overall payload limit for the messaging API for Push notification is 4KB.

Android

ParameterTypeMandatoryDescription
textStringYesAndroid specific text message .
extrasJSONObjectNoA parameter block consisting of:

collapse_key
time_to_live
sound
delay_while_idle (Deprecated)
customtags
notificationaction
titleStringNoMessage title.
{
	"push":{
		"android":{
			"text":"<Android message>",
			"title":"android message title",
			"extras":{
				Refer to Android extras
			}
		}
	}
  "destination": [
    {
     "userid":["4545"]
    }
  ]

push > android > Android extras

ParameterTypeMandatoryDescription
collapse_keyStringNoAn arbitrary string that is used to replace the older message with new message when the older message did not reach the destination.
time_to_liveStringNoExpiry time for the message in seconds.
soundStringNoDefault / Custom sound will be played when the notification delivered.

The options are:
default
custom sound
delay_while_idle (Deprecated)StringNoIf true, the message delivery is delayed when the customer’s device is idle.

Options are:
true
false
customtagsJSONObjectNoA user defined key-value pair. The value can be a string or JSON object, or a JSON array. This object contains a reserved parameter:
imageurl: It accepts a URL as string. This parameter is used to send images in notification.
notificationactionJSONObjectNoDefine this object to add an action when the notification is clicked. The sub parameters of this block are:

action
value
iconurlStringNoCorresponds to Android Push notification image received on the mobile.
notificationChannelIdStringNoStarting on Android 8.0, all notifications must be assigned to a Notification channel or it will not appear.

Instead of disabling all the notifications, user can control notification by disabling a specific channel on the app.
{
   "collapse_key":"<Alpha numeric key>",
   "sound":"<default/custom sound>",
   "time_to_live":"<integer value>",
   "customtags":{"key1":"object1","key2":{"object2":"val"},"key3":["object3","object4"]},
   "notificationaction": {
    	"action": "OPEN_URL",
			"value": "www.google.com"
		}
}

The following parameters are part of the notification action parameter block which in turn is part of the extras block.

ParameterTypeMandatoryDescription
actionStringNoYou can configure the following for an action:

OPEN_URL: Requires a URL as action value.
OPEN_WEBVIEW: Requires a URL as action value.
OPEN_HTML: Requires a html code to render as action value.
DEEPLINK: Requires a deeplink URL as action value.
OPEN_APP: Does not require an action value.
valueStringNoSpecifies the value that is used to complete the action configured. For example, if you configure action as OPEN_URL, then you have to configure value with a URL such as www.bbc.com.

Note: If the action is set to OPENAPP, value is not required.

📘

It is not mandatory to define notificationaction. But if you set an action, you must specify a _value _that is used to complete the configured action.

  • iOS
ParameterTypeMandatoryDescription
textStringYesiOS specific text message.
extrasJSONObjectNoA parameter block consisting of:

badge
sound
time_to_live
silentpush
url
html
customtags
notificationaction
collapse_key
attachmenturl
{
	"ios":{
		"text":"<iOS message>",
		"title":"ios message title",
		"extras":{
			Refer to ios extras
		}
	}
}

push > ios > ios extras

ParameterTypeMandatoryDescription
badgeStringNoThe number to be displayed as badge of the app icon.
soundStringNoDefault / Custom sound that should be played when the notification is delivered.

The options are:
default
custom sound
time_to_liveStringNoExpiry time for the message in seconds.
silentpushStringNoThe customer will not get the notification of the delivered message, but the app receives the pushed message if this attribute is true.

The options are:
true
false
customtagsJSONObjectNoA user defined key-value pair. The value can be a string or JSON object, or a JSON array.
notificationactionJSONObjectNoDefine this object to add an action when the notification is clicked. The sub parameters of this block are:
action
value
{
    "badge": "<badge number>",
    "sound": "<default/custom sound>",
    "time_to_live": "<integer value>",
    "silentpush": "[true|false]",
    "customtags": {
        "key1": "object1",
        "key2": {
            "object2": "val"
        },
        "key3": ["object3", "object4"]
    },
    "notificationaction": {
        "action": "OPEN_URL",
        "value": "www.google.com"
    }
}

The following parameters are part of the notificationaction parameter block which in turn is part of the extras block.

ParameterTypeMandatoryDescription
actionStringNoYou can configure the following for an action:

OPEN_URL: Requires a URL as action value.
OPEN_WEBVIEW: Requires a URL as action value.
OPEN_HTML: Requires a html code to render as action value.
DEEPLINK: Requires a deeplink URL as action value.
OPEN_APP: Does not require an action value.
valueStringNoSpecifies the value that is used to complete the action configured. For example, if you configure action as OPEN_URL, then you have to configure value with a URL such as www.bbc.com.

Note: If the action is set to OPENAPP, value is not required.

📘

It is not mandatory to define notification action. But if you set an action, you must specify a _value _that is used to complete the configured action.

web

ParameterTypeMandatoryDescription
titleStringYesSpecifies the title of the web browser push message.
textStringYesSpecifies the push message for web browser.
urlStringNoSpecifies the URL that opens when the message is clicked.
actiontextStringYesSpecifies the text of the button. This parameter is applicable to Safari browser only.
platform_typesJSONArrayYesSpecifies the browsers to which the message is sent.
extrasJSONObjectNoA parameter block consisting of:

time_to_live
collapse_key
customtags

Note: The parameter collapse_key is not applicable to safari browser.
{
	"web":{
		"platform_types":[
			"firefox",
			"chrome",
			"safari"
		],
		"title":"Offers",
		"text":"50% off on google apps",
		"actiontext":"view",
		"url":"https://play.google.com/myaps/50"
	}
}
// Web browser notification
{
    "web": {
        "title": "<title text for web browser push message>",
        "text": "<push message text for Web browser>",
        "url": "<URL that opens when message is clicked>",
        "actiontext": "<Specifies the text of the button for safari browsers only>",
        "platorm_types": ["chrome", "safari", "firefox"], //Specifies the browsers to which the message is sent.
        "extras": {
            "collapse_key": "<Alpha numeric key>", //If two messages have same collapse key, older message is discarded on the end device.
            "time_to_live": "<integer value>", //Number of seconds that a message may be stored if the user is not immediately available. Max of 51840000.
            "customtags": {
                "key1": "object1",
                "key2": {
                    "object2": "val"
                },
                "key3": ["object3", "object4"]
            }
        }

    }
}

push > web > extras

ParameterTypeMandatoryDescription
collapse_keyStringNoAn arbitrary string that is used to replace the older message with new message when the older message did not reached the destination.

Note:The parameter collapse_key is not applicable to safari browser.
time_to_liveStringNoExpiry time for the message in seconds.
customtagsJSONObjectNoA user defined key-value pair. The value can be a string or JSON object, or a JSON array.

push > interactive

The following parameters are part of the interactive parameter block which in turn is part of the push block.

ParameterTypeMandatoryDescription
device_typesJSONArrayYes, atleast oneThe device types that should receive the interactive notifications.

android
ios
windows
pushrefStringNoThis is an optional parameter to be defined in the push JSON if the sender intends to use the push interaction result as a trigger for rules.
categoryStringYesEither one the below categories should be passed

SINGLE_DISMISS
SINGLE_OPEN
SINGLE_SUBSCRIBE
SINGLE_UNSUBSCRIBE
SINGLE_SHARE
SINGLE_DEEPLINK
SINGLE_REPLY
DOUBLE_YES_NO
DOUBLE_ACCEPT_CANCEL
DOUBLE_SHARE_CANCEL
DOUBLE_SHOPNOW_CANCEL
DOUBLE_LATER_NOW
DOUBLE_PLAY_NOW_PLAY_LATER
DOUBLE_OK_LEARN_MORE
DOUBLE_SUBSCRIBE_UNSUBSCRIBE
DOUBLE_BUY_NOW_BUY_LATER
DOUBLE_LIKE_SHARE
actionsJSONArrayYesThe JSON array should contain the following.

{
"pos": 1,
"action": "",
"identifier":
"value": ""
}

pos
Specifies the position of the button. Either 1 or 2.
action
Action for the notification buttons. Available actions are

DISMISS
OPENURL (Requires URL to be opened in value parameter)
OPEN_APP
DEEPLINK (Requires app page to be opened in value parameter)
OPENWEBVIEW (Requires URL to be opened in value parameter)
SHARE (Requires the content to be shared)

identifier
Identifier depends on the action. For example, if the action is _DOUBLE_SHOPNOW_CANCEL
, then identifier 1 will be SHOPNOW identifier 2 will be CANCEL. Refer to Push notification section for detail list of all identifiers
value
Specifies the value for the action.
{
            "pushref": "<Provide a reference value if the results of the push interaction is required as a trigger for rules.>",
            "ios": {
                "text": "<iOS specific push message text>",
                "extras": {Refer to iOS extras}
            },
            "android": {
                "text": "<Android specific message text>",
                "extras": {Refer to Android extras}
            },
            "web": {
                "title": "<title text for web browser push message>",
                "text": "<push message text for Web browser>",
                "url": "<URL that opens when message is clicked>",
                "actiontext": "<Specifies the text for button for safari browsers only>",
                "platorm_types": "<specifies the browser to which the message is sent>",
                "extras": {Refer to web extras}
            },
            "interactive": {
                "device_types": [
                    "ios",
                    "android"
                ],
                "category": "<Each category has a specific context and associated set of actions. Refer to the list of categories.>",
                "actions": [{
                    "pos": 1,
                    "action": "<Actions depend on the category>",
                    "value": "<Value depends on the action>"
                }, {
                    "pos": 2,
                    "action": "<Actions depend on the category>",
                    "value": "<Value depends on the action>"
                }]
            }
        }
{
	"ios":{
		"text":"This is a push notification",
		"title":"Hello"
	}
}
{
	"android":{
		"text":"This is a push notification",
		"title":"Hello"
	}
}
{
	"android":{
		"text":"Android message",
		"extras":{
			"sound":"default",
			"customtags":{
				"imageurl":"http://www.fox.com/wp-content/uploads/2014/01/5.jpg"
			}
		}
	},
	"ios":{
		"text":"iOS Push message",
		"extras":{
			"sound":"default"
		}
	}
}
{
	"ios":{
		"text":"Test Notification Action3",
		"extras":{
			"notificationaction":{
				"action":"DEEPLINK",
				"value":"PM19092429://command/settings"
			}
		}
	},
	"android":{
		"text":"Test Notification Action3",
		"extras":{
			"notificationaction":{
				"action":"DEEPLINK",
				"value":"PM19092429://command/topic"
			}
		}
	},
	"windows":{
		"text":[
			"windows push test",
			"windows push test1",
			"windows push test2"
		],
		"extras":{
			"notificationaction":{
				"action":"DEEPLINK",
				"value":"PM19092429://command/streams"
			}
		}
	}
}
{
	"android":{
		"extras":{
			"sound":"default"
		},
		"text":"asdsad"
	},
	"pushref":"4321",
	"interactive":{
		"category":"DOUBLE_YES_NO",
		"device_types":[
			"ios",
			"android",
			"windows"
		],
		"actions":[
			{
				"identifier":"YES",
				"pos":1,
				"action":"OPEN_APP"
			},
			{
				"identifier":"NO",
				"pos":2,
				"action":"SHARE",
				"value":"54333"
			}
		]
	},
	"ios":{
		"extras":{
			"sound":"default"
		},
		"text":"Hello",
		"title":"This is a push notification"
	}
}

Facebook Messenger

{
    "appid": "<app-id>",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "text": "Welcome to Webex Connect",
                "notification_type": "NO_PUSH"or"SILENT_PUSH",
                "messaging_type": "MESSAGE_TAG",
                "tag": "ACCOUNT_UPDATE",
								"quick_replies": [{
                    "content_type": "text",
                    "title": "Red",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED"
                }, {
                    "content_type": "text",
                    "title": "Green",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN"
                }],
                "type": "conversation"
            }
        }
    },
    "destination": [
        {
            "psid": [
                "<psid>"
            ]
        }
    ]
}
ParameterTypeMandatoryDescription
textStringNoSpecifies the message text. Note: Either text _or _attachment or sender_action is mandatory.
attachmentJSONObjectNoA block consists of the following parameters:

type
payload

Note: Either text _or _attachment or sender_action is mandatory.
notification_typeStringNoSpecifies the notification to be received with a sound or without sound. The options are:

REGULAR (Default): The notification will be sent with a sound.
NO_PUSH: The notification will not be sent.
sender_actionStringNoSpecifies the message state. The options are:

markseen
typing_on
typing_off

Note: Either _text
or attachment or sender_action is mandatory.
quick_repliesJSONArrayNoSpecifies an options in the text message to reply back to the sender. When the quick reply is tapped, the message is sent with the option tapped. Once the message is sent, the options disappear.
messaging_typeStringNoSpecifies the messaging type. The options are:

RESPONSE - Use this messaging type if you are responding to a received message. This includes messages sent inside the 24-hour standard messaging window. For example, use this tag to respond if a person asks for a reservation confirmation or an status update.

UPDATE - Use this messaging type if you are proactively sending a message and not in response to a received message. This includes messages sent inside the the 24-hour standard messaging window.

MESSAGE_TAG - Message is non-promotional and is being sent outside the 24-hour standard messaging window with a message tag. The message must match the allowed use case for the tag
Specify the tag using 'tag' field.

Refer to Messenger Node to know the list of supported tags.
  • attachment
ParameterTypeMandatoryDescription
typeStringYesSpecifies the type of the attachment. The options are:

image
audio
video
file
template
payloadJSONObjectYesSpecifies the payload of attachment. The parameters of payload are:

template_type: There are seven types of templates:
generic
button
receipt
airline_itinerary
airline_checkin
airline_boardingpass
airline_flight_update

elements: Specifies the parameters of the selected template type in an array.

attachment type - media

{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"image",
               "payload":{
                  "url":"<image-url>"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"audio",
               "payload":{
                  "url":"<audio-url>"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"video",
               "payload":{
                  "url":"<video-url>"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"file",
               "payload":{
                  "url":"<file-url>"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

attachment type - template

Generic Template
Generic template allows you to send horizontal scrollable set of images with an option to configure short description and buttons to request input from the users. You can add up to 10 images per message. For more information on generic template, click here.

ParameterTypeMandatoryDescription
titleStringYesSpecifies the bubble title. It has a limit of 80 characters.
item_urlStringNoSpecifies the URL that is opened when bubble is tapped.
image_urlStringNoSpecifies the bubble image.
subtitleStringNoSpecifies the bubble subtitle. It has a limit of 80 characters.
buttonsJSONArrayNoSpecifies a set of buttons that appears as call-to-actions. You can add up to 3 buttons only. The parameters are:

type
title
url
payload
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"generic",
                  "elements":[
                     {
                        "title":"Classic White T-Shirt",
                        "image_url":"http://petersapparel.parseapp.com/img/item100-thumb.png",
                        "subtitle":"Soft white cotton t-shirt is back in style",
                        "buttons":[
                           {
                              "type":"web_url",
                              "url":"https://petersapparel.parseapp.com/view_item?item_id=100",
                              "title":"View Item"
                           },
                           {
                              "type":"web_url",
                              "url":"https://petersapparel.parseapp.com/buy_item?item_id=100",
                              "title":"Buy Item"
                           },
                           {
                              "type":"postback",
                              "title":"Bookmark Item",
                              "payload":"check"
                           }
                        ]
                     },
                     {
                        "title":"Giordano 60058 Black/Orange Analog Watch - For Men",
                        "image_url":"http://img6a.flixcart.com/image/watch/g/q/z/60058-black-orange-giordano-400x400-imae7c8rhnp4rfze.jpeg",
                        "subtitle":"Watch Watch",
                        "buttons":[
                           {
                              "type":"web_url",
                              "url":"http://www.flipkart.com/giordano-60058-black-orange-analog-watch-men/p/itmdw4v6gkgejetj?pid=WATDW4V5GYEYQGQZ&al=rWnbPKcgb3ESJptH0q72XsldugMWZuE7Phn6Yd2VMSLMQz8fzEH13Ce0tGaT7ePiWmFmBeJJs7Q%3D&offer=nb%3Amp%3A0405c80713&ref=L%3A-7770517350658453810&srno=b_1",
                              "title":"View Item"
                           },
                           {
                              "type":"web_url",
                              "url":"https://petersapparel.parseapp.com/buy_item?item_id=101",
                              "title":"Buy Item"
                           },
                           {
                              "type":"postback",
                              "title":"Bookmark Item",
                              "payload":"USER_DEFINED_PAYLOAD_FOR_ITEM101"
                           }
                        ]
                     }
                  ]
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

Button Template
Button template allows you to send a text and buttons attachment to request input from the user. The buttons can open a URL or make a back-end call to your webhook. For more information on button template, click here.

ParameterTypeMandatory
textStringYesThe text that appears in the main body.
buttonsJSONArrayNoSpecifies a set of buttons that appears as call-to-actions. Click here to view the button object.
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"button",
                  "text":"",
                  "buttons":[
                     {
                        "type":"web_url",
                        "url":"https://www.google.co.in/maps/@17.4495157,78.4000172,16z?hl=en",
                        "title":"Show location"
                     },
                     {
                        "type":"postback",
                        "title":"Start Chatting",
                        "payload":"1232"
                     },
                     {
                        "type":"phone_number",
                        "title":"Call Representative",
                        "payload":"+9177xxxxxxxx"
                     }
                  ]
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

You can add up to 3 buttons only. The parameters are:

ParameterTypeMandatoryDescription
typeStringYesSpecifies the value for button. The options are:

web_url
postback
titleStringYesSpecifies the button title.
urlStringYesSpecifies the web_url for buttons. It opens a browser when the button is tapped.
payloadStringYesWhen the postback button is clicked an event is raised that can be used to write rules.

Receipt Template
Receipt template allows you to send an order confirmation, with the transaction summary and description for each item. For more information on receipt template, click here.

ParameterTypeMandatoryDescription
recipient_nameStringYesSpecifies the recipients name.
order_numberStringYesspecifies the order number.
currencyStringYesSpecifies the currency for order.
payment_methodStringYesSpecifies the payment method details.
timestampStringNoSpecifies the timestamp of order. It must be a unique number.
order_urlStringNoSpecifies the URL of order.
elementsJSONArrayYesSpecifies the details of the order. The parameters are:

title
subtitle
quantity
price
currency
image_url
addressJSONObjectNoSpecifies the details of the shipping address. The parameters are:

street_1
street_2
city
postal_code
summaryJSONObjectYesSpecifies the payment summary details. The parameters are:

subtotal
shipping_cost
total_tax
adjustmentsJSONArrayNoSpecifies the payment adjustments. The parameters are:

name
amount
{
    "appid": "<appid>",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "receipt",
                        "recipient_name": "Stephane Crozatier",
                        "order_number": "1234444415678902",
                        "currency": "USD",
                        "payment_method": "Visa 2345",
                        "order_url": "http://petersapparel.parseapp.com/order?order_id=123456",
                        "timestamp": "1428444852",
                        "elements": [
                            {
                                "title": "Classic White T-Shirt",
                                "subtitle": "100% Soft and Luxurious Cotton",
                                "quantity": 2,
                                "price": 50,
                                "currency": "USD",
                                "image_url": "http://petersapparel.parseapp.com/img/whiteshirt.png"
                            },
                            {
                                "title": "Classic Gray T-Shirt",
                                "subtitle": "100% Soft and Luxurious Cotton",
                                "quantity": 1,
                                "price": 25,
                                "currency": "USD",
                                "image_url": "http://petersapparel.parseapp.com/img/grayshirt.png"
                            }
                        ],
                        "address": {
                            "street_1": "1 Hacker Way",
                            "street_2": "",
                            "city": "Menlo Park",
                            "postal_code": "94025",
                            "state": "CA",
                            "country": "US"
                        },
                        "summary": {
                            "subtotal": 75.00,
                            "shipping_cost": 4.95,
                            "total_tax": 6.19,
                            "total_cost": 56.14
                        },
                        "adjustments": [
                            {
                                "name": "New Customer Discount",
                                "amount": 20
                            },
                            {
                                "name": "$10 Off Coupon",
                                "amount": 10
                            }
                        ]
                    }
                }
            }
        }
    }
}
},
"destination": [
{
    "psid": [
        "<psid>"
    ]
}
]
}

Specifies the details of the order in receipt template. It accepts an array.

ParameterTypeMandatoryDescription
titleStringYesSpecifies the title of the item.
subtitleStringNoSpecifies the sub title of item.
quantityIntegerNoSpecifies the quantity of item.
priceDoubleNoSpecifies the item price.
currencyStringNoSpecifies the currency of price.
image_urlStringNoSpecifies the image URL of item.

Specifies the details of the shipping address.

ParameterTypeMandatoryDescription
street_1StringYesSpecifies the street address, line 1.
street_2StringNoSpecifies the street address, line 2.
cityStringYesSpecifies the city details.
postal_codeStringYesSpecifies the postal code.
stateStringYesSpecifies the state abbreviation of a country.
countryStringYesSpecifies the two letter abbreviation of a country.

Specifies the payment summary details. The parameters are:

ParameterTypeMandatoryDescription
subtotalNumberNoSpecifies the subtotal.
shipping_costNumberNoSpecifies the cost of shipping.
total_taxNumberNoSpecifies the total tax.
total_costNumberNoSpecifies the total cost.

Specifies the payment adjustments. The parameters are:

ParameterTypeMandatoryDescription
nameStringNoSpecifies the name of adjustment.
amountNumberNoSpecifies the adjusted amount.

Airline Itinerary Template

❗️

Airline Itinerary Template is now deprecated

Airline Itinerary Template is deprecated and the messaging API call will fail with a delivery receipt notification.

An airline itinerary template is used to send airline itinerary and receipt. For more information on the airline boarding pass template, click here.

ParameterTypeMandatoryDescription
template_typeStringYesSpecifies the template type. The value must be airline_itinerary.
intro_messageStringYesSpecifies the introduction message.
localeStringYesSpecifies the two-letter language region code. For example, en_US.
theme_colorStringNoSpecifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.
pnr_numberStringYesSpecifies the passenger name record number.
passenger_infoJSONArrayYesSpecifies an array of passenger information. Refer to passenger_info object.
flight_infoJSONArrayYesSpecifies the flight information. Refer to flight_info object.
passenger_segment_infoJSONArrayYesSpecifies the information unique to passenger or segment pair. Refer to passenger_segment_info object.
price_infoJSONArrayNoSpecifies the itemized price information. Refer to price_info object.
base_priceNumberNoSpecifies the base price amount.
taxNumberNoSpecifies the tax amount.
total_priceNumberYesSpecifies the total price of the booking.
currencyStringYesSpecifies the currency code. For example, to display American dollars the code is USD.
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"airline_itinerary",
                  "intro_message":"Here's your flight itinerary.",
                  "locale":"en_US",
                  "pnr_number":"ABCDEF",
                  "passenger_info":[
                     {
                        "name":"Farbound Smith Jr",
                        "ticket_number":"0741234567890",
                        "passenger_id":"p001"
                     },
                     {
                        "name":"Nick Jones",
                        "ticket_number":"0741234567891",
                        "passenger_id":"p002"
                     }
                  ],
                  "flight_info":[
                     {
                        "connection_id":"c001",
                        "segment_id":"s001",
                        "flight_number":"KL9123",
                        "aircraft_type":"Boeing 737",
                        "departure_airport":{
                           "airport_code":"SFO",
                           "city":"San Francisco",
                           "terminal":"T4",
                           "gate":"G8"
                        },
                        "arrival_airport":{
                           "airport_code":"SLC",
                           "city":"Salt Lake City",
                           "terminal":"T4",
                           "gate":"G8"
                        },
                        "flight_schedule":{
                           "departure_time":"2016-01-02T19:45",
                           "arrival_time":"2016-01-02T21:20"
                        },
                        "travel_class":"business"
                     },
                     {
                        "connection_id":"c002",
                        "segment_id":"s002",
                        "flight_number":"KL321",
                        "aircraft_type":"Boeing 747-200",
                        "travel_class":"business",
                        "departure_airport":{
                           "airport_code":"SLC",
                           "city":"Salt Lake City",
                           "terminal":"T1",
                           "gate":"G33"
                        },
                        "arrival_airport":{
                           "airport_code":"AMS",
                           "city":"Amsterdam",
                           "terminal":"T1",
                           "gate":"G33"
                        },
                        "flight_schedule":{
                           "departure_time":"2016-01-02T22:45",
                           "arrival_time":"2016-01-03T17:20"
                        }
                     }
                  ],
                  "passenger_segment_info":[
                     {
                        "segment_id":"s001",
                        "passenger_id":"p001",
                        "seat":"12A",
                        "seat_type":"Business",
                        "product_info":[
                           {
                              "title":"Lounge",
                              "value":"Complimentary lounge access"
                           },
                           {
                              "title":"Baggage",
                              "value":"1 extra bag 50lbs"
                           }
                        ]
                     },
                     {
                        "segment_id":"s001",
                        "passenger_id":"p002",
                        "seat":"12B",
                        "seat_type":"Business",
                        "product_info":[
                           {
                              "title":"Lounge",
                              "value":"Complimentary lounge access"
                           },
                           {
                              "title":"Baggage",
                              "value":"1 extra bag 50lbs"
                           }
                        ]
                     },
                     {
                        "segment_id":"s002",
                        "passenger_id":"p001",
                        "seat":"73A",
                        "seat_type":"World Business",
                        "product_info":[
                           {
                              "title":"Lounge",
                              "value":"Complimentary lounge access"
                           },
                           {
                              "title":"Baggage",
                              "value":"1 extra bag 50lbs"
                           }
                        ]
                     },
                     {
                        "segment_id":"s002",
                        "passenger_id":"p002",
                        "seat":"73B",
                        "seat_type":"World Business",
                        "product_info":[
                           {
                              "title":"Lounge",
                              "value":"Complimentary lounge access"
                           },
                           {
                              "title":"Baggage",
                              "value":"1 extra bag 50lbs"
                           }
                        ]
                     }
                  ],
                  "price_info":[
                     {
                        "title":"Fuel surcharge",
                        "amount":"1597",
                        "currency":"USD"
                     }
                  ],
                  "base_price":"12206",
                  "tax":"200",
                  "total_price":"14003",
                  "currency":"USD"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

Click here to view the supported list of currencies.

The parameters of passenger_info under Airline Itinerary template are:

ParameterTypeMandatoryDescription
passenger_idStringYesSpecifies a unique passenger identification.
ticket_numberStringNoSpecifies the ticket number.
nameStringYesSpecifies the full name of the passenger.

The parameters of flight_info under Airline Itinerary template are:

ParameterTypeMandatoryDecription
connection_idStringYesSpecifies a unique id within the itinerary to group segments of a connection together.
segment_idStringYesSpecifies the segmentid of the _passenger_segment_info object.
flight_numberStringYesSpecifies the flight number.
aircraft_typeStringNoSpecifies the aircraft type.
departure_airportJSONObjectYesSpecifies the departure airport. Refer to airport object.
arrival_airportJSONObjectYesSpecifies the arrival airport. Refer to airport object.
flight_airportJSONObjectYesSpecifies the schedule for the flight. Refer to flight_schedule object.
travel_classStringYesSpecifies the travel class.

The parameters of passenger_segment_info under Airline Itinerary template are:

ParameterTypeMandatoryDescription
segment_idStringYesSpecifies a unique id within the itinerary to identify a flight segment.
passenger_idStringYesSpecifies the passenger id of passenger_info object.
seatStringYesSpecifies the seat number for the passenger.
seat_typeStringYesSpecifies the seat type for the passenger. For example, Economy comfort.
product_infoStringYesSpecifies the list of products the passenger purchased. You can add up to 4 products only.

The parameters of airport object under Airline Itinerary template are:

ParameterTypeMandatoryDescription
airport_codeStringYesSpecifies the airport code.
cityStringYesSpecifies the city name.
terminalStringNoSpecifies the terminal number.
gateStringNoSpecifies the gate number.

The parameters of flight_schedule object under Airline Itinerary template are:

ParameterTypeMandatoryDescription
boarding_timeStringNoSpecifies the boarding time in departure airport timezone.
departure_timeStringYesSpecifies the departure time in departure airport timezone.
arrival_timeStringYesSpecifies the arrival time in arrival airport timezone.

📘

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh: mm. For example, 2016-09-26T11:15.

The parameters of price_info object under Airline Itinerary template are:

ParameterTypeMandatoryDescription
titleStringYesSpecifies the product title
valueStringYesSpecifies the product description.

Airline Check-in Template

❗️

Airline Check-in Template is deprecated

Airline Check-in Template is deprecated and the messaging API call will fail with a delivery receipt notification.

Airline check-in template is used to send flight check-in reminder messages. For more information on the airline check-in template, click here.

ParameterTypeMandatoryDescription
template_typeStringYesSpecifies the template type. The value must be airline_itinerary.
intro_messageStringYesSpecifies the introduction message.
localeStringYesSpecifies the two-letter language region code. For example, en_US.
theme_colorStringNoSpecifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.
pnr_numberStringYesSpecifies the passenger name record number.
flight_infoJSONArrayYesSpecifies the flight information. Refer to flight_info object.
checkin_urlStringYesSpecifies the URL for passengers to check-in.
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"airline_checkin",
                  "intro_message":"Check-in is available now.",
                  "locale":"en_US",
                  "pnr_number":"ABCDEF",
                  "flight_info":[
                     {
                        "flight_number":"f001",
                        "departure_airport":{
                           "airport_code":"SFO",
                           "city":"San Francisco",
                           "terminal":"T4",
                           "gate":"G8"
                        },
                        "arrival_airport":{
                           "airport_code":"SEA",
                           "city":"Seattle",
                           "terminal":"T4",
                           "gate":"G8"
                        },
                        "flight_schedule":{
                           "boarding_time":"2016-01-05T15:05",
                           "departure_time":"2016-01-05T15:45",
                           "arrival_time":"2016-01-05T17:30"
                        }
                     }
                  ],
                  "checkin_url":"https:\/\/www.airline.com\/check-in"
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

The parameters of flight_info under Airline Checkin template are:

ParameterTypeMandatoryDescription
flight_numberStringYesSpecifies the flight number.
departure_airportJSONObjectYesSpecifies the departure airport.
arrival_airportJSONObjectYesSpecifies the arrival airport.
flight_scheduleJSONObjectYesSpecifies the schedule for the flight.

The parameters of flight_schedule object under Airline Checkin template are:

ParameterTypeMandatoryDescription
boarding_timeStringNoSpecifies the boarding time in departure airport timezone.
departure_timeStringYesSpecifies the departure time in departure airport timezone.
arrival_timeStringYesSpecifies the arrival time in arrival airport timezone.

📘

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh: mm. For example, 2016-09-26T11:15.

Airline Boarding Pass Template

❗️

Airline Flight Update Template is deprecated

Airline Flight Update Template is deprecated and the messaging API call will fail with a delivery receipt notification.

Airline boarding pass template allows you to send boarding passes for one or more flights to passengers. For more information on the airline boarding pass template, click here.

ParameterTypeMandatoryDescription
template_typeStringYesSpecifies the template type. The value must be airline_itinerary.
intro_messageStringYesSpecifies the introduction message.
localeStringYesSpecifies the two-letter language region code. For example, en_US.
theme_colorStringNoSpecifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.
boarding_passJSONArrayYesSpecifies the boarding passes for passengers. Refer to the boarding_pass object.
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"airline_boardingpass",
                  "intro_message":"You are checked in.",
                  "locale":"en_US",
                  "boarding_pass":[
                     {
                        "passenger_name":"SMITH\/NICOLAS",
                        "pnr_number":"CG4X7U",
                        "travel_class":"business",
                        "seat":"74J",
                        "auxiliary_fields":[
                           {
                              "label":"Terminal",
                              "value":"T1"
                           },
                           {
                              "label":"Departure",
                              "value":"30OCT 19:05"
                           }
                        ],
                        "secondary_fields":[
                           {
                              "label":"Boarding",
                              "value":"18:30"
                           },
                           {
                              "label":"Gate",
                              "value":"D57"
                           },
                           {
                              "label":"Seat",
                              "value":"74J"
                           },
                           {
                              "label":"Sec.Nr.",
                              "value":"003"
                           }
                        ],
                        "logo_image_url":"https:\/\/www.example.com\/en\/logo.png",
                        "header_image_url":"https:\/\/www.example.com\/en\/fb\/header.png",
                        "qr_code":"M1SMITH\/NICOLAS  CG4X7U nawouehgawgnapwi3jfa0wfh",
                        "above_bar_code_image_url":"https:\/\/www.example.com\/en\/PLAT.png",
                        "flight_info":{
                           "flight_number":"KL0642",
                           "departure_airport":{
                              "airport_code":"JFK",
                              "city":"New York",
                              "terminal":"T1",
                              "gate":"D57"
                           },
                           "arrival_airport":{
                              "airport_code":"AMS",
                              "city":"Amsterdam"
                           },
                           "flight_schedule":{
                              "departure_time":"2016-01-02T19:05",
                              "arrival_time":"2016-01-05T17:30"
                           }
                        }
                     },
                     {
                        "passenger_name":"JONES\/FARBOUND",
                        "pnr_number":"CG4X7U",
                        "travel_class":"business",
                        "seat":"74K",
                        "auxiliary_fields":[
                           {
                              "label":"Terminal",
                              "value":"T1"
                           },
                           {
                              "label":"Departure",
                              "value":"30OCT 19:05"
                           }
                        ],
                        "secondary_fields":[
                           {
                              "label":"Boarding",
                              "value":"18:30"
                           },
                           {
                              "label":"Gate",
                              "value":"D57"
                           },
                           {
                              "label":"Seat",
                              "value":"74K"
                           },
                           {
                              "label":"Sec.Nr.",
                              "value":"004"
                           }
                        ],
                        "logo_image_url":"https:\/\/www.example.com\/en\/logo.png",
                        "header_image_url":"https:\/\/www.example.com\/en\/fb\/header.png",
                        "qr_code":"M1JONES\/FARBOUND  CG4X7U nawouehgawgnapwi3jfa0wfh",
                        "above_bar_code_image_url":"https:\/\/www.example.com\/en\/PLAT.png",
                        "flight_info":{
                           "flight_number":"KL0642",
                           "departure_airport":{
                              "airport_code":"JFK",
                              "city":"New York",
                              "terminal":"T1",
                              "gate":"D57"
                           },
                           "arrival_airport":{
                              "airport_code":"AMS",
                              "city":"Amsterdam"
                           },
                           "flight_schedule":{
                              "departure_time":"2016-01-02T19:05",
                              "arrival_time":"2016-01-05T17:30"
                           }
                        }
                     }
                  ]
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

The parameters of boarding_pass object under Airline Boarding Pass template are:

ParameterTypeMandatoryDescription
passenger_nameStringYesSpecifies the passenger name.
pnr_numberStringYesSpecifies the passenger name record number.
travel_classStringNoSpecifies the travel class. The options are:

economy
business
first_class
seatStringNoSpecifies the seat number for the passenger.
auxiliary_fieldsJSONArrayNoSpecifies the flexible information to display in the auxiliary section. You can add up to 5 fields. Refer to field object.
secondary_fieldsJSONArrayNoSpecifies the flexible information to display in the secondary section. You can add up to 5 fields. Refer to field object.
logo_image_urlStringYesSpecifies the URL for the logo image.
header_image_urlStringNoSpecifies the URL for the header image.
header_text_fieldStringNoSpecifies the text for the header field.
qr_codeStringYes, unless the image of barcode is provided.Specifies Aztec or QR code.
barcode_image_urlStringYes, unless the qr_code is provided.Specifies the URL of the bar code image.
above_bar_code_image_urlStringYesSpecifies the URL of thin image above the bar code.
flight_infoJSONObjectYesSpecifies the information about the flight. Refer to flight_info object.

The parameters of flight_info under Airline Boarding Pass template are:

ParameterTypeMandatoryDescription
flight_numberStringYesSpecifies the flight number.
departure_airportJSONObjectYesSpecifies the departure airport. Refer to airport object.
arrival_airportJSONObjectYesSpecifies the arrival airport. Refer to airport object.
flight_scheduleJSONObjectYesSpecifies the schedule for the flight. Refer to flight_schedule object.

The parameters of flight_schedule object under Airline Boarding Pass template are:

ParameterTypeMandatoryDescription
boarding_timeStringNoSpecifies the boarding time in departure airport timezone.
departure_timeStringYesSpecifies the departure time in departure airport timezone.
arrival_timeStringNoSpecifies the arrival time in arrival airport timezone.

📘

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh: mm. For example, 2016-09-26T11:15.

The parameters of airport object under Airline Boarding Pass template are:

ParameterTypeMandatoryDescription
airport_codeStringYesSpecifies the airport code.
cityStringYesSpecifies the city name.
terminalStringNoSpecifies the terminal number.
gateStringNoSpecifies the gate number.

📘

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

The parameters of field object under Airline Boarding Pass template are:

ParameterTypeMandatoryDescription
labelStringYesSpecifies the label for the additional field.
valueStringYesSpecifies the value for the additional field.

Airline Flight Update Template

❗️

Airline Flight Update Template is deprecated

Airline Flight Update Template is deprecated and the API calls will fail notified on message delivery receipt.

Airline flight update template allows you to send flight status update messages. For more information on the airline flight update template, click here.

ParameterTypeMandatoryDescription
template_typeStringYesSpecifies the template type. The value must be airline_update.
intro_messageStringNoSpecifies the introduction message.
update_typeStringYesSpecifies the type of update for the notification. The options are:

delay
gate_change
cancellation
localeStringYesSpecifies the two-letter language region code. For example, en_US.
theme_colorStringNoSpecifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.
pnr_numberStringYesSpecifies the passenger name record number.
update_flight_infoJSONObjectYesSpecifies the information about a flight. Refer to update_flight_info object.
{
   "appid":"<appid>",
   "deliverychannel":"fb",
   "channels":{
      "OTT-Messaging":{
         "fb":{
            "attachment":{
               "type":"template",
               "payload":{
                  "template_type":"airline_update",
                  "intro_message":"Your flight is delayed",
                  "update_type":"delay",
                  "locale":"en_US",
                  "pnr_number":"CF23G2",
                  "update_flight_info":{
                     "flight_number":"KL123",
                     "departure_airport":{
                        "airport_code":"SFO",
                        "city":"San Francisco",
                        "terminal":"T4",
                        "gate":"G8"
                     },
                     "arrival_airport":{
                        "airport_code":"AMS",
                        "city":"Amsterdam",
                        "terminal":"T4",
                        "gate":"G8"
                     },
                     "flight_schedule":{
                        "boarding_time":"2015-12-26T10:30",
                        "departure_time":"2015-12-26T11:30",
                        "arrival_time":"2015-12-27T07:30"
                     }
                  }
               }
            }
         }
      }
   },
   "destination":[
      {
         "psid":[
            "<psid>"
         ]
      }
   ]
}

The parameters of update_flight_info under Airline Flight Update template are:

ParameterTypeMandatoryDescription
flight_numberStringYesSpecifies the flight number.
departure_airportJSONObjectYesSpecifies the departure airport. Refer to airport object.
arrival_airportJSONObjectYesSpecifies the arrival airport. Refer to airport object.
flight_scheduleJSONObjectYesSpecifies the schedule for the flight. Refer to flight_schedule object.

The parameters of flight_schedule under Airline Flight Update template are:

ParameterTypeMandatoryDescription
boarding_timeStringNoSpecifies the boarding time in departure airport timezone.
departure_timeStringYesSpecifies the departure time in departure airport timezone.
arrival_timeStringNoSpecifies the arrival time in arrival airport timezone.

📘

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

  • sender action
    Sender action feature allows you to set typing indicators or send read receipts to let users know that someone is typing or the message is read. Typically this feature is used in chat conversations. When you are processing a time-consuming request, you can send a typing indicator. The typing indicator gives an impression to your users that someone is replying to their request. For more information on sender action, click here.

{
  "appid": "<app-id>",
  "deliverychannel": "fb",
  "channels": {
    "OTT-Messaging": {
      "fb": {
        
    "sender_action":"typing_on"

   
      }
    }
  },
  "destination": [
    {
      "psid":["<psid>"] 
    }
  ]
}
  • Quick_ Replies

Quick Replies are buttons with some text that appears above the text composer. Users can tap on the button to respond to the message. Once the message is tapped, the options disappear. You can add up to 10 buttons. These buttons are useful to get a specific response from the users. You can configure buttons to have a plain text or a combination of text and image. You can also configure a button with location so that users can send geographic locations in the conversation. You can configure the button with a payload that can have custom data that will be sent back to the enterprises through a webhook. For additional information on Quick Replies, click here.

ParameterTypeMandatoryDescription
content_typeStringYesSpecifies the type of content. The options are:

text
location
titleStringYes. This is applicable only when content_type is set as text.Specifies the caption for button. You can add up to 20 characters as title.
payloadStringYes. This is applicable only when content_type is set as text.Specifies the custom data that will be sent back to you through web hook. The limit of this payload is 1000 characters.
image_urlStringNoSpecifies the URL of the image sent as quick_replies.
{
  "appid": "<app-id>",
  "deliverychannel": "fb",
  "channels": {
    "OTT-Messaging": {
      "fb":{
	"text":"Customer id check 1",
	"quick_replies":[
		{
			"content_type":"text",
			"title":"Red",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED"
		},
		{
			"content_type":"text",
			"title":"Green",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN"
		},
		{
			"content_type":"text",
			"title":"Yellow",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_YELLOW"
		},
		{
			"content_type":"text",
			"title":"Orange",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_ORANGE"
		},
		{
			"content_type":"text",
			"title":"Pink",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_PINK"
		},
		{
			"content_type":"text",
			"title":"Brown",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BROWN"
		},
		{
			"content_type":"text",
			"title":"Blue",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLUE"
		},
		{
			"content_type":"text",
			"title":"Black",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLACK"
		},
		{
			"content_type":"text",
			"title":"Magenta",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLACK"
		},
		{
			"content_type":"text",
			"title":"Voilate",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_VOILATE"
		}
	],
	"type":"conversation"
}
}
  },
  "destination": [
    {
      "psid":["<psid>"] 
    }
  ]
}
{
  "appid": "<app-id>",
  "deliverychannel": "fb",
  "channels": {
    "OTT-Messaging": {
      "fb":{
	"text":"Customer id check 1",
	"quick_replies":[
		{
			"content_type":"text",
			"title":"Red",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED",
			"image_url":"http://www.gstatic.com/webp/gallery/1.jpg"
		},
		{
			"content_type":"text",
			"title":"Green",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Yellow",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_YELLOW",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Orange",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_ORANGE",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Pink",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_PINK",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Brown",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BROWN",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Blue",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLUE",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		},
		{
			"content_type":"text",
			"title":"Voilate",
			"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_VOILATE",
			"image_url":"https://www.gstatic.com/webp/gallery3/1.png"
		}
	],
	"type":"conversation"
}
}
  },
  "destination": [
    {
      "psid":["<psid>"] 
    }
  ]
}

Response Codes

Webex Connect Messaging API is an asynchronous API. When you make a Messaging API call, Webex Connect returns an immediate response code and description to confirm whether your request has been successfully queued or not. Here's the list of various response codes with their description.

You can provide a 'notifyURL' and 'callbackData' identifier in the request payload to track the message delivery status.

Response CodeMessageDescription
1001QueuedReturned when the request is accepted by imiconnect.
7000Invalid JSONReturned when an invalid JSON request is sent.
7001Authentication failedReturned when an invalid service key or profile key is provided in the request.
7002Service key missingReturned when the parameter key is missing in the message request.
7003Mandatory parameters missingReturned when the mandatory parameters configured in custom event are missing.
7004Invalid parametersReturned when the parameters are invalid.
7006Internal error occurredReturned when an internal error occurs.
7007Service inactiveReturned when the service is in inactive state.
7009Max number of destinationsReturned when an API request exceeds the limit (1000) to send messages using messaging API.
7722Parameter value is invalidReturned when the namespace used in WhatsApp message does not correspond to the WABA id.
Language
Authorization
Header