Omnichannel API

All endpoints require HTTP basic authorization header with Messente API username and password.

You can find the API username and password under your Account API Settings.

Sends an Omnimessage

POST https://api.messente.com/v1/omnimessage

Request Body

Body is required. Omnimessage to be sent
Property Type Info
torequired string

Phone number in e.164 format
messagesrequired array

An array of messages

SMS message content

Property Type Info
textrequired string

Text content of the SMS

Example: Hello world!
sender string

Phone number or alphanumeric sender name
validity integer

After how many minutes this channel is considered as failed and the next channel is attempted. Only one of "ttl" and "validity" can be used.

Example: 360
ttl integer

After how many seconds this channel is considered as failed and the next channel is attempted. Only one of "ttl" and "validity" can be used.

Example: 21600
autoconvert string

Defines how non-GSM characters will be treated:

  • "on" Use replacement settings from the account's API Auto Replace settings page (default)
  • "full" All non GSM 03.38 characters will be replaced with suitable alternatives
  • "off" Message content is not modified in any way
Possible values:
  • full
  • on
  • off
udh string

hex-encoded string containing SMS UDH
channelrequired string

The channel used to deliver the message

Possible values:
  • sms
Default: sms

Viber message content

Property Type Info
sender string

Phone number or alphanumeric sender name
validity integer

After how many minutes this channel is considered as failed and the next channel is attempted. Only one of "ttl" and "validity" can be used.

Example: 360
ttl integer

After how many seconds this channel is considered as failed and the next channel is attempted. Only one of "ttl" and "validity" can be used.

Example: 21600
text string

Plaintext content for Viber
image_url string

URL for the embedded image

Valid combinations:

1) image_url,

2) text, image_url, button_url, button_text
button_url string

URL of the button, must be specified along with ''text'', ''button_text'' and ''image_url'' (optional). For specifics when used with video, refer to the video section.
button_text string

Must be specified along with ''text'', ''button_url'', ''button_text'', ''image_url'' (optional). For specifics when used with video, refer to the video section.
channelrequired string

The channel used to deliver the message

Possible values:
  • viber
Default: viber
video object

Viber video object.

Valid combinations:
  • video
  • video + text
  • video + text + button_text (button redirects to video)
  • video + text + button_text + button_url (button redirects to specified URL)

Property Type Info
urlrequired string

URL pointing to the video resource.
thumbnailrequired string

URL pointing to the video thumbnail resource.
file_sizerequired integer

Size of the video file in bytes. Cannot be larger than 200MB.
durationrequired integer

Duration of the video in seconds. Cannot be longer than 600 seconds.

WhatsApp message content

Property Type Info
sender string

Phone number or alphanumeric sender name
validity integer

After how many minutes this channel is considered as failed and the next channel is attempted

Example: 360
ttl integer

After how many seconds this channel is considered as failed and the next channel is attempted. Only one of "ttl" and "validity" can be used.

Example: 21600
template object

WhatsApp template object used for customizing the message. The template must be approved by WhatsApp before using.
channelrequired string

The channel used to deliver the message

Possible values:
  • whatsapp
Default: whatsapp
dlr_url string

URL where the delivery report will be sent

Format: url
text_store string

Whether to store message content as is (plaintext), as a hashed value (sha256) or not at all (nostore)

Possible values:
  • nostore
  • plaintext
  • sha256
time_to_send string

Optional parameter for sending messages at some specific time in the future. Time must be specified in the ISO-8601 format. If no timezone is specified, then the timezone is assumed to be UTC

Examples:

  • Time specified with timezone: 2018-06-22T09:05:07+00:00 Time specified in UTC: 2018-06-22T09:05:07Z
  • Time specified without timezone: 2018-06-22T09:05 (equivalent to 2018-06-22T09:05+00:00)
Format: date-time
priority string

Set the priority of the message. Messages are processed starting with in highest priority queue first and lowest priority queue last. This for example allows to prioritize OTP messages over marketing traffic.

Possible values:
  • low
  • regular
  • high

Template object

WhatsApp template object. Required for WhatsApp messages
Property Type Info
namerequired string

Name of the template.
languagerequired object

Whatsapp template language

Property Type Info
coderequired string

Language code
policy string

Language policy
components array

List of template component objects.

Component object

WhatsApp component object used in the templates
Property Type Info
typerequired string

Type of the component.
sub_type string

Sub-type of the component.
index integer

index used to position buttons.
parameters array

List of parameter objects.

Parameter object

WhatsApp parameter object used in template components
Property Type Info
typerequired string

Type of the parameter.
text string

A text.
currency object

Whatsapp currency object.

Property Type Info
fallback_valuerequired string

Default text if localization fails.
coderequired string

Currency code as defined in ISO 4217.
amount_1000required string

Amount multiplied by 1000.
date_time object

Whatsapp datetime object.

Property Type Info
fallback_valuerequired string

Default text.
image object

Whatsapp media object.

Property Type Info
id string

The media object ID. Do not use this field when message type is set to text.
link string

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message type is set to text.

caption string

Media asset caption. Do not use with audio or sticker media.
filename string

Describes the filename for the specific document. Use only with document media.
document object

Whatsapp media object.

Property Type Info
id string

The media object ID. Do not use this field when message type is set to text.
link string

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message type is set to text.

caption string

Media asset caption. Do not use with audio or sticker media.
filename string

Describes the filename for the specific document. Use only with document media.
video object

Whatsapp media object.

Property Type Info
id string

The media object ID. Do not use this field when message type is set to text.
link string

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message type is set to text.

caption string

Media asset caption. Do not use with audio or sticker media.
filename string

Describes the filename for the specific document. Use only with document media.

Successful Response

HTTP 201 - Omnimessage success response
Property Type Info
messagesrequired array

List of messages that compose the omnimessage

A message part of an omnimessage

Property Type Info
message_idrequired string

Unique identifier for the message

Format: UUID
channelrequired string

Defines the delivery channel

Possible values:
  • sms
  • viber
  • whatsapp
senderrequired string

Sender that was used for the message
torequired string

Phone number in e.164 format
omnimessage_idrequired string

Unique identifier for the omnimessage

Format: UUID

Error Responses

HTTP 400 - Invalid input
Property Type Info
errorsrequired array

An array of errors

A container for Omnichannel API error

Property Type Info
titlerequired string

Textual value which corresponds to an error code

Possible values:
  • Not found
  • Forbidden
  • Unauthorized
  • Invalid data
  • Internal Server Error
  • Missing data
  • Method not allowed
detailrequired string

Free form more detailed description of the error
coderequired string

Matches the following error title. This field is a constant

  • 101 - Not found
  • 102 - Forbidden
  • 103 - Unauthorized
  • 104 - Internal Server Error
  • 105 - Invalid data
  • 106 - Missing data
  • 107 - Method not allowed
sourcerequired string

Describes which field is causing the issue in the payload, null for non 400 status code responses

Retrieves the delivery report for the Omnimessage

GET https://api.messente.com/v1/omnimessage/{omnimessageId}/status

Request Parameters

Name Location Info
omnimessageIdrequired The parameter is part of the URL path
UUID of the omnimessage to for which the delivery report is to be retrieved
Type: string
Format: UUID

Successful Response

HTTP 200 - Delivery report success
Property Type Info
statusesrequired array

Contains the delivery reports for each channel, ordered by send order

A delivery report

Property Type Info
status string

The human-readable equivalent for this field is contained in "error". This value is null if the message is still being processed

Possible values:
  • ACK
  • DELIVRD
  • UNDELIV
  • FAILED
  • UNKNOWN
  • ACCEPTD
  • REJECTD
  • DELETED
  • EXPIRED
  • NACK
  • SEEN
channel string

Defines the delivery channel

Possible values:
  • sms
  • viber
  • whatsapp
message_id string

Unique identifier for the message

Format: UUID
error string

Human-readable description of what went wrong, null in case of success or if the message has not been processed yet
err integer

Machine-readable error code, 'null' when the message has not been processed yet

Matches the following meanings

  • 0 - No error
  • 1 - Delivery failure
  • 2 - Sending message expired
  • 3 - Invalid number
  • 4 - Error crediting account
  • 5 - Invalid number format
  • 6 - Too many identical messages
  • 7 - Sender name not allowed
  • 8 - Operator blacklisted
  • 9 - Unroutable
  • 10 - Seen
  • 999 - General temporary error
timestamp string

When this status was received by Omnichannel API

Format: date-time
torequired string

Phone number in e.164 format
omnimessage_idrequired string

Unique identifier for the omnimessage

Format: UUID

Error Responses

HTTP 404 - If no such message exists or you do not have access to the particular message
Property Type Info
errorsrequired array

An array of errors

A container for Omnichannel API error

Property Type Info
titlerequired string

Textual value which corresponds to an error code

Possible values:
  • Not found
  • Forbidden
  • Unauthorized
  • Invalid data
  • Internal Server Error
  • Missing data
  • Method not allowed
detailrequired string

Free form more detailed description of the error
coderequired string

Matches the following error title. This field is a constant

  • 101 - Not found
  • 102 - Forbidden
  • 103 - Unauthorized
  • 104 - Internal Server Error
  • 105 - Invalid data
  • 106 - Missing data
  • 107 - Method not allowed
sourcerequired string

Describes which field is causing the issue in the payload, null for non 400 status code responses

Cancels a scheduled Omnimessage

DELETE https://api.messente.com/v1/omnimessage/{omnimessageId}

Request Parameters

Name Location Info
omnimessageIdrequired The parameter is part of the URL path
UUID of the scheduled omnimessage to be cancelled
Type: string
Format: UUID

Successful Response

HTTP 202 - Scheduled omnimessage successfully cancelled
A response body containing empty JSON object

Error Responses

HTTP 404 - If the omnimessage has already been sent or no such message exists
Property Type Info
errorsrequired array

An array of errors

A container for Omnichannel API error

Property Type Info
titlerequired string

Textual value which corresponds to an error code

Possible values:
  • Not found
  • Forbidden
  • Unauthorized
  • Invalid data
  • Internal Server Error
  • Missing data
  • Method not allowed
detailrequired string

Free form more detailed description of the error
coderequired string

Matches the following error title. This field is a constant

  • 101 - Not found
  • 102 - Forbidden
  • 103 - Unauthorized
  • 104 - Internal Server Error
  • 105 - Invalid data
  • 106 - Missing data
  • 107 - Method not allowed
sourcerequired string

Describes which field is causing the issue in the payload, null for non 400 status code responses