Omnichannel API Reference

To send a Omnimessage, make the request to following API endpoint:

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

Request headers

HTTP header Description
Authorizationrequired Basic authentication using Messente API username and password
Content-Typerequired Set to application/json
Acceptrequired Set to application/json

Request payload

Key Description
torequired Phone number of recipient in international format (+440000000)
messages[]required An array of SmsMessage, ViberMessage and WhatsAppMessage in the preferred delivery order.
At least one Message must be provided, no duplicate object types allowed.

SmsMessage
channelrequired Set to sms
textrequired All characters (Unicode) and long messages are supported
sender Optional parameter that sets the Sender name.
Value must be encoded in UTF-8.
When not set, the default API Sender Name for the account is used instead
udh UDH parameter of the SMS, hex-encoded
autoconvert
ondefault Use replacement settings from the account's API Auto Replace settings page
full All non GSM 03.38 characters will be replaced with suitable alternatives
off Message content is not modified in any way

ViberMessage
channelrequired Set to viber
sender Optional parameter that sets the Sender name. "sender" value must be encoded in UTF-8. When not set, the default API Sender Name for the account is used instead
text
Content of the viber message (maximum of 1000 characters)
button_text The text on the button
button_url The URL of the button
image_url Embedded image URL

* Possible combinations of text, image and button elements for ViberMessage:

Text Button Image
Only text
Text with button
Text, image and button
Only image    

WhatsApp
channelrequired Set to whatsapp
sender Optional parameter that sets the Sender name. "sender" value must be encoded in UTF-8. When not set, the default API Sender Name for the account is used instead
text
body
Text content for WhatsApp message
preview_link
(optional)
Whether to preview URLs included in the message

audio
content
Base64-encoded string containing binary audio

document
content
Base64-encoded string containing binary document
caption (optional)
Caption describing the document
image
content
Base64-encoded string containing binary image
caption
(optional)
Caption describing the image

time_to_send Send messages at some specific time in the future. Time must be specified in the 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)
dlr_url URL where the automatic Delivery Request is made.
Defaults to value set in API settings

Request example


POST /v1/omnimessage HTTP/1.1
Host: api.messente.com
Content-Type: application/json
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"to": "+37251916062",
"dlr_url": "https://myserver.com/dlr/messente/",
"messages": [
{
"channel": "whatsapp",
"sender": "Messente",
"text": {
"body": "Do you need a little coffee-kickstart on your way into the office today? Well, stop by the coffee shop and get half off any coffee with your personal code.",
"preview_link": true
},
},
{
"channel": "viber",
"sender": "Messente",
"text": "You're all checked in to your flight! Here's your mobile boarding pass. Need help with anything else?",
"image_url": "https://s15.postimg.cc/v4kocjc7v/Sample_QR_code.png",
"button_text": "Update flight info",
"button_url": "http://bit.ly/2M0r8LC"
},
{
"channel": "sms",
"sender": "Messente",
"text": "You're all checked in to your flight! Here's your mobile boarding pass. http://bit.ly/2M0r8LC"
}
]
}

Response body

Key Value
omnimessage_id Unique identifier for this Omnimessage
to The phone number which received the message
messages[] Array of MessageResults objects that were specified to be sent

MessageResult
message_id Unique identifier for this message
sender Sender that was used
channel Channel for this message - smsviber or whatsapp
errors[] In case there is an error with the message request, the errors are displayed here

ErrorItem
title Error message
detail Longer description of the error message
code Machine-readable error code

101 Not found
102 Forbidden
103 Unauthorized
104 Invalid data
105 Internal Server Error
106 Missing data
107 Method not allowed
source Location in the request body for this error message

Response body example

{
"messages": [
{
"channel": "whatsapp",
"message_id": "eb687d55-8e80-46de-a98d-2718503d5a56",
"sender": "Messente"
},
{
"channel": "viber",
"message_id": "57c8dae1-3f79-47e8-bb1d-a5aaa824ffad",
"sender": "Messente"
},
{
"channel": "sms",
"message_id": "e25c189e-c9f7-404b-9532-dfe1f168d8f5",
"sender": "Messente"
}
],
"omnimessage_id": "1dc8e83c-61de-4e99-a0b0-80da6c82b6fc",
"to": "+37251916062"
}

Delivery Reports

Delivery reports are JSON encoded HTTP POST messages sent from the following IPs:

  • 5.9.48.210
  • 5.9.235.252
  • 213.239.195.15

The provided Delivery report URL (drl_url) endpoint should respond with a HTTP status code within the range 200-399, otherwise the DRL will be considered undelivered.

Request body (JSON encoded)

KeyTypeValue
omnimessage_idstringUnique identifier for the Omnimessage
message_id
string
Unique identifier for the Message
sender
stringSender used for this message
status
string
Machine-readable status code

ACKOperator has accepted the message for delivery
DELIVRDThe message has been successfully delivered to the handset
UNDELIVUnable to deliver message to the handset
FAILEDFailed to deliver message to the handset
UNKNOWNUnknown status has been reported by the operator
ACCEPTD
Message has been accepted for the delivery and is in the operators's delivery queue
REJECTDThe message was rejected by the operator
EXPIREDDelivery of the message expired
NACK
The message delivery has been rejected
SEENThe message has been seen by the recipient
error
string
Human-readable error message
errintegerMachine-readable error code

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

Successful DLR example

{
    "status": "DELIVRD",
    "sender": "MySender",
    "err": 0,
    "message_id": "3e28ec48-d620-4191-a96e-d91ba8ecc949",
    "to": "+3725555555",
    "channel": "viber",
    "error": null,
    "omnimessage_id": "d7248cda-6c1a-4436-acf5-aaf249bb67d3"
}
                    

Failed DLR example

{
    "status": "NACK",
    "sender": "MySender",
    "err": 7,
    "message_id": "4e07b416-98df-4c93-87a4-88ede67cfc0e",
    "to": "+3725555555",
    "channel": "viber",
    "error": "Sender name not allowed",
    "omnimessage_id": "a372bb8a-09a2-4c85-8d46-c3b741e068aa"
}