VIBER API

DecisionTelecom Viber API дозволяє надсилати та отримувати ділові повідомлення Viber у будь-яку країну світу та з неї через API. Кожне повідомлення ідентифікується унікальним випадковим ідентифікатором, тому користувачі можуть перевірити статус повідомлення, використовуючи задану кінцеву точку.

Viber API використовує HTTPS з ключем доступу, який використовується як авторизація API. Корисні дані запитів та відповідей форматуються як JSON за допомогою кодування UTF-8.

API Авторизація - Базовий ключ доступу Base64.

Щоб отримати ключ API, будь ласка, зв'яжіться з вашим менеджером по роботі з клієнтами.

Авторизація

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);

Надіслати Вайбер повідомлення

https://web.it-decision.com/v1/api/send-viber
Example for text-image-button messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,							
	"message_type":108, 									
	"text":"Message content", 										
	"image":"https://yourdomain.com/images/image.jpg", 		
	"button_caption":"Join Us", 							
	"button_action":"https://yourdomain.com/join-us",   	
	"source_type":1, 										
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":3600
}
​
Example for promotional text messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,	
	"message_type":106, 								
	"text":"Message content",
	"source_type":1, 	
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":3600
}

Example for send file:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,						
	"message_type":222, 
	"file_url":" https://yourdomain.com/files/custom.pdf ",	
	"source_type":1, 								
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":180
}
​
Example for transactional template messages:
{
	"source_addr": "Custom Company", 						
	"destination_addr": 8882222200,	
	"message_type":304, 
	"text":"Message content",							
	"source_type":2,
	"callback_url":"https://yourdomain.com/viber-callback",
	"validity_period":180
}

Параметри

source_addr:

от 3 до 20 символів - from whom the message

destination_addr:

от 11 до 20 цифр - to whom the message

message_type (Type of message sent):

6 - тільки текст (для основного пристрою)

106 - тільки текст (для всіх пристроїв)

8 - текст+зображення+кнопка (для основного пристрою)

108 - текст+зображення+кнопка (для всіх пристроїв)

9 - кнопка текст+ (для основного пристрою)

109 - текст+кнопка (для всіх пристроїв)

222 - надіслати файл (для всіх пристроїв), підтримувані формати: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax , .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

301 - транзакційний шаблонный текст (для основного пристрою)

304 - транзакційний шаблонный текст (для всіх пристроїв)

text:

до 1000 символів - текст Viber повідомлення

image (Правильна URL-адреса із зображенням для рекламного повідомлення із заголовком кнопки та дією кнопки):

jpg or jpeg (тип mime — зображення/jpeg), максимальна роздільна здатність 800x800 пікселів

png (тип mime — image/png), максимальна роздільна здатність 800x800 пікселів

button_caption:

від 1 до 30 символів – напис на кнопці

button_action:

Правильна URL-адреса для переходу при натисканні кнопки

source_type (Процедура надсилання повідомлення):

promotion message (повідомлення може бути з текстом, зображенням, кнопкою) - 1

transactional message (текстове шаблонне повідомлення) – 2

callback_url:

Правильна URL-адреса для зворотного виклику статусу повідомлення

validity_period:

TTL (Час життя) дозволяє відправнику обмежити час життя повідомлення. У разі, якщо повідомлення не отримало статус «доставлено» до закінчення часу, повідомлення не буде списано та не буде доставлене користувачеві. Якщо TTL не було вказано (немає параметра «ttl»), Viber намагатиметься доставити повідомлення протягом 1 дня.

promotion message - хв. TTL 60 секунд макс. TTL 43200 секунд (12 годин)

transactional message – хв. TTL 60 секунд макс. TTL 43200 секунд(12 годин)

file_url:

Параметр тільки для типу повідомлень 222 має містити коректний URL документа. Розширення файлів, дозволені до відправки: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx Файл повинен містити розширення та його назва не може перевищувати 25 символів. Розмір файлу не повинен перевищувати 200 Мб.

Response:

{
    "message_id":4291235
}

Значення:

message_id:

Ідентифікатор надісланого повідомлення

Отримати Вайбер повідомлення

 https://web.it-decision.com/v1/api/receive-viber
{
    "message_id":4291235
}

Параметри

message_id:

ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)

{
    "message_id":4291235, 			
    "status":1, 					
}

Значення

message_id:

ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)

status:

Поточний статус повідомлення Viber

Отримати Вайбер повідомлення масово

Кількість повідомлень, що перевіряються, — не більше 200 в одному запиті.

 https://web.it-decision.com/v1/api/receive-bulk-viber
[
     {"message_id":11017894},
     {"message_id":11017879},
     {"message_id":11017865},
     {"message_id": ... n}
]

Параметри

message_id:

ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)

{
    "11017894": {
        "message_id": 11017894,
        "status": 1
    },
    "11017879": {
        "message_id": 11017879,
        "status": 1
    },
    "11017865": {
        "name": "Empty parameter or parameter validation error",
        "message": "Invalid Parameter: message_id 11017865 is not accepted for you",
        "code": 1,
        "status": 400
    }
}

Значення

message_id:

ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)

status:

Поточний статус повідомлення Viber

Отримання Callback

Зворотний виклик буде повернено на URL, вказаний під час надсилання повідомлення в callback_url

{
    "message_id":4291235,                                 
    "status":1                                                                       
}

If the status is 3 (Rejected) then the additional parameter reject_code will be returned:
{
    "message_id":4291235,                                 
    "status":1,         
    "reject_code":9                                              
}

If the message type being sent is 301 or 304 (template transactional text) then the additional parameter matching_template_id will be returned
{
    "message_id":4291235,                                 
    "status":1,         
    "matching_template_id":11079289                                                            
}

Значения:

message_id:

ID повідомлення

status:

Поточний статус повідомлення Viber

reject_code:

код, що повертається Viber при відхиленні повідомлення:

1 – Внутрішня помилка сервера.

2 - Ідентифікатор не використовувався більше року/Ідентифікатор нещодавно був створений і ще не завантажений на сервер.

3 – Помилка у структурі запиту. Можливо, пропущена кома, дужки, текст довжиною понад 1000 символів тощо.

5 - Неправильний тип повідомлення. Або непідтримуваний тип, чи неправильне значення.

6 - Відсутні обов'язкові параметри.

7 - Вказує на тайм-аут сервера на боці Viber.

8 - Ідентифікатор був заблокований користувачем/Користувач повністю заблокував ділові повідомлення на своєму пристрої.

9 - Номер призначення не зареєстрований як Viber.

10 - Пристрій не Android або iOS з версією Viber, яка підтримує ділові повідомлення.

11 - Запит було надіслано з IP-адреси, що не входить до білого списку для цього ідентифікатора/У запиті використано невірний ідентифікатор, що не належить партнеру.

13 - Помилка у процесі виставлення рахунку

18 - Відсутнє значення/Неправильне значення у запиті параметра "label".

28 - Файл, який намагаються надіслати, не має підтримуваного формату для цієї функції.

29 - Ім'я файлу перевищує максимально допустимі 25 символів.

30 - Якщо URL-адреса мініатюри складається з більш ніж 1000 символів.

matching_template_id:

ID, виданий Viber під час реєстрації шаблону. Якщо параметр є і значення параметра порожнє, це означає, що повідомлення не відповідає жодному із зареєстрованих шаблонів і було перетарифіковано з транзакційного на рекламне повідомлення на стороні Viber.

Статуси повідомлень Вайбер

sent
0

delivered

1

error

2

rejected

3

undelivered

4

pending

5

seen

6

unknown

20

Помилки:

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:

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

Приклади:

curl --location --request POST 'https://web.it-decision.com/v1/api/send-viber' \
--header 'Authorization: Basic api key' \
--header 'Content-Type: application/json' \
--data-raw '{"source_addr": "Custom Company", "destination_addr": 8882222200,"message_type":106,"text":"Message content","image":"https://yourdomain.com/images/image.jpg","button_caption":"Join Us","button_action":"https://yourdomain.com/join-us","source_type":1,"callback_url":"https://yourdomain.com/viber-callback","validity_period":3600}'
PreviousSMS APINextWhatsApp Business API

Last updated