Messente logo

Omnichannel API

Omnichannel API Setup

Omnichannel API allows you to send a message to a phone number using various channels as a backup, if the message happens not to be delivered via some channel.

This tutorial will guide you through the setup of Omnichannel API.

  1. Create a Messente Account on https://dashboard.messente.com/register
  2. Obtain your Messente API username and API password from API Settings page - https://dashboard.messente.com/api-settings
  3. Start using the API

API endpoint

Omnichannel API requests are made to the following server:

https://api.messente.com

Authentication

Authentication is done using HTTP Basic Authentication using your Messente API username and password.

Requestand response FORMAT

All request and response bodies for the API calls are JSON encoded. 

Accept and Content-Type headers must be set to application/json.

Response HTTP status codes

API call responses have status codes according to REST specifications.

Only 2XX response codes indicate a successful response.

Send Omnimessage

To send a Omnimessage, make the following request

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

Request headers

HTTP header Description Required
Content-Type application/json Yes
Accept application/json Yes

Request body (JSON encoded)

Key Description Required
scenarios
List[ScenarioItem]
Yes
viber ViberMessage
No
sms No
to Phone number of recipient in international format (+<country_code><local number>)
Yes
dlr_url URL where the automatic Delivery Request is made. Defaults to value set in API settings
No

SmsMessage

Key Description Required
 text All characters (Unicode) and long messages are supported  
Yes
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 No
autoconvert  1. on (default) Use replacement settings from the account's API Auto Replace settings page 2. full All non GSM 03.38 characters will be replaced with suitable alternatives 3. off Message content is not modified in any way
 No

ViberMessage

Key Description Required
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 No
text
Content of the viber message (maximum of 1000 characters)
No
button_text The text on the button No
button_url The URL of the button No
image_url Embedded image URL
No

Available value combinations of text, button_text, button_url and image_url:

  • text
  • text + button_text + button_url
  • text + button_text + button_url + image_url
  • image_url

ScenarioItem

Key DESCRIPTION REQUIRED
channel One of viber, sms
Yes
validity Specifies the maximum time (in minutes) that is spent trying to send a message via this channel
No

Response body (JSON encoded)

Key tYPE Value
omnimessage_id string Unique identifier for this Omnimessage
to string The phone number which received the message
messages List[MessageResult] List of messages that were specified to be sent

MessageResult

Key Type Value
message_id string Unique identifier for this message
sender string Sender that was used
channel string Channel for this message

Example REQUEST PAYLOAD

{
 "dlr_url": "http://example.com",
 "scenarios": [
   {"channel": "viber"},
   {"channel": "sms"}
  ],
 "sms": {
   "text": "hello sms"
 },
 "to": "+372555555",
 "viber": {
   "sender": "MySender",
   "text": "hello viber"
 }
}

EXAMPLE RESPONSE PAYLOAD

{
 "messages": [
   {
     "channel": "viber",
     "message_id": "98c90404-9f5b-44fd-a4ca-d29e0337580d",
     "sender": "MySender"
   },
   {
     "channel": "sms",
     "message_id": "a0ad638b-1a52-4d53-96ac-b593bcff06f5",
     "sender": "MySender"
    }
 ],
 "omnimessage_id": "b841d328-ff7f-4c0f-8f5b-ac931bff767c",
 "to": "+372555555"
}

Delivery Report

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)

Key Type Value
err integer machine-readable error code
error string human-readable error
message_id string unique identifier for the message
omnimessage_id string unique identifier for the omnimessage
status string machine-readable status code
sender string  sender used for this message

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"
}