VIBER API

DecisionTelecom Viber API allows you to send and receive Viber business messages to and from any country in the world via API. Each message is identified by a unique random ID, so users can always check the status of a message using given endpoint.

The Viber API uses HTTPS with access key that is used as the API authorization. Request and response payloads are formatted as JSON using UTF-8 encoding.

API Authorization - Base64 access key.

Please contact your account manager to get an API key.

Auth

Basic Auth

Example:

$userHashKey = 'User Hash Key provided by your account manager';
$ch = curl_init('https://web.it-decision.com/v1/api/send-viber');
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$userHashKey");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestParams)); // 
$requestParams - raquest array with correct data 
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); 
$result = curl_exec($ch); 
curl_close($ch);

Send Viber message

Parameters

source_addr:

from 3 to 20 characters - from whom the message

destination_addr:

from 11 to 20 digits - to whom the message

message_type (Type of message sent):

6 - only text (for primary device)

225 - only text (for all devices)

8 - text+image+button (for primary device)

108 - text+image+button (for all devices)

9 - text+ button (for primary device)

109 - text+button (for all devices)

222 - send file (for all devices) , supported formats: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

301 - template transactional text (for primary device)

304 - template transactional text (for all devices)

901 - carousel message (for all devices)

text:

up to 1000 characters - text of Viber message

image (Correct URL with image for promotional message with button caption and button action):

jpg or jpeg (mime type is image/jpeg), maximum resolution 800x800 pixels

png (mime type is image/png), maximum resolution 800x800 pixels

button_caption:

from 1 to 30 characters - button caption

button_action:

Correct URL for transition when you press the button

source_type (Message sending procedure):

promotion message (the message can be with text, picture, button) - 1

transactional message (template text message) – 2

callback_url:

Correct URL for message status callback

validity_period:

TTL (Time to live) allows the sender to limit the lifetime of a message. In case the message did not get the status "delivered" before the time ended, the message will not be charged and will not be delivered to the user. In case no TTL was provided (no "ttl" parameter) Viber will try to deliver the message for up to 1 day.

promotion message - min TTL 60 seconds max TTL 43200 seconds (12 hours)

transactional message - min TTL 60 seconds max TTL 43200 seconds (12 hours)

file_url:

Only for 222 message type сorrect URL for document. Possible file extensions to send: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx The file name must contain an extension and must not exceed 25 characters. File size must be up to 200 MB.

carousel:

message type enables businesses to send a single message featuring text and multiple customizable sections (items), each showcasing different products or services along with dedicated media and a call-to-action. The message type allows presenting from 2 to 5 individual items. Each carousel item includes an image, a brief description, and offers up to 2 customizable buttons. All items in the carousel can have different sets of buttons.

items: from 2 to 5 carousel items.

  • title (Mandatory) - Item title text. From 2 to 38 UTF-8 characters.

  • imageUrl (Mandatory) - Expected formats - PNG, JPEG, jpg. Recommended size: 215x185

  • primaryButton (Mandatory) - Holds a set of primary button parameters.

  • secondaryButton (Optional) - Holds a set of secondary button parameters.

  • label (Mandatory) - Button parameter. The text that will appear on the action button. Up to 10 UTF-8 characters when inside the primaryButton. Up to 12 UTF-8 characters when inside the secondaryButton.

  • actionUrl (Mandatory) - Button parameter. The URL users are directed to or the action performed when pressing the action button\or tap on the image.

Response:

Values:

message_id:

Sent message ID

Send verification messages (OTP)

Logic

A templated message is a predefined message stored on Viber side which allows the sender to define specific values upon sending the message. Viber`s verification messages are new message types designed for sending one time passwords (OTP) using pre-approved and pre-designed templates.

Availability

Templates described in the Predefined OTP Templates section are available for all services by default. In contrast to our regex template logic, there is no need to submit a template for each and every service separately, they are already stored on our side.

Copy

A templated message has a predefined copy which includes predefined variables that can be defined to hold a requested value by the sender. Variables are specific and defined for each template and will be validated according to specific limitations of each variable.

Example of templated message structure: Your code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

In this case, the sender can define the pin value when sending the message. For example, if the sender will define the pin as 123456, the message that will be shown to the user will be: Your code is 123456. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Additional Parameters for OTP

message_type: Mandatory. 701 - template message sent to primary only 702 - template message sent to all of the user devices

template_id: Mandatory. Predefined code of a template copy to be sent.

template_params: Mandatory. A range of variables which are specific per template. For the templates and possible values description. Each template holds a different set of parameters which will be validated upon request.

Predefined OTP Templates

1.Basic OTP

Template ID

0aac888f-2ee2-4112-9659-1755a951966a

English Copy

Your code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT

2.Basic OTP valid for 5 minutes

Template ID

c2cdc028-a48b-4187-bbaf-3aaa137b6e23

English Copy

Your code is {{pin}}. It's valid for 5 minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT

3.OTP with business/platform name

Template ID

c33cccaf-735f-4d62-8383-a76bf4999e2d

English Copy

{{business_platform_name}}: Your code is {{pin}}.

Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{business_platform_name}} - TEXT

4.Basic OTP with code validity time

Template ID

bed0942f-e07e-4879-834b-29cc4cf3ec35

English Copy

Your code is {{pin}}. It's valid for {{code_validity_time}} minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{code_validity_time}} - NUMBER

5.OTP with code type & validity time

Template ID

60d67b38-b9fb-444a-80e6-754447e010c6

English Copy

Your {{pin_type}} code is {{pin}}. It's valid for {{code_validity_time}} minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{pin_type}} - TEXT {{code_validity_time}} - NUMBER

6.OTP with business/platform name & validity time

Template ID

6c929cef-29b4-4349-bc9d-2a07bdbb6e43

English Copy

Your {{business_platform_name}} code is {{pin}}. It's valid for {{code_validity_time}} hours. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{business_platform_name}} - TEXT {{code_validity_time}} - NUMBER

7.OTP with type of code type

Template ID

82ba31a3-db42-4e87-82e8-33fa92b9e5ed

English Copy

Your {{pin_type}} code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{pin_type}} - TEXT

8.OTP with details on OTP action/platform

Template ID

210ee8a9-1ed5-43cd-96e4-65bba311ab40

English Copy

Your one-time password for {{business_platform_action_name}} is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{business_platform_action_name}} - TEXT

9.OTP with business/platform name & code reason

Template ID

be56d97b-2a33-4c89-ac5f-f555a2c827d9

English Copy

{{business_platform_name}}: Your code is {{pin}}. You got this code because {{code_reason}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Parameters and Validations

{{pin}} - TEXT {{business_platform_name}} - TEXT {{code_reason}} - TEXT

Receive Viber message

Parameters

message_id:

The ID of the message whose status you want to get (for the last 30 days)

Values

message_id:

The ID of the message whose status you want to get (for the last 30 days)

status:

Current Viber message status

Receive bulk Viber messages

The number of verified messages is no more than 200 in one request.

Parameters

message_id:

The ID of the message whose status you want to get (for the last 30 days)

Values

message_id:

The ID of the message whose status you want to get (for the last 30 days)

status:

Current Viber message status

Callback

The callback will be returned to the URL specified when sending the message in the parameter callback_url

Values

message_id:

The ID of the message

status:

Current Viber message status

reject_code:

code returned by Viber when rejecting a message:

1 - Internal server error.

2 - The ID wasn’t in use for over a year/The ID was recently created and

wasn’t uploaded to the server yet.

3 - An error in the request’s structure. Could be a missing comma, brackets,

text over 1000 characters, etc.

5 - Incorrect message type. Either a non-supported type or an incorrect value.

6 - Missing mandatory parameters.

7 - Indicates a server timeout on Viber’s end.

8 - The ID was blocked by the user/The user blocked business messages

completely on their device.

9 - The destination number is not registered as a Viber user.

10 - Not an Android or iOS device with a Viber version that supports Business

Messages.

401 - The request was sent from a non-whitelisted IP for this ID/An incorrect ID

that doesn’t belong to the partner was used in the request.

13 - An error in the billing process

18 - Missing value/Incorrect value in the request for “label” parameter.

28 - The file that is being attempted to be sent is not in a supported format for

this feature.

29 - The name of the file is more than the maximum 25 characters.

30 - In case the thumbnail URL is compiled of more than 1000 characters.

38 - The provided template ID is not found (for OTP)

39 - Template variables did not pass the server validation (for OTP)

40 - One of the List messages parameters failed validation.

41 - One of the Carousel messages parameters failed validation.

matching_template_id:

ID issued by Viber when registering a template. If the parameter is present and the parameter value is empty, it means the message does not match any of the registered templates and has been re-rated from transactional to promotional message on the Viber side.

Viber messages statuses

Name
Status code

sent

0

delivered

1

error

2

rejected

3

undelivered

4

pending

5

seen

6

unknown

20

Errors

Name
Too Many Requests

message

Rate limit exceeded

code

0

status

429

Name
Empty parameter or parameter validation error

message

Invalid Parameter: <param>

code

1

status

400

param:

source_addr more than 20 chars

destination_addrr more than 20 chars

wrong viber user account

source_type is wrong

source_type or message_type is wrong

source_type is wrong, because the account is another type

message_type is wrong

empty text

text more than 1000 chars

transaction message error - not empty image, button_caption or button_action

message_type is wrong - not empty image, button_caption or button_action

message_type is wrong - empty image, button_caption or button_action

message_type is wrong - empty button_caption or button_action

image is not url

image url wrong scheme

image not valid type

image is not valid

image size is more than 800x800

button_action is empty

button_caption is empty

button_caption or button_action is empty

image or button_action is empty

image or button_caption is empty

callback_url is not url

callback_url url wrong scheme

button_action is not url

button_action url wrong scheme

button_action more than 30 chars

message_id <message_id> is not accepted for you

file_url is not url

file_url wrong scheme

file_url contains an invalid file type or extension, possible file extensions to send: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

button_caption is not applicable with file_url

button_action is not applicable with file_url

image is not applicable with file_url

wrong message type for file_url

file_url is not applicable in this context

Name
Internal server error

message

The server encountered an unexpected condition which prevented it from fulfilling the request

code

2

status

500

Name
Topup balance is required

message

Sender balance is empty

code

3

status

402

Name
Duplicate error

message

Duplicate Viber message detected

code

4

status

400

Name
Message Template error

message

The message does not match any template

code

5

status

400

Name
Authorization error

message

Unauthorized

code

6

status

401

Viber example

PreviousSMS APINextWhatsApp Business API

Last updated