v1.0

Routeon OMNIAPI

Routeon OMNIAPI is an interface tool that provides an API for external systems that can send messages through Routeon.

Authorization

Using API key

The API key must be passed in the X-API-Key header.
The API key will be generated in the client account, in API Accesses section.

Response

If the message is received successfully, the API will respond with a 202 Accepted code and details in the response body.
If the message is not received successfully, the API will respond with a corresponding HTTP code and details in the response body.
A successful message reception does not mean its successful sending to the user's device. You will receive information about further fate of the message, including sending, delivery and read statuses, asynchronously via webhook requests.

Webhook

In order to receive sending, delivery and read notifications, as well as user responses, it is necessary to specify the URL from which your hardware expects these notifications as a Webhook URL in the corresponding "Sender group" in the profile.

The Webhook URL is resolved in the following order (first non-empty value is used):

webhook field in the request body
Webhook configured for the Sender
Webhook configured for the API access (API key or Basic Auth login)

Request body

Field	Type	Mandatory	Description
contact	string	Yes	Recipient's phone number. With country code, without "+".
channel	int	Yes	Channel for message sending 4 is always used for WhatsApp.
senderId	string	Yes	Sender ID (sender's name) for message sending. For WhatsApp channel phone number linked to the WhatsApp Business Account is used for WhatsApp.
payload	Object Payload	Yes	Message content The content format differs depending on the channel.
webhook	string	No	Webhook URL to which message status reports should be sent. Optional field: if not specified, the webhook URL specified in the Sender ID settings will be used.
clientInfo	string	No	Custom field saved in EDR.
isOtp	bool	No	Flag that message content is one time password (OTP), that need to be hided. Optional field: if true, message content will be replaced by safe for reading text.
successOn	string	No	(Only for omnimessages) The message status indicating that the fallback was succeeded and there is no need to send a next message after the timeout. Optional field: if not specified, the condition is set to "sent".
timeout	int	No	(Only for omnimessages) The period of time in seconds after which, if the fallback was not succeeded, a next message will be sent. Optional field: if not specified, the timeout is set to 20 minutes.
cooldown	int	No	(Only for omnimessages) The period of time in seconds for lockout contact or contacts if the last message in the fallback was not succeeded after the timeout. Optional field: if not specified, contacts lockout is disabled.

Payload

Sms payload

Field	Type	Description
"text"	string	Text message content

Example

{
  "payload": {
    "text": "Test from omni-api"
  }
}

Rcs payload

Field	Type	Mandatory	Description
RCSMessage	RCSMessage Object	Yes	A valid RCS message

RCSMessage Object

Field	Type	Mandatory	Description
suggestedResponse	Object	No	This is the Suggested Response JSON object following UP 2.0 specification, a.k.a. the "response" object defined in 3.6.10.3 of RCC.07 [2]. This can only be sent from the user to the Chatbot.
sharedData	Object	No	This is the Shared Data JSON object following UP 2.0 specification, a.k.a. the "sharedData" object defined in 3.6.10.3 of RCC.07 [2]. This can only be sent from the user to the Chatbot.
isTyping	string	No	The isTyping notification to be sent to the user for the given Chat, or the isTyping notification received from the user for the given Chat. If sending the isTyping notification to the user, the value can be set to 'active' or 'idle'. According to RFC3994, the default active-state refresh interval is 120 seconds, and the default idle time-out interval is 15 seconds. In other words, if no 'active' notification is sent by the bot within 15 seconds, the platform will send the 'idle' notification to the user.
suggestedChipList	SuggestedChipList Object	No	This is the Suggested Chip List JSON object following UP 2.0 specification, a.k.a. the "suggestions" object defined in 3.6.10.3 of RCC.07 [2]. The Chatbot shall not send a chip list alone and it has to be associated with a RCSContentMessage.
textMessage	string	No	This is a normal RCS text based Chat message defined in 3.2.3 of RCC.07 [2].
fileMessage	FileMessage Object	No	The RCS file transfer.
audioMessage	AudioMessage Object	No	The RCS audio message.
geolocationPushMessage	GeolocationPushMessage Object	No	The RCS geolocation push.
richcardMessage	RichcardMessage Object	No	This is the Rich Card JSON object following UP 2.0 specification, a.k.a. the "message" object defined in 3.6.10.3 of RCC.07 [2].

RCSMessage Objects

FileMessage Object

Field	Type	Mandatory	Description
thumbnailFileName	string	No	The file name of the thumbnail.
thumbnailUrl	string (url)	No	The URL of the thumbnail.
thumbnailMIMEType	string	No	The MIME type of the thumbnail.
thumbnailFileSize	integer	No	The size of the thumbnail.
fileName	string	No	The file name.
fileUrl	string (url)	Yes	The URL of the file.
fileMIMEType	string	No	The MIME type of the file.
fileSize	integer	No	The size of the file.

AudioMessage Object

Field	Type	Mandatory	Description
fileName	string	No	The file name.
fileUrl	string (url)	Yes	The URL of the file.
fileMIMEType	string	No	The MIME type of the file.
fileSize	integer	No	The size of the file.
playingLength	integer minimum: 1 maximum: 600	No	The playing length of the audio.

GeolocationPushMessage Object

Field	Type	Mandatory	Description
label	string maxLength: 200	No	This can be used to tag the nature of the location.
timestamp	string(date-time)	No	This is the time when the location information was pushed.
expiry	string(date-time)	No	This is an absolute date at which time the recipient is no longer permitted to possess the location information.
timeOffset	integer	No	This is the time zone where the location information was pushed, expressed as the number of minutes away from UTC as defined in [RFC4480].
pos	string	Yes	This is the coordinates in WGS 84 (latitude, longitude) decimal notion as described in [RFC5491], providing the latitude and longitude as “double”-encoded decimal numbers (as specified in [GML3.1.1]) representing the degrees, separated by a space starting with the latitude.
radius	number	No	The radius of the circle will be represented in meters, which will be indicated by setting the unit of measure attribute of the radius element to the value of EPSG9001 as described in [RFC5491].

SuggestedChipList Object

Suggested Chip List Item

The list is an array of objects of the following form:

{
  "<TYPE>": {
    "<ACTION_CATEGORY>": {
      "<ACTION>": {
        <...>
      }
    },
    "displayText": "<...>",
    "postback": {
      "data": "<...>"
    }
  }
}

The <TYPE> for a proposed response should be reply and for an action it should be action.
The <ACTION_CATEGORY> property defines an action and is not present in responses (see below for more information on what actions and action categories are).
The displayText property specifies the name of the button for this response/action, and for the response this is the response text.
In the postback/data property, the chatbot specifies arbitrary data that will be sent back to it along with a reply/notification that the user has clicked on the button for this reply/action.

Action categories

urlAction

`urlAction` action category

Action	Description
openUrl	Opens a URL in a browser or application over a diplink

Action `openUrl`

Field	Type	Mandatory	Description
url	string	Yes	URL to open
application	string	Yes	The application in which you want to open the link. So far, two possible values: `browser` - open in a browser, `webview` - open as webview directly in the message application.
viewMode	string	No	Webview mode. So far there are three possible values `full`, `half` or `tall`. Only applicable if `"application": "webview"`.

dialerAction

`dialerAction` action category

Action	Description
dialPhoneNumber	Starts a call to the specified number
dialEnrichedCall	Starts an RCS Enriched call to the specified number
dialVideoCall	Starts a video call to the specified number

Action `dialPhoneNumber`

Field	Type	Mandatory	Description
phoneNumber	string	Yes	The number to call
fallbackUrl	string	No	URL to be pulled if a call cannot be made (e.g., skype call)

Action `dialEnrichedCall`

Field	Type	Mandatory	Description
phoneNumber	string	Yes	The number to call
subject	string	No	Call subject
fallbackUrl	string	No	URL to be pulled if a call cannot be made (e.g., skype call)

Action `dialVideoCall`

Field	Type	Mandatory	Description
phoneNumber	string	Yes	The number to call
fallbackUrl	string	No	URL to be pulled if a call cannot be made (e.g., skype call)

mapAction

`mapAction` action category

Action	Description
showLocation	Shows the location(s) on the map by specified coordinates or specified search query
requestLocationPush	Requests the user to share their current location

Action `showLocation`

Field	Type	Mandatory	Description
location	Location Object	Yes	Object with location properties
fallbackUrl	string	No	URL to open if you cannot display the location in the messaging app, such as a link to Google maps

Location Object

Field	Type	Mandatory	Description
latitude	string	Yes if "query" is not set	Latitude
longitude	string	Yes if "query" is not set	Longitude
label	string	No	Location tag
query	string	Yes if "latitude" and "longitude" is not set	Search location query

Action `requestLocationPush`

No fields, requestLocationPush is an empty object

calendarAction

`calendarAction` action category

Action	Description
createCalendarEvent	Creates an event in the user's calendar

Action `createCalendarEvent`

Field	Type	Mandatory	Description
startTime	string	Yes	Start of event
endTime	string	Yes	End of event
title	string	Yes	Title of event
description	string	No	Description of event
fallbackUrl	string	No	URL to open if it is not possible to create a calendar event, e.g. a link to the web version of Google calendar

composeAction

`composeAction` action category

Action	Description
composeTextMessage	Opens a window for creating a new text message to the specified number
composeRecordingMessage	Opens a window for creating a new video or audio message to a specified number

Action `composeTextMessage`

Field	Type	Mandatory	Description
phoneNumber	string	Yes	The number to which we write the message
text	string	Yes	Message text to be entered into the editor

Action `composeRecordingMessage`

Field	Type	Mandatory	Description
phoneNumber	string	Yes	The number to which you want to record the message
type	string	Yes	Message Type. Possible values are AUDIO or VIDEO

deviceAction

`deviceAction` action category

Action	Description
requestDeviceSpecifics	Requests the user to share the characteristics of the current device (device model, operating system version, messaging client identifier and version, and remaining battery charge in minutes)

Action `requestDeviceSpecifics`

No fields, requestDeviceSpecifics is an empty object

settingsAction

`settingsAction` action category

Action	Description
disableAnonymization	Requests the user to exit anonymization mode and reveal their mobile number
enableDisplayedNotifications	Requests the user to enable read notifications

Action `disableAnonymization`

No fields, disableAnonymization is an empty object

Action `enableDisplayedNotifications`

No fields, enableDisplayedNotifications is an empty object

RichcardMessage Object

Field	Type	Mandatory	Description
layout	Layout Object	Yes	In this section markup and formatting options
content	Content Object	Yes	This section contains the contents of the card itself

Layout Object

Field	Type	Mandatory	Description
cardOrientation	string	Yes	Card orientation: VERTICAL or HORIZONTAL
imageAlignment	string	Yes if "cardOrientation" is "HORIZONTAL"	The position of the media on the horizontal card: LEFT or RIGHT
titleFontStyle	string array	No	Header font style: array of italics, bold, underline
descriptionFontStyle	string array	No	Header font style: array of italics, bold, underline
cardStyle	string	No	Link to CSS describing the card style

Content Object

Field	Type	Mandatory	Description
media	Media Object	No	In this subsection, media content settings
title	string	No	Card header
description	string	No	Card description/text
suggestions	Suggested Chip List	No	A list of suggested responses and/or actions that are drawn inside the card. Maximum of 4 pieces.

Media Object

Field	Type	Mandatory	Description
mediaUrl	string	Yes	URL of the media file
mediaContentType	string	Yes	MIME type of the media file
mediaFileSize	string	Yes	Media file size in bytes
thumbnailUrl	string	No	URL of the thumbnail for the media file
thumbnailContentType	string array	Yes if "thumbnailUrl" is set	MIME thumbnail type for the media file
thumbnailFileSize	integer	Yes if "thumbnailUrl" is set	Media file thumbnail size in bytes
height	integer	Yes	Media height: SHORT_HEIGHT, MEDIUM_HEIGHT or TALL_HEIGHT
contentDescription	integer	No	Text description of media content, shown instead of media if it cannot be displayed

Example

Example text message

{
  "payload": {
    "RCSMessage": {
      "textMessage": "This is simple text"
    }
  }
}

Example rich card message

{
  "payload":{
    "richcardMessage":{
      "message":{
        "generalPurposeCard":{
          "layout":{
            "titleFontStyle":[
              "bold"
            ],
            "cardOrientation":"VERTICAL",
            "descriptionFontStyle":[
              "italic"
            ]
          },
          "content":{
            "media":{
              "height":"SHORT_HEIGHT",
              "mediaUrl":"http://62.67.222.59/files/storage/0c68be49-c851-4892-88f7-77bedb7ac2f0/8492d8805e7dfaf5f9a5a0e7282e21eee2099259d359fbf9e48b69c97c26e6ca/pepsi.png",
              "thumbnailUrl":"http://62.67.222.59/files/storage/7b8d58dc-865b-4b83-beca-020497713d29/76914f3b37963de292af9cca9de408a3e2ccc0ee9fa6f93a682a3dbd482938aa/thumb",
              "mediaFileSize":791264,
              "mediaContentType":"image/png",
              "thumbnailFileSize":4013,
              "thumbnailContentType":"image/png"
            },
            "title":"Cupidatat non proident",
            "description":"Lorem ipsum dolor sit amet",
            "suggestions":[
              {
                "reply":{
                  "displayText":"Eiusmod tempor incididunt"
                }
              },
              {
                "reply":{
                  "displayText":"Excepteur sint"
                }
              }
            ]
          }
        }
      }
    }
  }
}

Viber payload

Field	Type	Description
"text"	string	Text message content
"imageUrl"	string	Image
"buttonUrl"	string	The URL the button goes to
"buttonCaption"	string	Button text

Example

{
  "payload": {
    "text": "Lorem ipsum. Dolor sit amet, consectetur adipiscing elit. More info: https://www.oursite.com",
    "imageUrl": "https://png.pngtree.com/element_our/20190529/ourmid/pngtree-smiling-illustration-cartoon-expression-image_1200038.jpg",
    "buttonUrl": "https://www.google.com/",
    "buttonCaption": "ALERT"
  }
}

WhatsApp payload

Field	Type	Mandatory	Description
type	string	Yes	Message type. Possible values: template, text, image, video, audio, document, location, contact, sticker, interactive.
template	Object Template	Yes*	Template message content
text	Object Text	Yes*	Text message content
image	Object Media	Yes*	Message content with an image
video	Object Media	Yes*	Message content with a video
audio	Object Media	Yes*	Message content with an audio
document	Object Media	Yes*	Message content with a PDF document
location	Object Location	Yes*	Message content with a location
contacts	Array of objects Contact	Yes*	Message content with contacts
sticker	Object Media	Yes*	Message content with a sticker
interactive	Object Interactive	Yes*	Interactive message content
recipient_type	string	No	The type of recipient the message is being sent to. Supported value: individual
preview_url	boolean	No	Whether to show a link preview if there is a link in the message text. Applies to text messages only. By default - false.

*- one of the fields, depending on the message type.

Payload objects

WhatsApp template

Type `Template`

Field	Type	Mandatory	Description
namespace	string	Yes	Namespace associated with WhatsApp Business Account to which the sender's name is assigned
name	string	Yes	Template name (pass-through identifier)
language	Object Language	Yes	Text message content
components	Array of objects Component	No	Template components. They are used to pass variables to be inserted into the corresponding template component. If no variables are provided in the component, the component is not specified. If there are no components with variables in the template, the whole field is not specified.

Field `language`

Field	Type	Mandatory	Description
policy	string	Yes	Language Policy. The only possible value - deterministic.
code	string	Yes	Template language. See here for allowed values.

Field `component`

Field	Type	Mandatory	Description
type	string	Yes	The template component for which the variables are passed. Possible values: header, body, footer, button. Variables for text templates must be passed in the body component.
subtype	string	No	Component subtype. Mandatory for a button type component and applicable only to it. Possible values: quick_reply, url.
index	integer	No	Button index number in the template, starting from 0. Mandatory for the only button type component to which it is applicable.
parameters	Array of objects Parameter	No	Array of variables to be inserted into the corresponding template component. Variables are listed in the same order in which they are numbered in the component.

Type `Parameter`

Field	Type	Mandatory	Description
type	string	Yes	Variable type to be inserted. Possible values: text, currency, date_time, image, document, video, payload.
text	string	Yes*	Plain text to be inserted. For buttons of url type - a variable part of the URL. It can be in any component, except for quick_reply buttons. The only parameter type that can be in url type buttons.
currency	Object Currency	Yes*	Localizable variable for values in currency to be inserted. It can be in any component except buttons.
date_time	Object DateTime	Yes*	Localizable variable for datetime values to be inserted. It can be in any component except buttons.
image	Object Media	Yes*	Image variable. It can be in the header component only.
document	Object Media	Yes*	PDF document variable. It can be in the header component only.
video	Object Media	Yes*	Video variable. It can be in the header component only.
payload	string	Yes*	Payload, which is sent back together with the notification when the quick_reply button was tapped. It can only be in quick_reply type buttons . The only parameter type that can be in quick_reply type buttons.

*- one of the fields, depending on the variable type.

Type `Currency`

Field	Type	Mandatory	Description
amount_1000	integer	Yes	Currency amount multiplied by 1000
code	string	Yes	Three-letter currency code
fallback_value	string	Yes	The currency amount as plain text in case the data cannot be presented in the recipient`s locale

Type `DateTime`

Field	Type	Mandatory	Description
year	integer	Yes*	Year
month	integer	Yes*	Month
day_of_month	integer	Yes*	Day of the month
hour	integer	Yes*	Hour
minute	integer	Yes*	Minute
day_of_week	integer	Yes	Day of the week (1-7)
fallback_value	string	Yes	Date as a plain text, in case the data cannot be presented in the recipient's locale
timestamp	integer	No*	Unix timestamp (number of seconds from 00:00 January 1, 1970)

*- either timestamp or all other date fields can be specified.

Text

Type `text`

Field	Type	Mandatory	Description
body	string	Yes	Message text

Location

Type `Location`

Field	Type	Mandatory	Description
latitude	string	Yes	Latitude
longitude	string	Yes	Longitude
name	string	No	Location name
address	string	No	Address

Media

Type `Media`

Field	Type	Mandatory	Description
link	string	Yes	URL of the file to be uploaded
caption	string	No	File description. Not applicable to audio and sticker types.
filename	string	No	PDF file name. It applies to document type only.

Examples

Template example

{
  "contact": "48501923322",
  "webhook": "https://example.com/webhooks/status",
  "isOtp": false,
  "channel": 4,
  "senderId": "104594471418892442531",
  "payload": {
    "recipient_type": "individual",
    "type": "template",
    "template": {
      "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
      "name": "movie_ticket_update",
      "language": {
        "code": "en",
        "policy": "deterministic"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": {
                "id": "your-image-id"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Star Rangers"
            },
            {
              "type": "date_time",
              "date_time" : {
                "fallback_value": "May 1st, 2019 8:45pm",
                "day_of_month": 20,
                "year": 2019,
                "month": 9,
                "hour": 20,
                "minute": 45
              }
            },
            {
              "type": "text",
              "text": "Carnival, Sangam"
            },
            {
              "type": "text",
              "text": "Silver"
            },
            {
              "type": "text",
              "text": "F6, F7, F8"
            }
          ]
        }
      ]
    }
  }
}

Example plain text

{
  "payload": {
    "preview_url": true,
    "recipient_type": "individual",
    "type": "text",
    "text": {
      "body": "OMNI API whatsapp omni message. Wait for 10 secs."
    }
  }
}

Example interactive message. Image with button

{
  "recipient_type": "individual",
  "to": "905063565285",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "image": {
        "link": "https://your-domain.com/files/storage/dev2/9929b7f0-cdc4-4b33-aea3-4c552208d0db/d83626585b711b1992eac2c623011ba7383ccc6dd5c455a3338fbf476f92100d/4b6a3366-97b5-4e50-b1b4-c8d63dafbf19.jpg"
      }
    },
    "body": {
      "text": "This is s cat!"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "title": "Are you agree?",
            "id": "ID: 0"
          }
        }
      ]
    }
  }
}

Example image file

{
  "to": "905063565285",
  "type": "image",
  "image": {
    "link": "https://your-domain.com/files/storage/dev2/0d75dda3-2942-45d6-bbfd-02f37496c6e7/92c2962981b9a8ab6194a5bcc1bcbecb6040a32d0e2d72d4e5c29b67dc1065ce/download%282%29.png"
  }
}

Example interactive message. Send location

{
  "recipient_type": "individual",
  "to": "905063565285",
  "type": "location",
  "location": {
    "longitude": 30.31,
    "latitude": 59.94,
    "name": "https://www.hermitagemuseum.org/wps/portal/hermitage/",
    "address": "Saint-Petersburg"
  }
}

Example interactive. List message

{
  "recipient_type": "individual",
  "to": "905063565285",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "This is question!"
    },
    "body": {
      "text": "Are you ready?"
    },
    "footer": {
      "text": ""
    },
    "action": {
      "button": "Header",
      "sections": [
        {
          "title": "Answer",
          "rows": [
            {
              "title": "Yes",
              "id": "5",
              "description": ""
            },
            {
              "title": "No",
              "id": "6",
              "description": ""
            }
          ]
        }
      ]
    }
  }
}

Email payload

Field	Type	Mandatory	Description
subject	string	No	Default subject of email
subtitle	string	No	Subtitle of email. Right now, this parameter does not affect anything.
body.rendered	Array of objects Rendered	Yes	List of email bodies

Rendered Object

Field	Type	Mandatory	Description
contentType	string	Yes	Type of email content. Supported values: html, mjml, plainText
content	string	Yes	Actual content of the email

Examples

Example with text

{
  "contact": "alex@example.com",
  "webhook": "https://webhook.site/8882947e-cef3-48ea-be43-79f4b8b4a350",
  "isOtp": false,
  "channel": 7,
  "senderId": "email_fromAlex",
  "payload": {
    "subject": "subject",
    "subtitle": "subtitle",
    "body": {
      "rendered": [
        {
          "contentType": "html",
          "content": "<html>Hello my friend.</html>"
        }
      ]
    }
  }
}

Example with image

{
  "contact": "askirilloff@gmail.com",
  "webhook": "https://webhook.site/d6afd08a-8064-4b59-9a45-2719fecd8cd3",
  "isOtp": false,
  "channel": 7,
  "senderId": "email_fromAlex",
  "payload": {
    "subject": "Email subject",
    "subtitle": "Email subtitle",
    "body": {
      "rendered": [
        {
          "contentType": "html",
          "content": "<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office"><head><title></title><!--[if !mso]><!--><meta http-equiv="X-UA-Compatible" content="IE=edge"><!--<![endif]--><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><style type="text/css">#outlook a { padding:0; }n body { margin:0;padding:0;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%; }n table, td { border-collapse:collapse;mso-table-lspace:0pt;mso-table-rspace:0pt; }n img { border:0;height:auto;line-height:100%; outline:none;text-decoration:none;-ms-interpolation-mode:bicubic; }n p { display:block;margin:13px 0; }</style><!--[if mso]>n <noscript>n <xml>n <o:OfficeDocumentSettings>n <o:AllowPNG/>n <o:PixelsPerInch>96</o:PixelsPerInch>n </o:OfficeDocumentSettings>n </xml>n </noscript>n <![endif]--><!--[if lte mso 11]>n <style type="text/css">n .mj-outlook-group-fix { width:100% !important; }n </style>n <![endif]--><!--[if !mso]><!--><link href="https://fonts.googleapis.com/css?family=Droid+Sans:300,400,500,700" rel="stylesheet" type="text/css"><link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700" rel="stylesheet" type="text/css"><link href="https://fonts.googleapis.com/css?family=Ubuntu:300,400,500,700" rel="stylesheet" type="text/css"><style type="text/css">@import url(https://fonts.googleapis.com/css?family=Droid+Sans:300,400,500,700);n@import url(https://fonts.googleapis.com/css?family=Roboto:300,400,500,700);n@import url(https://fonts.googleapis.com/css?family=Ubuntu:300,400,500,700);</style><!--<![endif]--><style type="text/css">@media only screen and (min-width:480px) {n .mj-column-per-100 { width:100% !important; max-width: 100%; }n }</style><style media="screen and (min-width:480px)">.moz-text-html .mj-column-per-100 { width:100% !important; max-width: 100%; }</style><style type="text/css">@media only screen and (max-width:479px) {n table.mj-full-width-mobile { width: 100% !important; }n td.mj-full-width-mobile { width: auto !important; }n }</style><style type="text/css"></style></head><body style="word-spacing:normal;background-color:#efeeea;"><div style="background-color:#efeeea;"><!--[if mso | IE]><table align="center" border="0" cellpadding="0" cellspacing="0" class="" role="presentation" style="width:600px;" width="600" ><tr><td style="line-height:0px;font-size:0px;mso-line-height-rule:exactly;"><![endif]--><div style="margin:0px auto;max-width:600px;"><table align="center" border="0" cellpadding="0" cellspacing="0" role="presentation" style="width:100%;"><tbody><tr><td style="direction:ltr;font-size:0px;padding:0px;text-align:left;"><!--[if mso | IE]><table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr><td class="" style="vertical-align:top;width:600px;" ><![endif]--><div class="mj-column-per-100 mj-outlook-group-fix" style="font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;"><table border="0" cellpadding="0" cellspacing="0" role="presentation" style="vertical-align:top;" width="100%"><tbody><tr><td align="center" style="font-size:0px;padding:0px 0px 0px 0px;word-break:break-word;"><table border="0" cellpadding="0" cellspacing="0" role="presentation" style="border-collapse:collapse;border-spacing:0px;"><tbody><tr><td style="width:600px;"><img src="https://your-domain.com/files/storage/dev2/6fb7101d-1326-4b37-a374-35a2f9a9054f/5f9038801a35eea1894c5cc47433c547220e6c294d5826c8841a7595ea88d0b5/example15.jpg" style="border:0;display:block;outline:none;text-decoration:none;height:auto;width:100%;font-size:13px;" width="600" height="auto"></td></tr></tbody></table></td></tr></tbody></table></div><!--[if mso | IE]></td></tr></table><![endif]--></td></tr></tbody></table></div><!--[if mso | IE]></td></tr></table><table align="center" border="0" cellpadding="0" cellspacing="0" class="" role="presentation" style="width:600px;" width="600" ><tr><td style="line-height:0px;font-size:0px;mso-line-height-rule:exactly;"><![endif]--><div style="margin:0px auto;max-width:600px;"><table align="center" border="0" cellpadding="0" cellspacing="0" role="presentation" style="width:100%;"><tbody><tr><td style="direction:ltr;font-size:0px;padding:0px;text-align:left;"><!--[if mso | IE]><table role="presentation" border="0" cellpadding="0" cellspacing="0"><tr><td class="" style="vertical-align:top;width:600px;" ><![endif]--><div class="mj-column-per-100 mj-outlook-group-fix" style="font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;"><table border="0" cellpadding="0" cellspacing="0" role="presentation" style="vertical-align:top;" width="100%"><tbody><tr><td align="left" style="font-size:0px;padding:10px 25px 10px 25px;word-break:break-word;"><div style="font-family:-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans','Helvetica Neue', sans-serif;font-size:14px;font-weight:400;line-height:1.7;text-align:left;color:#000000;">Make it easy for everyone to compose emails!</div></td></tr></tbody></table></div><!--[if mso | IE]></td></tr></table><![endif]--></td></tr></tbody></table></div><!--[if mso | IE]></td></tr></table><![endif]--></div></body></html>"
        }
      ]
    }
  }
}

Telegram Gateway payload

Field	Type	Mandatory	Description
code	integer	No*	This is the code to be sent (4-8 digits). Mandatory parameter unless the code_length parameter is specified. If the parameter is specified, the code_length parameter is ignored.
code_length	integer	No*	This is the length of the send code to be generated on the TG side, supported values are from 4 to 8. Mandatory parameter if no code parameter is specified.
ttl	integer	No	Verification code message lifetime in seconds, supported values 30-3600. Optional parameter.

*- one of them should be used.

Example

{
  "channel": 8,
  "contact": "905518709790",
  "payload": {
    "code_length": 5,
    "ttl": 300
  },
  "senderId": "transit",
  "webhook": "https://webhook.site/852af452-1f48-4c90-8aa5-bac4cf77e386",
  "isOtp": true
}

Push payload

Example

Field	Type	Mandatory	Description
notification	Object	Yes	Object for push message params
title	string	No*	Push message title.
body	string	No*	Push message body.
image	string	No*	Push message image.

*- one of them should be used.

{
  "contact": "cpRLb7mHSWa8TVaebL5xe7:APA91bGSly-XOYRzXu2DQZcxOR2Y4eL_Glx61-f9ngx7MhhsgkjGi_2Zv8AzKyJgYlWQLg7lkectMPpNttcBeW6kOyKQS4H0hRyrZLMXzC7dSh_cnZb4jAs",
  "channel": 10,
  "senderId": "push_dev",
  "payload": {
    "notification": {
      "title": "some title",
      "body": "some body",
      "image": "https://your-domain.com/files/storage/e3890761-20f2-426d-81fc-197e71e0051f/6ec1f471f0d9ca4c616a4c923f4cc1fa144103e122f76e0ff42d6b6e2371b08c/kosta-rika-2.jpg"
    }
  }
}

TTS payload

Example

Field	Type	Mandatory	Description
text	string	Yes	TTS message text.
language	string	Yes	TTS message language.
repeat_count	integer	No	TTS message number of repetitions.

{
  "contact": "995568739067",
  "channel": 11,
  "senderId": "905063565285",
  "payload": {
    "text": "31245",
    "language": "eu",
    "repeat_count": 1
  }
}

Example send fallback of messages

{
  "contact": "48501923322",
  "webhook": "https://example.com/webhooks/status",
  "isOtp": true,
  "cooldown": 86400,
  "messages": [
    {
      "channel": 4,
      "contact": "48501923322",
      "senderId": "14157386170",
      "successOn": "delivered",
      "timeout": 14400,
      "payload": {
        "preview_url": true,
        "recipient_type": "individual",
        "type": "text",
        "text": {
          "body": "OMNI API whatsapp omni message. Wait for 10 secs."
        }
      }
    },
    {
      "channel": 2,
      "contact": "123456789",
      "senderId": "104594471418892442531",
      "successOn": "seen",
      "timeout": 259200,
      "payload": {
        "textMessage": "Test OMNI API rcs_google omni message. Wait for 10 secs."
      }
    }
  ]
}

For omni-fallback timeout for transition to the next cascade channel is not set. If we receive the status that the subscriber is not available/does not exist/rejected, fallback to the next cascade channel is immediately performed.

Content templates

This section shows an example of sending templates.

Template Object

The template parameter is obligatory if it is required to send a message via template.

Field	Type	Mandatory	Description
id	integer	Yes	Template ID which may be found in the interface of Assets->Templates https:///media/content-templates
params	Object Parameters	Yes	The template attributes should be placed here. In case the template does not contain any variables you need to send empty array inside params parameter

Example

{
  "contact": "askirilloff@gmail.com",
  "webhook": "https://webhook.site/c9e9bef8-ca37-4090-a39b-58f0eca70af4",
  "isOtp": false,
  "channel": 7,
  "senderId": "email_fromAlex",
  "template": {
    "id": 624,
    "params": {
      "attribute.phoneNumber": "905518709790",
      "attribute.name": "Alex (turk)"
    }
  }
}

Response body

Field	Type	Mandatory	Description
error	boolean	Yes	The checkbox indicating, that the request was completed with an error. If the request is successful it will be false.
data	Object Data	Yes	Object with the request result details

Type `Data`

Field	Type	Mandatory	Description
channel	integer	Yes	Message channel. 4 is always used for WhatsApp.
transactionId	string	Yes	Transaction ID
messageId	string	No	Message ID. This is the ID to which further sending, delivery and read notifications will be sent.

Example

Response example

HTTP/1.1 202 Accepted
Date: Thu, 07 Oct 2021 10:07:53 GMT
Content-Type: application/json
Content-Length: 142
Vary: Origin
Access-Control-Allow-Origin: *

{
    "error": false,
    "data": {
        "channel": 4,
        "transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
        "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
    }
}

Webhook payload

Webhook payload for message status

Example

{
  "event": "messageStatus",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "channel": 2,
    "senderId": "emulator",
    "status": "delivered",
    "timestamp": "2023-09-08T15:30:00Z",
    "contact": "905324546496",
    "cost": "1.00"
  }
}

Type `WebhookPayloadForMessageStatus`

Filed	Type	Mandatory	Description
event	string	Yes	Event type (can be `messageStatus`)
message	StatusPayload	Yes	Payload
reason	Reason	No	Error reason

Type `StatusPayload`

Filed	Type	Mandatory	Description
messageId	string	Yes	Unique identifier of the message
omniTransactionId	string	No	Omni-Transaction identifier (may be empty)
channel	integer	Yes	Type of channel through which the message was sent
senderId	string	Yes	Unique identifier of the sender
status	MessageStatus	Yes	Message status
timestamp	string	Yes	Timestamp of the message (RFC3339)
contact	string	Yes	Receiver contact
cost	float	No	Message cost (may be empty)

Type `Reason`

Filed	Type	Mandatory	Description
code	integer	No	Error status code
text	string	Yes	Error description

Enum `MessageStatus` (string)

Value	Description
"sent"	The message has been successfully sent
"failed"	Failed to send a message
"delivered"	The message has been successfully delivered
"undeliverable"	Failed to deliver message
"displayed"	The message has been successfully viewed
"unknown"	Unknown or unsupported status

Webhook payload for MO message

Example

{
  "event": "message",
  "message": {
    "messageId": "4aab1947-7a34-4efe-8c51-e9c8f9b1412b",
    "omniTransactionId": "57f29fdd-1127-45b3-a7d5-260a831a4662",
    "timestamp": "2023-09-08T15:30:00Z",
    "channel": "SMS",
    "senderId": "2813380676",
    "contact": "8172958708",
    "payload": {
      "text": "test SMS"
    }
  }
}

Type `WebhookPayloadForMO`

Field	Type	Mandatory	Description
event	string	Yes	Event type (can be `message`)
message	MessagePayload	Yes	Payload

Type `MessagePayload`

Field	Type	Description
messageId	string	Unique identifier of the message
omniTransactionId	string	Omni-Transaction identifier (may be empty)
timestamp	string	Timestamp of the message (RFC3339)
channel	ChannelType	Channel type
senderId	string	Sender ID
contact	string	Phone number
payload	Object	Message payload (channel-specific payload)
status	string	Message status (may be empty)
webhook	string	Message webhook (may be empty)

Constants `ChannelType` (string)

[
  "UNSET",
  "SMS",
  "RCS",
  "Viber",
  "WhatsApp"
]

This section provides an overview of channels, message types, and shows examples of messages.

WhatsApp channel

There are the following message types:

Template messages:
- Plain text,
- With media,
Free-form text messages:
- Plain Text,
- Messages with media:
  - Image,
  - Audio,
  - Video,
  - File (document),
- Location,
- Contact list.

About template messages

Documentation - Message Templates - WhatsApp Business API

Unlike free-form text messages, the content of template messages is defined in a corresponding template, the ability to modify it is limited and is only allowed for personalization purposes. A template message is a statically defined content (with the only ability to insert variables into certain fields), which is registered on WhatsApp and must go through an approval process by WhatsApp. A template message can be sent only when its template is approved. Message templates must fit into one of the following categories (scopes):

Account Update: Let customers know about updates or changes to their accounts.
Alert Update: Send important updates or news to customers.
Appointment Update: Send confirmations, reminders, or other updates to customers about their appointments.
Auto-Reply: Send auto-replies to customers when your business isn't online or available to respond right away.
Issue Resolution: Respond to questions, concerns, or feedback from customers about your business.
Payment Update: Send a message to customers about their payment.
Personal Finance Update: Send a message to customers about their personal finances.
Reservation Update: Send confirmations, reminders, or other updates to customers about their reservations.
Shipping Update: Send shipping updates to customers about their orders.
Ticket Update: Send ticketing information or updates to customers.
Transportation Update: Send transportation information or updates to customers.

Variables to personalize the message are inserted into certain template fields. In this case, when sending a template message, only the template identifier (name) and the array of variables to be inserted are specified. Variables to be inserted are usually used as a plain text, however 2 types of so-called localizable variables are additionally supported:

Currency (currency amount),
Date and time.

Localizable variables are set in a unified format when they are sent to Whatsapp, but when the message is displayed on the device, they are automatically converted to the format that the recipient is used to, depending on their language and location settings. The default value for localizable variables can also be set as a plain text, which will be displayed in cases where the user's locale cannot be determined or the variable value cannot be converted to the desired locale. Variables to be substituted in the template must be in the same order in which they are marked in the template.

Text message template

Documentation - Message Templates - WhatsApp Business API

The text message template is as follows

Your {{1}} code: {{2}}. Valid for {{3}} minutes

where {{1}}, {{2}} и {{3}} - variable substitution indexes (i.e. {{1}} will be replaced by the first variable specified, {{2}} will be replaced by the second, and so on).

Example

POST /api/v1/messages HTTP/1.1
Host: {{URL}}
X-API-Key: 660046f99d249708e83e1b4bd1f02dc7167b7f6da1d81d73b865de40303cc81e
Content-Type: application/json
Content-Length: 1016

{
    "contact": "905063565285",
    "channel": 4,
    "senderId": "1234567890",
    "payload": {
        "type": "template",
        "template": {
            "namespace": "9b6b4fcb_da19_4a26_8fe8_78074a91b584",
            "name": "verification_code",
            "language": {
                "policy": "deterministic",
                "code": "en_US"
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "Booking.com"
                        },
                        {
                            "type": "text",
                            "text": "56821"
                        },
                        {
                            "type": "text",
                            "text": "3"
                        }
                    ]
                }
            ]
        }
    }
}

Media message template with buttons

Documentation - Media Message Templates - WhatsApp Business API

Media message templates allow you to send complex structure messages.

Such messages can have:

Header (optional) - can be text, image, video, PDF document or location. In case the header is a text, you can use variables in it. In other cases, the variable is the media file itself to use as the header. The content types available for use as a header depend on the category (scope) of the template,
Message body (mandatory) - text in which you can use variables, as in a plain text message,
Signature (optional) - short text displayed in small print at the bottom of the message. Variables can also be used in the signature,
Quick reply and action buttons (optional) - buttons for sending quick replies or performing actions (dialing a number or following a URL). Variables can be used in the buttons properties (for example, substitute a unique part of the URL). The button types and the maximum number of buttons allowed to be used in a template depend on the category (scope) of the template.

For each template section (header / body / footer / each specific button) arrays of variables to be inserted are specified separately, and variable indexes are maintained independently. When sending a message, only the variables and which section they belong to are specified - in case a section does not contain them (i.e., if the content of the section is completely static), it should not be mentioned when sending

Example

POST /api/v1/messages HTTP/1.1
Host: {{URL}}
X-API-Key: 660046f99d249708e83e1b4bd1f02dc7167b7f6da1d81d73b865de40303cc81e
Content-Type: application/json
Content-Length: 2491

{
    "contact": "905063565285",
    "channel": 4,
    "senderId": "1234567890",
    "payload": {
        "recipient_type": "individual",
        "type": "template",
        "template": {
            "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
            "name": "upcoming_trip_reminder",
            "language": {
                "code": "en",
                "policy": "deterministic"
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "12/26"
                        }
                    ]
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "*Ski Trip*"
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "29th July 2019, 8:00am",
                                "day_of_month": "29",
                                "year": "2019",
                                "month": "7",
                                "hour": "8",
                                "minute": "00"
                            }
                        },
                        {
                            "type": "text",
                            "text": "*Squaw Valley Ski Resort, Tahoe*"
                        }
                    ]
                },
                {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": 0,
                    "parameters": [
                        {
                            "type": "payload",
                            "payload": "Yes-Button-Payload"
                        }
                    ]
                },
                {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": 1,
                    "parameters": [
                        {
                            "type": "payload",
                            "payload": "No-Button-Payload"
                        }
                    ]
                }
            ]
        }
    }
}

Open API Playground Download spec

balance

GET /balance Get balances for own company

channels

GET /channels Get all channels

edrs

GET /edrs Get edrs

messages

POST /messages Send message POST /messages/revoke Revoke verification message POST /messages/verification Check verification status

omnimessages

POST /omnimessages Send omnimessages

senders

GET /senders Get all senders

template

GET /templates Get content templates list GET /wa_templates Get content templates list

Routeon OMNIAPI

Authorization

Using API key

Response

Webhook

Request body

Payload

Sms payload

Example

Rcs payload

RCSMessage Object

RCSMessage Objects

FileMessage Object

AudioMessage Object

GeolocationPushMessage Object

Suggested Chip List Item

Action categories

urlAction action category

Action openUrl

dialerAction action category

Action dialPhoneNumber

Action dialEnrichedCall

Action dialVideoCall

mapAction action category

Action showLocation

Location Object

Action requestLocationPush

calendarAction action category

Action createCalendarEvent

composeAction action category

Action composeTextMessage

Action composeRecordingMessage

deviceAction action category

Action requestDeviceSpecifics

settingsAction action category

Action disableAnonymization

Action enableDisplayedNotifications

RichcardMessage Object

Layout Object

Content Object

Media Object

Example

Viber payload

Example

WhatsApp payload

Payload objects

Type Template

Field language

Field component

Type Parameter

Type Currency

Type DateTime

Type text

Type Location

Type Media

Examples

Email payload

Rendered Object

Examples

Telegram Gateway payload

Example

Example

Example

Content templates

Template Object

Response body

Type Data

Example

Webhook payload

Webhook payload for message status

Example

Type WebhookPayloadForMessageStatus

Type StatusPayload

Type Reason

Enum MessageStatus (string)

Webhook payload for MO message

Example

Type WebhookPayloadForMO

Type MessagePayload

Constants ChannelType (string)

`urlAction` action category

Action `openUrl`

`dialerAction` action category

Action `dialPhoneNumber`

Action `dialEnrichedCall`

Action `dialVideoCall`

`mapAction` action category

Action `showLocation`

Action `requestLocationPush`

`calendarAction` action category

Action `createCalendarEvent`

`composeAction` action category

Action `composeTextMessage`

Action `composeRecordingMessage`

`deviceAction` action category

Action `requestDeviceSpecifics`

`settingsAction` action category

Action `disableAnonymization`

Action `enableDisplayedNotifications`

Type `Template`

Field `language`

Field `component`

Type `Parameter`

Type `Currency`

Type `DateTime`

Type `text`

Type `Location`

Type `Media`

Type `Data`

Type `WebhookPayloadForMessageStatus`

Type `StatusPayload`

Type `Reason`

Enum `MessageStatus` (string)

Type `WebhookPayloadForMO`

Type `MessagePayload`

Constants `ChannelType` (string)