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); Надіслати Вайбер повідомлення
Параметри
source_addr:
от 3 до 20 символів - from whom the message
destination_addr:
от 11 до 20 цифр - to whom the message
message_type (Type of message sent):
6 - тільки текст (для основного пристрою)
225 - тільки текст (для всіх пристроїв)
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
1701 - транзакційний шаблонный текст (для основного пристрою). Через випуск нового API для шаблонів у Viber, тип 301 (шаблонний транзакційний текст для основних пристроїв) незабаром буде застарілий.
1702 - транзакційний шаблонный текст (для всіх пристроїв). Через випуск нового API для шаблонів у Viber, тип 304 (шаблонний транзакційний текст для усіх пристроїв) незабаром буде застарілий.
801 - список (для всіх пристроїв)
901 - карусель (для всіх пристроїв)
text:
до 1000 символів - текст Viber повідомлення
image (Правильна URL-адреса із зображенням для рекламного повідомлення із заголовком кнопки та дією кнопки):
jpg or jpeg (тип mime — зображення/jpeg), максимальна роздільна здатність 800x800 пікселів
png (тип mime — image/png), максимальна роздільна здатність 800x800 пікселів
gif (тип mime — image/gif), максимальна роздільна здатність 800x800 пікселів
image_action (опціонально):
Правильна URL-адреса для переходу під час натискання зображення. Вказує окрему URL-адресу для кліків на зображення. Якщо цей параметр пропустити, дія кліку буде використана URL-адреса, зазначена у стандартному параметрі button_action.
image_format (опціонально для Анімованого GIF):
gif — Вмикає анімацію для файлів .gif (потрібно для анімованого перегляду).
img — Стандартна обробка статичних зображень (поведінка за замовчуванням, якщо параметр image_format пропущено).
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 Мб.
carousel:
Тип повідомлення дозволяє компаніям надсилати одне повідомлення, що містить текст і кілька розділів (елементів), що налаштовуються, кожен з яких демонструє різні продукти або послуги. Тип повідомлення дозволяє представляти від 2 до 5 окремих елементів. Кожен елемент каруселі містить зображення, короткий опис і пропонує до 2 кнопок, що налаштовуються. Усі елементи в каруселі можуть мати різні набори кнопок.
items: from 2 to 5 carousel items.
title (Mandatory) - Текст назви елемента. Від 2 до 38 символів UTF-8.
imageUrl (Mandatory) - Очікувані формати - PNG, JPEG, jpg. Рекомендований розмір: 215x185
primaryButton (Mandatory) - Містить набір основних параметрів кнопки.
secondaryButton (Optional) - Містить набір параметрів вторинної кнопки.
label (Mandatory) - Параметр кнопки. Текст, який відображатиметься на кнопці дії. До 10 символів UTF-8 всередині primaryButton. До 12 символів UTF-8 всередині secondaryButton.
actionUrl (Mandatory) - Параметр кнопки. URL-адреса, на яку перенаправляються користувачі, або дія, яка виконується під час натискання кнопки дії або торкання зображення.
survey:
Списки повідомлень надають можливість представити користувачам запитання та 2-5 відповідей, з яких вони зможуть вибрати одну. Щойно користувач вибере варіант, він буде виділений як вибраний. Відповідний текст варіанта буде надіслано користувачем до ділового чату, що ініціює зворотний виклик користувача на URL-адресу повідомлення, надану менеджеру та встановлену в налаштуваннях вашого облікового запису. Після вибору користувач зможе змінити свій вибір. Після зміни вибору, від імені користувача буде надіслано додаткове повідомлення в чаті, а додатковий зворотний виклик буде надіслано на URL-адресу повідомлення, надану менеджеру та встановлену в налаштуваннях вашого облікового запису.
Щоб використовувати цей тип повідомлення, переконайтеся, що у вашому бізнес-акаунті налаштовано значення URL-адреси повідомлення.
list_message_ui_type: (Необов’язково) – Визначає візуальний стиль опцій: 1 – Перемикачі (застарілі): Класичний стиль вибору списку. 2 – Кнопки (нові): Сучасне горизонтальне розташування кнопок Резервний варіант – 1, якщо параметр не вказано.
options: від 2 до 5 елементів списку.
текст (обов’язково) – до 85 символів UTF-8.
tracking_data (обов’язково) – обов’язково для типу повідомлення «Список». Дані для відстеження надісланого повідомлення.
options (обов’язково) – кількість опцій може бути від 2 до 5.
option text (обов’язково) – до 50 символів UTF-8 на опцію.
Підтримка GIF
Ця функція підтримується на пристроях з Viber версії 28.1 і вище. Повідомлення із зображеннями тепер підтримують анімований формат GIF. За замовчуванням всі надіслані зображення обробляються як статичні. Щоб відобразити анімований GIF, потрібно явно передати параметр image_format у запиті.
Параметр: "image_format" (опціональний) Можливі значення: gif — Вмикає анімацію для файлів .gif (потрібно для анімованого перегляду). img — Стандартна обробка статичних зображень (поведінка за замовчуванням, якщо параметр пропущено).
Response:
Значення:
message_id:
Ідентифікатор надісланого повідомлення
Callback відповіді користувача для повідомлення зі списку розсилки:
Текстова відповідь із зазначенням вибору користувача буде надіслано на URL-адресу, надану менеджеру та встановлену в налаштуваннях вашого облікового запису, разом з інформацією для відстеження, наданою в запиті:
Повідомлення з підтвердженням (OTP)
Шаблонне повідомлення – це попередньо визначене повідомлення, що зберігається на стороні Viber, яке дозволяє відправнику визначити певні значення під час надсилання повідомлення. Повідомлення підтвердження Viber – це нові типи повідомлень, призначені для надсилання одноразових паролів (OTP) за допомогою попередньо затверджених та розроблених шаблонів.
Шаблони, описані в розділі «Попередньо визначені шаблони OTP», доступні для всіх сервісів за замовчуванням. На відміну від нашої логіки шаблонів регулярних виразів, немає потреби надсилати шаблон для кожного сервісу окремо, вони вже зберігаються на нашому боці.
Шаблонне повідомлення має попередньо визначену копію, яка містить попередньо визначені змінні, які можуть бути визначені для зберігання запитуваного значення відправником. Змінні є специфічними та визначеними для кожного шаблону і будуть перевірені відповідно до конкретних обмежень кожної змінної. Приклад структури шаблонного повідомлення: Your code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it. У цьому випадку відправник може визначити значення PIN-коду під час надсилання повідомлення. Наприклад, якщо відправник визначить PIN-код як 123456, повідомлення, яке буде показано користувачеві, буде таким: Your code is 123456. Please don't share your code with ANYONE. We'll never call or message you and ask for it.
Додаткові параметри для OTP
message_type: Обов'язкове. 701 - шаблон повідомлення, надісилається лише на основний прилад 702 - шаблон повідомлення, надісилається лише на усі прилади
template_id: Обов'язкове. Попередньо визначений код шаблону для надсилання.
template_params: Обов'язкове. Діапазон змінних, специфічних для кожного шаблону. Для шаблонів та опису можливих значень. Кожен шаблон містить різний набір параметрів, які будуть перевірені за запитом.
template_lang: Опціональне - якщо не вказано, значенням за замовчуванням буде мова пристрою. Якщо мова пристрою не підтримується, копія буде представлена англійською мовою. Список локалізацій
Попередньо визначені шаблони 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
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
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
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
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
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
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
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
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
Список локалізацій
Параметр шаблону локалізації буде відповідати кодуванню ISO 639-1, представленому дволітерним кодом, як показано нижче:
English
en
Arabic
ar
Bulgarian
bg
Croatian
hr
Czech
cs
Danish
da
German
de
Greek
el
Spanish
es
Finnish
fi
French
fr
Hebrew
he
Burmese
my
Hungarian
hu
Indonesian
id
Italian
it
Japanese
ja
Norwegian
nb
Dutch
nl
Polish
pl
Portuguese (Portugal)
pt
Portuguese (Brazil)
br
Romanian
ro
Russian
ru
Slovak
sk
Serbian
sr
Swedish
sv
Thai
th
Turkish
tr
Ukrainian
uk
Vietnamese
vi
Persian
fa
Belarusian
be
Отримати Вайбер повідомлення
Параметри
message_id:
ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)
Значення
message_id:
ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)
status:
Поточний статус повідомлення Viber
Отримати Вайбер повідомлення масово
Кількість повідомлень, що перевіряються, — не більше 200 в одному запиті.
Параметри
message_id:
ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)
Значення
message_id:
ID повідомлення, статус якого ви бажаєте отримати (за останні 30 днів)
status:
Поточний статус повідомлення Viber
Отримання Callback
Зворотний виклик буде повернено на URL, вказаний під час надсилання повідомлення в callback_url
Значения:
message_id:
ID повідомлення
status:
Поточний статус повідомлення Viber
reject_code:
код, що повертається Viber при відхиленні повідомлення:
1 – Внутрішня помилка сервера.
2 - Ідентифікатор не використовувався більше року/Ідентифікатор нещодавно був створений і ще не завантажений на сервер.
3 – Помилка у структурі запиту. Можливо, пропущена кома, дужки, текст довжиною понад 1000 символів тощо.
5 - Неправильний тип повідомлення. Або непідтримуваний тип, чи неправильне значення.
6 - Відсутні обов'язкові параметри.
7 - Вказує на тайм-аут сервера на боці Viber.
8 - Ідентифікатор був заблокований користувачем/Користувач повністю заблокував ділові повідомлення на своєму пристрої.
9 - Номер призначення не зареєстрований як Viber.
10 - Пристрій не Android або iOS з версією Viber, яка підтримує ділові повідомлення.
401 - Запит було надіслано з IP-адреси, що не входить до білого списку для цього ідентифікатора/У запиті використано невірний ідентифікатор, що не належить партнеру.
13 - Помилка у процесі виставлення рахунку
18 - Відсутнє значення/Неправильне значення у запиті параметра "label".
28 - Файл, який намагаються надіслати, не має підтримуваного формату для цієї функції.
29 - Ім'я файлу перевищує максимально допустимі 25 символів.
30 - Якщо URL-адреса мініатюри складається з більш ніж 1000 символів.
40 – Один із параметрів повідомлень списку не пройшов перевірку.
41 – Один із параметрів повідомлень каруселі не пройшов перевірку.
matching_template_id:
ID, виданий Viber під час реєстрації шаблону. Якщо параметр є і значення параметра порожнє, це означає, що повідомлення не відповідає жодному із зареєстрованих шаблонів і було перетарифіковано з транзакційного на рекламне повідомлення на стороні Viber.
Статуси повідомлень Вайбер
delivered
1
error
2
rejected
3
undelivered
4
pending
5
seen
6
unknown
20
Помилки:
message
Rate limit exceeded
code
0
status
429
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
message
The server encountered an unexpected condition which prevented it from fulfilling the request
code
2
status
500
message
Sender balance is empty
code
3
status
402
message
Duplicate Viber message detected
code
4
status
400
message
The message does not match any template
code
5
status
400
message
Unauthorized
code
6
status
401
Приклади:
Last updated