Viber

The following Viber messages are supported:

• text only;

• image only;

• text + button to follow the link;

• text + image + button to follow the link.

Lifetime of Viber messages: from 30 to 86400 seconds (24 hours).

The Viber message lifetime is passed in the request in the viberTtl parameter.

Sending Requests

POST and GET requests are allowed in the HTTP API.

Request Examples

POST requestGET requests

Text formatText in URL format

POST request with a message in Latin “test“ in a simple text format.

{
    POST /login HTTP/1.1
    Host: 10.10.10.10:9080
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
    Content-Length: 58
    serviceId=login&pass=123&clientId=79161234567&message=test
}

Request Parameters

The parameters are applicable for POST and GET requests.

Parameter	Required	Type	Description
clientId	yes	string	Subscriber’s phone number, no more than 25 characters. More details Examples: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.
message	no	string	Text of the message in UTF-8 encoding. More details Maximum length: 1000 characters.
serviceId	yes	string	ID of the Partner’s service (login), which is used to send a message. More details The Service Provider establishes serviceId while enabling the Partner’s service and reports it to the Partner.
pass	yes	string	Password for authorization in the service. More details The Service Provider establishes the password while enabling the service and reports it to the Partner.
ptag	no	string	Message identifier in the Partner’s system. More details It may contain from 1 to 50 characters. Valid characters: 0...9a...zA...Z- It may be any identifier in the Partner's system. Note For example, it may be the unique identifier of a message or the identifier of subdivision, which initiates the request for sending. In contrast to the partnerMsgId parameter, which is needed to control resending and duplication, the Service Provider does not control values sent in the ptag parameter (only format compliance is checked). The Service Provider optionally returns this identifier to the Partner as part of a request for receiving the message delivery status (this functionality is described in the section Delivery Status Service).
imageUrl	no	string	Link to the image to be sent to the subscriber. More details The link must begin with "http://" or "https://".
buttonText	no	string	Text of the button. More details If the buttonText parameter is sent, the buttonLink parameter must be sent as well. Maximum length: 30 characters.
buttonLink	no	string	Link to follow to after clicking on the button. More details The link should start with "http://", "https://", "viber://", "tel:", "mailto:" Maximum link length: 2048 characters. If the buttonLink parameter is sent, the buttonText must be sent as well.
viberTtl	no	integer	Message lifetime. More details Acceptable range in seconds: from 30 to 86400. Recommended minimum value: 60. During this time, Viber will try to deliver the message to the subscriber. Values that go beyond the minimum and maximum ones will be rounded to them. If no parameter is sent, the default value will be used (agreed when the service started). If a message's lifetime has expired, it is assigned the "undelivered" status.
sending_time	no	string	Local time to send a message to a subscriber. More details Specified in the hh_hh format, where two hour values specify the time period in which the message should be sent. Warning If the parameter is specified, then its value cannot be empty. Note For example, if the parameter value is sending_time = 10_20, the message will be sent within the period from 10:00 to 20:00 local time in the time zone of the subscriber. The time zone of the subscriber is determined not by actual location of the subscriber. If the Partner doesn't send the time_zone parameter, the time zone of the subscriber will be determined by the phone number. If the Partner sends the time zone in the time_zone parameter, the message will be sent to the subscriber according to local time of this time zone.
time_zone	no	string	Time zone of the subscriber. More details Specified in the ±hh:mm format. For details see ISO 8601. If the Partner sends the value time zone in this parameter, the message will be sent to the subscriber according to local time of this time zone, otherwise the time zone of the subscriber will be determined by the subscriber's phone number. Note The subscriber with the number from Khabarovsk is in Moscow. The following sending options are available: The values are received: sending_time = 10_20, time_zone = +04:00 (Moscow time). The message will be sent within the period from 10:00 to 20:00 Moscow time. The sending_time = 10_20 value was received and the time_zone parameter wasn't passed. The message will be sent within the period from 10:00 to 20:00 (Khabarovsk time). For the zero zone it is necessary to specify a "+" or "–" sign. The "+" sign will be transformed into %2B when encoded in URL. For example, the +04:00 time zone will be sent as time_zone = %2B04:00.
source	no	string	Name of the sender. More details The message will be sent to the subscriber from the service name specified in this parameter. This parameter is optional. If the parameter is missing in the request, the message will be sent to the subscriber from the default service name (setting on the Service Provider's side). Important This parameter is not available for the Partner by default. This feature can be activated only after approval by the Service Provider. In this case, the list of allowed senders' names is set for the Partner's service or the dynamic signature feature is activated.
output	no	string	Request response format. More details If output = xml, the response to request will be formed as XML, see Response in the XML Format. If the parameter is not defined or is different, the default format is used: text/plain (see Response to the request).
partnerMsgId	no	string	Message unique identifier in the Partner’s system. More details Allowed length: from 1 to 50 characters. This parameter is required for resending and duplicate control. The Partner can send a request to send a message several times with the same partnerMsgId. In this case: the message will be sent to the subscriber only once (when the first request is received); in responses to requests the Service Provider will return to the Partner the same message identifier in the Service Provider system (the same that was sent for the first request). The Service Provider as an option returns this identifier to the Partner as a part of the request for receiving the message delivery status (see section Delivery Status Service). This parameter is not available by default. To enable this functionality, please consult with your manager.
shortenLinks	no	boolean	Parameter specifies whether to shorten links in the message text. More details Important It is used for single messages only. If cascade resending, you need to use the shorten_list parameter (see Cascading Message Sending). Important This option is not available by default. The connection of this functionality should be agreed with your supervising manager. For more details: see Link Shortening Service.

Note

Possible combinations of parameters in the request:

• message;
• imageUrl;
• message + buttonText + buttonLink;
• message + imageUrl + buttonText + buttonLink.

Response

After receiving and processing the request, the Service Provider synchronously returns the response to the Partner.

By default, the response from the Service Provider comes in the text/plain format.

In agreement with the Partner, the response can be generated in XML format.

Note

The Service Provider sends messages to subscribers only if the request is successfully processed.

Successful Sending

In case of successful processing of the request the Service Provider returns to the Partner:

• HTTP code 200 OK;

• the ID of the message in the Service Provider’s system.

Response exampleResponse parameters

{
   OK
   4095284974
}

Sending Errors

When sending an incorrect request, a short text error message may be transmitted in the response body.

Response exampleError codes when sending the request

An example of an error response – invalid serviceId/pass combination:

{
    Invalid password
}

Response in the XML Format

To receive the response in XML format the Partner needs to send the output = xml parameter in the body of the request.

In this case, the Service Provider synchronously responds to the request with one of the following HTTP codes:

• 200 — the request was successfully processed;

• 500 — internal server error, technical problems on the Service Provider’s side.

Response Examples

Successful sendingError sendingDescription of XML elements

Response example in XML format in case of successful request sending (HTTP code 200).

The description of the response content is given in the “Description of XML elements“ tab.

{
    <?xml version="1.0" encoding="utf-8"?>
    <response>
        <code>200</code>
        <text>OK</text>
        <payload>
            <id>4095284976</id>
        </payload>
    </response>
}

Viber Delivery Statuses

To receive Viber message statuses, you need to set up the Delivery Status Service.

Delivery Error Codes

Delivery error codes for each message type are provided in the corresponding tab of the Error codes (parameter unifiedExtStatus) section.

Viber Session

Viber Session is a feature that allows to the Partner to communicate with subscribers at a fixed price per session within a certain time frame.

It can be any reason for the request: a question, a message about a problem, checking the reservation or the delivery status. The subscriber will receive a response in real time.

Note

The feature of Viber sessions is not available by default. Please, contact your supervising manager to connect it.

Viber Session Setup

Using sessions includes having a special Viber business account.

You can create a new Viber business account with connected session functionality.

If you already have a valid business account and you would like to connect sessions to it, please, contact your supervising manager.

Important

For business accounts that support Viber sessions, messages with the type “text only“ or “image only“ are available (the value of InstantContent.type parameter must be TEXT or IMAGE_URL).

Features

The beginning of the session:

• only subscriber can initiate a session;

• the session starts when the subscriber sends the first message to the Partner;

• the session cannot be initiated by an image;

• if only one sender is present in the correspondence (it doesn’t matter whether it’s a subscriber or a Partner), this is not considered a session, messages will be charged in the usual way.

Session limits:

• session duration is 24 hours by default;

• the Partner can send up to 60 messages (a new session starts automatically after exceeding this limit);

• the Partner can send up to 10 messages without a subscriber’s response (the session is automatically closed after exceeding this limit);

• the Partner can send messages with the type “text“ or “image“ only.

End of the session:

• after 24 hours;

• after reaching the limit of 60 messages (a new session starts automatically);

• after reaching the limit of 10 unanswered messages from the Partner.

Billing of Viber Sessions

A subscription fee is charged for using the session functionality. Please check the session size with the supervising manager when creating a business account.

All sessions are paid for a fixed (identical) price. Messages within sessions are not charged.

Messages outside the session are charged as usual.