REST API Guide v1.

3 CONFIDENTIAL

Document Technical Guide for

Version 1.3

Date
Omni Messaging REST API
2022-04-05

Copyright Table of Contents

Omni Messaging
Introduction
Version History
Terminology

Technical Description
Connecting to the API
Authentication
Sending Messages
Sending Status
Sending Recipients
Receiving Delivery Reports
Receiving Click/Open Notifications
Receiving Viber Subscription Status Notification
Account Status

Examples
Appendices
1. SMS Character Encoding
2. Multipart SMS

1
 REST API Guide v1.3 CONFIDENTIAL

Introduction

Version History

Version Date Comment

1.3 2022-04-05 Add sending_code option

Add sending_rate option

1.2 2020-12-01
Add Click/Open Notification

1.1 2020-09-07 Add Sending Template support

1.0 2017-07-20 Initial version

Terminology

Term Explained Comment

Application Programming
API
Interface

Global System for Mobile A digital mobile telephone system that uses a
GSM
Communication variation of time division multiple access.

The mobile equivalent of ISDN. Used as a

Mobile Station Integrated
value, MSISDN refers to the MSISDN subscriber
MSISDN Services Digital Network
ID, which is a max 15-digit number.

SMS MT are transported from the SMSC to the

handset and can be submitted to the SMSC by
other mobile subscribers via MO-SM or by
MT Mobile Terminated
other sources such as voicemail systems,
paging networks, or operators.

In information technology, a protocol is the

special set of rules that end points in a
Protocol
telecommunication connection use when they
communicate.

2
 REST API Guide v1.3 CONFIDENTIAL

Term Explained Comment

Ability of a mobile phone user to travel from

one cell to another, with complete
communications continuity. Roaming is
supported by a cellular network of radio base
Roaming
stations. It also is roaming is also the term
given for inter-network operability, i.e. moving
from one network provider to another
(internationally).

Service Level Agreement

SLA

An SMSC provides a number of services, in

particular the regulation of the transfer of text
messages between mobile phones. When a
user sends a text message (SMS message) to a
recipient, the phone actually sends the
message to the SMSC. The SMSC stores the
message and then delivers it to the destination
recipient when he is available. The SMSC
usually has a configurable time limit for how
long it will store the message, and the user can
usually specify a shorter time limit if he wants
Short Message Service to. Additionally the message centre will take
SMSC
Center care of any charging that needs to take place.
Generally speaking there is at least one Short
Message Service Centre (SMSC) per network.
For bulk transmission and reception of SMS
messages, SMSCs have conventional, fixed,
network interfaces as well as mobile network
interfaces. A number of protocols have been
defined to support this sort of wire-line access.
SMPP is the most commonly used of these
protocols.

A protocol for securely transmitting data via

SSL Secure Sockets Layer
the Internet.

3
 REST API Guide v1.3 CONFIDENTIAL

Technical Description
This document describes the REST API of the Bulk SMS platform that is used in order to manage all
important aspects of your Bulk SMS platform remotely. This document will be updated regurlarly as
an increasing amount of features will be added to the API. In case a future change is incompatible
with the current specification, a new API version will be created and compatibility to the features
that are described in this document will be maintained.

Connecting to the API

The API is designed according to the REST architecture and is available in the following URL:

https://api.omni-messaging.com/v1

The character set used by the API is UTF-8 and the data encoding format is JSON. For this reason the
content type that must be used in HTTP messages is:

Content-Type: application/json; charset=UTF-8

Authentication

The API uses standard HTTP authentication for user identification and access control. More
specifically an API client must include an HTTP authentication header in each request. The username
and the password of the HTTP request are the User ID and the Auth Key for each account. This
information is available in the API Settings page of the administration panel.

Username User ID

Password Auth Key

According to standard HTTP authentication method, an Authorization: Basic HTTP header must be
provided that contains the base64 encoded version of the string username:password. An example
HTTP header for a User having an ID of 1 and Auth Key "abcdefghijklm123456789" is:

GET https://api.omni-messaging.com/v1/account HTTP/1.1

Authorization: Basic MTphYmNkZWZnaGlqa2xtMTIzNDU2Nzg5
Host: api.omni-messaging.com
Accept: */*
Content-Type: application/json; charset=UTF-8
Content-Length: 0

4
 REST API Guide v1.3 CONFIDENTIAL

Response Format

The API presents a unified response format and the status of the request (successful or not) is
generally described by the HTTP Status Code that is returned to the HTTP Client that makes the
request. The HTTP status codes that are used by the API are:

HTTP Name Success Description

Status
Code

The request was successful and the

200 OK Yes body of the response contains
information.

The resource was created on the

201 Created Yes server and the body contains
information.

The request was not successful.

400 Bad Request No More information is displayed in the
response body.

The client was not able to provide

401 Unauthorized No the authorization required to use
this resource.

The resource was not found on the

404 Not Found No
server.

The requested resource is no longer

410 Gone No
available at the server.

Internal Server Error The server experienced a problem

500 No
handling the request.

The requested resource/method is

501 Not Implemented No
not implemented.

5
 REST API Guide v1.3 CONFIDENTIAL

The standard response format for successful requests is:

{
"status": "success",
"data": {

}
}

Please note that the type of the data field depends on the specific response. It usually contains a
JSON object but can also contain an Array or even primitive types like String, Integer etc.

The standard response format for failed requests contains an array of errors that caused the failure.
An example response format for failed requests is shown below:

{
"status": "error",
"errors": [
{
"code": 401,
"message": "Unauthorized"
}
]
}

Please note that not all error responses are guaranteed to contain the specified response format.
As a general rule, you must use the HTTP Status Code to determine if a request is successful or
not.

6
 REST API Guide v1.3 CONFIDENTIAL

Sending Messages

An API client is able to send messages to one or many recipients using the sendings resource of the
API.

In that case the request that has to be executed is:

POST https://api.omni-messaging.com/v1/sendings

Using this resource, the user creates a sendings object that describes the sending details. A
sufficiently detailed example is shown below:

{
"transaction_id": "a unique transaction id",
"sending_name": "Sending name",
"sending_code": "Sending code",
"execution_timestamp": 1504000000,
"allow_duplicates": false,
"channels": [
{
"push": {
"notification": {
"message": "Example push notification message"
},
"validity_period": 60
}
},
{
"viber": {
"message": {
"text": "Viber Message to {tag 1}"
},
"validity_period": 10
}
},
{
"sms": {
"from": "Sender",
"text": "SMS Message to {tag 1}",
"encoding": 0,
"type": 1,
"validity_period": 120
}
}
],
"destinations": [
{
"id": "1",
"phone_number": "306900000000",
"tags": [
"John"
]
}
]
}

7
 REST API Guide v1.3 CONFIDENTIAL

Each element is described in the following table.

Element Required Type Description

sending_name No String Sending Name.

sending_code No String Sending Code.

The execution date and time for the

sending in Unix Time. Using this field
you can schedule sendings to be
executed at a future date. Please
note that execution dates to the past
will produce an API error so keep
execution_timestamp No Integer
your server clock synchronized to an
acceptable time source. If an
"execution_timestamp" is not
provided, the sending is executed
immediately.

Allow sending more than one

message to each destination in one
sending (if the recipients contain the
same destination more than once).
The default value is false. When
allow_duplicates No Boolean using message personalization via
tags, you must set this to true in
order to send multiple messages that
may include different
personalization tags.

This required field is used as a

security precaution against
communication errors between the
API client and server. You should
produce a unique transaction ID for
each sending you wish to execute.
Do not use on the fly randomly
generated values or timestamps as
this does not protect against
transaction_id Yes String
communication errors. A primary key
that is generated in your systems is
the preferred value that denies the
prossibility for the exact sending to
be executed more than once. The
maximum length of this field is 50
characters.

8
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

An ordered list of objects that

defines the communication flow that
will be applied in this sending. Each
channel is repsesented using a JSON
object that is described in the
following sections. Possible values
are "sms", "push" and "viber".
channels Yes* Array During the sending execution,
attempts are made to deliver the
appropriate messages using the
channels in the order they appear
inside this array. The SMS channel if
used, must be the last element in
this array.

This replaces the channels element

according to the values of the
template. This value could be found
template_id Yes* String via the admin panel at "Messages
Template" section under the
"Message Composer" menu.

An array of destinations for this

sending. Each destination object will
destinations Yes Array
be described in the following
sections.

Sening Rate in messages/minutes.

sending_rate No Integer Disable value: 0. Minimum value: 50.
Maximum value: 500.

Required: Yes*. Please note that when template_id element is used then the channal element
is not required and will be ignored.

9
 REST API Guide v1.3 CONFIDENTIAL

A successful request creates a sending object that describes the parameters of the sending that was
just created. A sample response is shown below.

{
"status": "success",
"data": {
"transaction_id": "a unique transaction id",
"sending_name": "Sending name",
"sending_code": "Sending code",
"sending_id": "SD-abcd1234",
"channels": {
"push": {
"notification": {
"message": "Example push notification message"
},
"validity_period": 60
},
"viber": {
"message": {
"text": "Viber Message to {tag 1}"
},
"validity_period": 10
},
"sms": {
"from": "Sender",
"text": "SMS Message to {tag 1}",
"encoding": 0,
"type": 1,
"validity_period": 120
}
},
"recipients": [
{
"id": "1",
"phone_number": "306900000000",
"tags": [
"John",
"Smith"
]
}
],
"execution_timestamp": 1504000000,
"allow_duplicates": false,
"status": "pending",
"cost_estimation": 0.1825
}
}

10
 REST API Guide v1.3 CONFIDENTIAL

Most of the content of the response shows the message details that were used on this sending. The
following table describes the elements that have not been analyzed in the request object.

Element Always Present Type Description

A unique ID for this sending

generated from the API. This ID will
be mentioned in the delivery reports
if they are forwarded to the client's
sending_id Yes String
systems. It can also be used to
retrieve the status of the sending so
it is advised to store this value
permanetly.

An array of recipients that will

receive this sending. This array is a
combination of all destinations
recipients Yes Array
provided in the request and all
destinations contained in the
specified lists (if used).

The status of the sending. More

information about this field can be
status Yes String
found in the "Sending status"
response description.

The cost reserved for this sending.

cost_estimation Yes Float

11
 REST API Guide v1.3 CONFIDENTIAL

Channels Object
There are 3 types of channel objects that describe the different options for sending messages. Each
channel has unique characteristics that will be explained in detail in the following sections.

SMS

The user can choose to send an SMS message to each recipient, either directly or as a fallback
method if messages sent using other channels fail or get expired. An SMS channel object describes
all aspects of the SMS message and is shown in the following example:

{
"sms": {
"from": "Sender",
"text": "SMS Message to {tag 1}",
"encoding": 0,
"type": 1,
"validity_period": 120
}
}

Alternatively the Template feature could be used in an SMS object as shown in the following
example:

{
"sms": {
"template_id": "TP-NCEPMRHm",
"validity_period": 120
}
}

12
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

Declares that this specific messaging

sms Yes Object channel is an SMS channel.

Defines the Sender ID used for this

channel. According to the SMS
specification the Sender ID can be
either Numeric or Alphanumeric. The
following restrictions apply for each
kind:

Numeric: Up to 15 numbers with

an optional plus sign if the Sender
sms.from Yes* String ID is an international phone
number (ex. +1555999999).
Alphanumeric: Up to 11 Latin
characters or numbers. Simple
symbols are supported by the
platform but may cause
deliverability issues to various
international operators. Symbols
that are relatively safe to be used
are the following: + - _ ! $ . , and
space.

This replaces the sms.from,

sms.text, sms.encoding and
sms.type elements according to the
values of the template. If this
element is set then any of the
followign elements sms.from,
sms.text, sms.encoding and
sms.template_id Yes* String
sms.type are treated as overwrites
for the corresponding values of the
template. This value could be found
via the admin panel at "Messages
Template" section under the
"Message Composer" menu.

The text of the SMS message.

Multipart/Long SMS messages are
supported. You can find more
sms.text Yes* String information about the characters
supported as well as the character
limits in Appendices 1 and 2.

Required: Yes*. Please note that when sms.template_id element is used then the sms.from
and sms.text elements are not required.

13
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

The charset of the SMS message. The

default value is 0 that enforces a 160
character SMS in GSM encoding.
Possible values are 0 (GSM) and 1
(UTF-8). Please note that this value
sms.encoding No Integer does not affect the character
encoding of this API that must
always be UTF-8. More information
regarding SMS character sets can be
found in Appendix 1.

The type of the SMS message. The

default value is 1 that means a
sms.type No Integer standard SMS message. By using a
value of 0 the message will be sent
as a flash SMS.

The number in minutes that this

channel is active. After the specified
period, the messages expire and will
not reach their recipients at all. The
sms.validity_period No Integer
default validity period that will be
used if this field is not provided is
2880 minutes (2 days).

14
 REST API Guide v1.3 CONFIDENTIAL

Viber

Viber messages can be sent through this API for accounts that have the Viber capability enabled and
configured. A full featured Viber message object is shown below:

{
"viber": {
"message": {
"text": "Viber Message to {tag 1}",
"caption": "Click here",
"action": "http://example.com/",
"image": "http://via.placeholder.com/350x150"
},
"validity_period": 5,
"action_tracking": false,
"smartphone_only": false
}
}

Alternatively the Template feature could be used in an Viber object as shown in the following
example:

{
"viber": {
"template_id": "TP-NCEPMRHm",
"validity_period": 5
}
}

15
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

Declares that this specific messaging

viber Yes Object channel is a Viber channel.

This replaces the viber.message,

viber.action_tracking and
viber.smartphone_only
elements according to the values of
the template. If this element is set
then viber.message,
viber.action_tracking and
viber.smartphone_only
viber.template_id Yes* String
elements are not required and will
be overwritten by the values of the
template. This value could be found
via the admin panel at "Messages
Template" section under the
"Message Composer" menu.

Specifies the Viber message details.

viber.message Yes* Object

This is the text of the Viber message

that will be sent to the recipient. The
viber.message .text Yes String
maximum length is 1000 characters.

In case the Viber message has an

viber.message .caption action URL, this field specifies the
No String
text that is displayed on the button.

The URL that will open in the

device's default browser if the
viber.message .action
No URL recipient clicks on the action button
of the message. Action URL can be
personalized.

Please note that the action element can be personalized by using the {tag #} notation. All tags
in action URL will be url encoded except of the first tag in case action URL starts with a tag.

Required: Yes*. Please note that the viber.message and viber.template_id element are
not simultaneously required.

16
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

Viber messages can contain an

optional image. This field specifies
viber.message .image No URL the URL of an image file that will be
shown in the appropriate location
inside the Viber message.

The number in minutes that this

channel is active. After the specified
period, the messages expire and will
not reach their recipients at all. The
viber.validity_period Yes Integer
minimum value is 5 minutes and the
maximum value is 1440 minutes (1
day).

Used with viber.message .action. Set

this value to true in order to track if
viber.action_tracking No Boolean
and when the user clicked the
action.

Set this value to true in order to limit

viber.smartphone_only No Boolean the sending to smartphones only

17
 REST API Guide v1.3 CONFIDENTIAL

Push

An alternative communication channel that can be used in sending messages is the Push Notification
channel. If the requirements are met and the account configuration is complete, a push notification
campaign can be scheduled using the following specifications. A simple Push Channel object is
shown below:

{
"push": {
"notification": {
"title": "Push notification title",
"message": "Example push notification message",
"url": "",
"custom_data": {

}
}
}
}

Element Required Type Description

Declares that this specific

push Yes Object messaging channel is a Push
Notification channel.

The payload of the push

push.notification Yes Object
notification message.

The text that will be displayed

as the push notification
push.notification.title Yes String
title/header in both platforms.

The text that will be displayed

as the push notification
push.notification.message Yes String
message in both platforms.

An optional URL that will be

opened when a recipient taps
push.notification.url No URL
on a push notification message.

18
 REST API Guide v1.3 CONFIDENTIAL

Element Required Type Description

An optional object that will be

sent within the push
notification message. The
content is user configurable as
well as the action performed
push.notification.custom_data No Object inside the mobile application.
Possible actions and special
handling must be implemented
on build time inside the mobile
application.

19
 REST API Guide v1.3 CONFIDENTIAL

Destinations

The destinations element of the sending object is used to define the destination phone numbers
for each sending. Each sending can be used to send messages to more than one recipients at a time,
for this reason the destinations object is an Array of destination objects.

Simple Destination
In it's simplest form, a destination can be a sigle phone number in International format. You may
also specify a unique id and destination specific tags. A full-featured example is shown below:

{
"id": "1",
"phone_number": "306900000000",
"tags": [
"John",
"Smith"
]
}

Element Required Type Description

A unique id that identifies the

specific message. This id will be
mentioned inside the delivery
reports of each message. In case an
id No String
id is not provided, the API will
generate a unique id for this
message and will return it inside the
HTTP response.

The phone number of the recipient

phone_number Yes String in international format without
leading zeros or +.

An array of strings that are linked to

this specific destination. Using tags,
you are able to send personalized
messages to each destination using a
tags No Array single request. You can find more
information about the usage of tags
in personalized messages in the
examples section.

20
 REST API Guide v1.3 CONFIDENTIAL

List
If you wish to send messages to a list that is already created through the administration panel, a
different destination object makes this possible. In the following example you can see that the
intended recipients for this sending are included in list LS-abcd1234.

{
"list_id": "LS-abcd1234"
}

Element Required Type Description

The list ID, you can find the list IDs

list_id Yes String for existing lists using the
administration panel.

You can also combine the 2 destination objects in order to send messages to multiple phone
numbers and multiple lists at the same time.

When list objects are used as destinations, the API retrieves and combines the phone numbers
contained in these lists as well as any extra destinations provided with the request. The response
contains an array of all destinations that will receive the message and a unique id for each
destination.

21
 REST API Guide v1.3 CONFIDENTIAL

Sending Status

After a successfull sending creation the API offers a unique resource for each sending that a client
can use to monitor and retrieve information about the sending. The API call that must be executed
for this reason is:

GET https://api.omni-messaging.com/v1/sendings/[Sending ID]

The Sending ID that has to be used was mentioned in create sending response (example format:
SD-abcd1234). A successfull response contains the following information:

{
"status": "success",
"data": {
"transaction_id": "a unique transaction id",
"sending_id": "SD-abcd1234",
"sending_name": "Sending name",
"sending_code": "Sending code",
"channels": {
"push": {
"notification": {
"message": "Example push notification message"
},
"validity_period": 60
},
"viber": {
"message": {
"text": "Viber Message to {tag 1}"
},
"validity_period": 10
},
"sms": {
"from": "Sender",
"text": "SMS Message to {tag 1}",
"charset": "GSM",
"validity_period": 120
}
},
"charge": 0.09,
"execution_timestamp": 1504000000,
"allow_duplicates": false,
"status": "finished",
"delivery_status": [
{
"push": {
"delivery": {
"pending": 0,
"expired": 0,
"failed": 0,
"delivered": 0,
"opened": 0
}
}
},

22
 REST API Guide v1.3 CONFIDENTIAL

{
"viber": {
"delivery": {
"pending": 0,
"expired": 0,
"failed": 0,
"delivered": 1,
"seen": 1
}
}
},
{
"sms": {
"delivery": {
"delivered": 0,
"not_delivered": 0,
"call_barred": 0,
"blocked": 0,
"absent_subscriber": 0,
"no_sms_subscription": 0,
"submitted": 0
}
}
}
]
}
}

The response contains the sending data as shown in "Create Sending" request as well as some extra
information regarding the sending and it's status. The extra fields are:

Element Always Present Type Description

The current charge for this sending.

This value will be changed at the end
of the sending after all channels and
charge Yes Number fallback scenarios are finished. This
final value will be the actual cost
associated with this sending.

23
 REST API Guide v1.3 CONFIDENTIAL

Element Always Present Type Description

pending: The sending will be

executed within the next few
minutes.
ongoing: The sending has started
and is in progress.
fallback_pending: The first or
second channel of this sending is
executed and the platform is
waiting for delivery expirations in
order to execute message sending
due to destinations being
unreachable in previous channels.
done: All sending channels are
finished executing (temporary
status prior to finished).
status Yes String finished: The actual charge of the
sending has been calculated.
failed: The system was not able to
execute the sending for various
reasons. If the reason is not
obvious (for example insufficient
balance on your account) you
should contact customer support
in order to investigate the reasons.
scheduled: The sending is to be
executed at a future date, 5
minutes prior to sending execution
the status will change to "pending"
and no modifications are allowed.

In this object you can find the total

number of messages per channel and
status. Each channel has a different
delivery_status No Object
set of statuses. You can find a
detailed list in the delivery reports
section.

24
 REST API Guide v1.3 CONFIDENTIAL

Sending Recipients

After a successfull sending creation the API offers a unique resource for each sending that a client
can use to monitor and retrieve information about the sending recipients. The API call that must be
executed for this reason is:

GET https://api.omni-messaging.com/v1/sendings/[Sending ID]/recipients

The Sending ID that has to be used was mentioned in create sending response (example format:
SD-abcd1234). A successfull response contains the following information:

{
"status": "success",
"data": [
{
"id": "SD-bfLodvhR-000000",
"phone_number": "306900000000",
"tags": [
"Tag 1"
],
"messages": {
"viber": {
"message": {
"text": "Tag 1",
"caption": "Caption",
"action": "Action",
"image": "Image URL"
},
"validity_period": 20,
"charge": 0,
"timestamp": 1521721262,
"fallbacked": true,
"dlr": "no_suitable_device",
"dlr_timestamp": 1521721272,
"message_status": "not_seen",
"message_status_timestamp": 1521721262
},
"sms": {
"from": "Sender",
"text": "Tag 1",
"type": "sms",
"encoding": "gsm",
"validity_period": 60,
"parts": 1,
"charge": 0.1825,
"timestamp": 1521721291,
"fallbacked": false,
"dlr": "submitted",
"dlr_timestamp": 1521721291
}
}
}
]
}

25
 REST API Guide v1.3 CONFIDENTIAL

The response data contains data for every recipient of the sending if the following format.

data is an array of Objects structured as described below

Element Type Description

id String The recipient id.

The phone number of the recipient in international

phone_number String
format without leading zeros or +.

An array of strings that are linked to this specific

destination. Using tags, you are able to send
personalized messages to each destination using a
tags Array
single request. You can find more information about
the usage of tags in personalized messages in the
examples section.

Object contains containts massage object that

messages Object provide information of messages send to this
recipinet.

Viber message object.

Element Type Description

As described in Channels Object section

viber .message Object

As described in Channels Object section

viber .validity_period Number

The current charge for this sending. This

value will be changed at the end of the
sending after all channels and fallback
viber .charge Number
scenarios are finished. This final value will
be the actual cost associated with this
sending.

Defines the timestamp of the creation of

viber .timestamp Number
this message in Unix Time format.

Defines if this message has fallback via

viber .fallbacked Boolean
the next channel.

As described in Receiving Delivery Reports

viber .dlr String
section.

As described in Receiving Delivery Reports

viber .dlr_timestamp Number
section.

As described in Receiving Delivery Reports

viber .message_status String
section.

viber .message_status_timestamp As described in Receiving Delivery Reports

Number
section.

26
 REST API Guide v1.3 CONFIDENTIAL

SMS message object.

Element Type Description

As described in Channels Object section

sms .from String

As described in Channels Object section

sms .text String

As described in Channels Object section

sms .encoding String

As described in Channels Object section

sms .validity_period Number

sms .parts String Defines the SMS parts.

The current charge for this sending. This

value will be changed at the end of the
sending after all channels and fallback
sms .charge Number
scenarios are finished. This final value will
be the actual cost associated with this
sending.

Defines the timestamp of the creation of

sms .timestamp Number
this message in Unix Time format.

As described in Receiving Delivery Reports

sms .dlr String
section.

As described in Receiving Delivery Reports

sms .dlr_timestamp Number
section.

27
 REST API Guide v1.3 CONFIDENTIAL

Account Status

Information regarding your account status is available using the account resource.

GET https://api.omni-messaging.com/v1/account

An example response is shown below

{
"status": "success",
"data": {
"id": 1,
"username": "test",
"email": "[email protected]",
"mobile": "306900000000",
"account_status": "active",
"balance": 500.000
}
}

28
 REST API Guide v1.3 CONFIDENTIAL

Receiving Delivery Reports

The messaging platform is able to forward delivery reports as they are received to client's system
that have initiated the sending. In order to enable the delivery report forwarding you must provide a
callback URL via the API section of the Web Administration Panel. This setting is user-specific and is
used for all delivery report events.

If everything is setup correctly the system will initiate a request as follows:

POST https://your-domain.com/api/delivery-reports

The full URL is user configurable. The body of the request will contain a JSON object as is shown in
the following example.

{
"id": "SD-abcd1234-000001",
"transaction_id": "a unique transaction id",
"sending_id": "SD-abcd1234",
"channel": "viber",
"dlr": "delivered",
"dlr_timestamp": 1504000030,
"message_status": "opened",
"message_status_timestamp": 1504000030
}

Each field contains information for a specific destination and is explained in the following table:

29
 REST API Guide v1.3 CONFIDENTIAL

Element Always Present Type Description

Corresponds to the Recipient ID

(id element inside each recipient
id Yes String
object in create sending
response).

Corresponds to the Transaction

transaction_id Yes String ID (found in create sending
response).

Corresponds to the Sending ID

sending_id Yes String (sending_id in create sending
response).

Defines the channel of this DLR

Notification. Possible values are
channel Yes String
"sms", "push" and "viber"

Defines the delivery status of

the message. Please refer to the
dlr Yes String
tables below for more
information.

Defines the timestamp of the

dlr_timestamp Yes Integer delivery report in Unix Time
format.

Defines the opened/seen status

of the message (avaliable only
for push and viber channels).
message_status No String Possible values are "opened",
"not_opened", "seen" and
"not_seen".

Defines the timestamp of

message_status_timestamp No String opened/seen event in Unix Time
format.

30
 REST API Guide v1.3 CONFIDENTIAL

Possible DLR values for SMS channel.

DLR Description State

delivered Delivered to phone Final

not_delivered Undelivered to phone Final

pending Buffered to gateway Intermediate

The SMS is undeliverable due to an

invalid/permanently barred MSISDN for the
invalid_msisdn Final
operator. This MSISDN should not be used again for
SMS submissions.

The SMS expired as it could not be delivered within

expired Final
the validity period set.

The SMS delivery to the MSISDN is blocked

call_barred Final
from the Mobile Operator.

Possible DLR values for Push channel.

DLR Description State

pending Message delivered to gateway for delivery Intermediate

expired Message Expired Final

failed Undelivered to device Final

delivered Delivered to device Final

Possible message_status values for Push channel.

mesage_status Description State

opened Message opened on device Final

not_opened Message not opened on device Intermediate

31
 REST API Guide v1.3 CONFIDENTIAL

Possible DLR values for Viber channel.

DLR Description State

pending Message delivered to gateway for delivery Intermediate

expired Message Expired Final

failed Undelivered to device Final

delivered Delivered to device Final

blocked Blocked Final

no_suitable_device Not suitable device Final

not_viber_user MSISDN is not a viber user Final

Possible message_status values for Viber channel.

mesage_status Description State

seen Message seen on device Final

not_seen Message not seen on device Intermediate

32
 REST API Guide v1.3 CONFIDENTIAL

Receiving Click/Open Notifications

The messaging platform is able to forward Click/Open notifications as they are received to client's
system that have initiated the sending. In order to enable the notifications forwarding you must
enable delivery reports by provide a callback URL via the API section of the Web Administration
Panel and enable the "Click Notification Events" option.

If everything is setup correctly the system will initiate a request as follows:

POST https://your-domain.com/api/delivery-reports

The full URL is user configurable. The body of the request will contain a JSON object as is shown in
the following examples.

Click event payload for Viber channel:

{
"id": "SD-abcd1234-000001",
"transaction_id": "a unique transaction id",
"sending_id": "SD-abcd1234",
"channel": "viber",
"clicked": true,
"clicked_timestamp": 1504000030,
"device_type": "mobile",
"device_os": "android"
}

Click event payload for SMS channel:

{
"id": "SD-abcd1234-000001",
"transaction_id": "a unique transaction id",
"sending_id": "SD-abcd1234",
"channel": "sms",
"opened": true,
"opened_timestamp": 1504000030
}

Each field contains information for a specific destination and is explained in the following table:

33
 REST API Guide v1.3 CONFIDENTIAL

Element Always Present Type Description

Corresponds to the Recipient ID

(id element inside each recipient
id Yes String
object in create sending
response).

Corresponds to the Transaction

transaction_id Yes String ID (found in create sending
response).

Corresponds to the Sending ID

sending_id Yes String (sending_id in create sending
response).

Defines the channel of this DLR

Notification. Possible values are
channel Yes String
"sms", "push" and "viber"

Defines the opened status of the

opened No Boolean landing page for SMS messages.

Defines the timestamp of

opened_timestamp No String opened event in Unix Time
format.

Defines the clicked status of the

clicked No Boolean
Viber Actions URL.

Defines the timestamp of click

clicked_timestamp No String event in Unix Time format.

Defines the type of device that

the click event occured. Possible
device_type No String values are "tablet", "mobile",
"desktop' and "other"

Defines the opation system of

the device ther the click event
device_os No String occured. Possible values are
"android", "ios" and "N/A".

34
 REST API Guide v1.3 CONFIDENTIAL

Receiving Viber Subscription Status Notification

The messaging platform is able to forward Viber subscription status change notification as they are
received to client's system. In order to enable the subscription status change notifications
forwarding you must provide a callback URL via the API section of the Web Administration Panel.
This setting is user-specific.

If everything is setup correctly the system will initiate a request as follows:

POST https://your-domain.com/api/viber-subcription-notifications

The full URL is user configurable. The body of the request will contain a JSON object as is shown in
the following example.

{
"id":"15",
"msisdn":"306900000000",
"type":"user_subscribed",
"timestamp":1521105142
}

Each field contains information for a specific destination and is explained in the following table:

Element Always Present Type Description

id Yes String Unique ID

msisdn Yes String Corresponds to user's MSISDN.

Susbcription status. Possible values:

user_subscribed: User subcribed

type Yes String user_unsubscribed: User
Unsubcribed

Defines the timestamp of the

timestamp Yes Integer
notification in Unix Time format.

35
 REST API Guide v1.3 CONFIDENTIAL

Examples
Minimum SMS Sending

POST https://api.omni-messaging.com/v1/sendings

{
"transaction_id": "a unique transaction id",
"channels": [
{
"sms": {
"from": "Sender",
"text": "Message goes here"
}
}
],
"destinations": [
{
"id": "1",
"phone_number": "306900000000"
}
]
}

Minimum Viber Message Sending

POST https://api.omni-messaging.com/v1/sendings

{
"transaction_id": "a unique transaction id",
"channels": [
{
"viber": {
"message": {
"text": "Viber Message"
}
}
}
],
"destinations": [
{
"id": "1",
"phone_number": "306900000000"
}
]
}

36
 REST API Guide v1.3 CONFIDENTIAL

Viber message with fallback to SMS and personalization

POST https://api.omni-messaging.com/v1/sendings

{
"transaction_id": "a unique transaction id",
"channels": [
{
"viber": {
"message": {
"text": "Hello {tag 1}, your invoice for
January is issued. Amount due: {tag 2}"
},
"validity_period": 30
}
},
{
"sms": {
"from": "Online Shop",
"text": "Hello {tag 1}, your invoice for January is
issued. Amount due: {tag 2}",
"validity_period": 120
}
}
],
"destinations": [
{
"id": "1",
"phone_number": "306900000000",
"tags": [
"John",
13.37
]
},
{
"id": "1",
"phone_number": "306900000001",
"tags": [
"Maria",
50
]
}
]
}

37
 REST API Guide v1.3 CONFIDENTIAL

Appendices

1. SMS Character Encoding

GSM

According to the GSM specification, a standard SMS message can contain up to 140 bytes of data.
Standard Latin (ISO-8859-1) character encoding represents a single character using 1 byte, which is 8
bits. Therefore, the maximum number of Latin 1 characters that could be included in an SMS is 140.

GSM encoding represents characters using 7 bits instead of 8. This therefore provides a maximum of
160 characters per SMS. (140 * 8 bits) / 7 bits = 160.

This effectively halves the number of characters that the GSM character set can support, compared
to ISO-8859-1. In order to include common characters that are usually represented using the 8th bit,
these characters as well as other symbol characters must be re-mapped to a combination of lower
bits. These remapped characters are often referred to as special characters. This remapping, in
combination with packing 7-bit characters into 8-bit bytes is called GSM Encoding.

A standard plain text (7-bit) SMS can contain up to 160 characters.

Due to the fact that the character set of this API is UTF-8 it is possible for the SMS text to contain
characters that cannot be represented from the standard GSM character set. In these cases an
automatic replace mechanism attempts to replace missing characters with visually similar
characters. If such a replacement is not possible then the offending character is removed from the
resulting SMS message.

You can find more information regarding the GSM character set here

Important Notice: According to the GSM specifications, the 9 special characters listed below count
as 2 individual characters:

Character Description

€ Euro sign

^ Circumflex accent

{ Left curly bracket

} Right curly bracket

[ Left square bracket

] Right square bracket

~ Tilde

| Vertical bar

\ Backslash

38
 REST API Guide v1.3 CONFIDENTIAL

Unicode (UTF-8)

This character format allows for a greatly extended character set which supports many languages.
Due to the fact that each Unicode character requires 2 bytes, the SMS message length is reduced to
70 characters. 140 bytes / 2 bytes = 70 characters.

2. Multipart SMS
It is possible to send multiple SMS joined together to form a single long message. This type of
message is referred to as one of the following:

Long SMS
Concatenated SMS
Multipart SMS

A long SMS is comprised of several standard SMS containing a concatenation header at the beginning
of each one. Since this header is within the message, it reduces the total size of each SMS according
to the table below:

# SMS GSM Characters Unicode Characters

1 160 70

2 306 134

3 459 201

4 612 268

5 765 335

n n * 153 n * 67

Concatenated SMS are charged by the number of individual SMS messages used. If you send a 459
7-bit characters message, you will be charged for 3 SMS.

39