For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

Список локалізацій

Параметр шаблону локалізації буде відповідати кодуванню ISO 639-1, представленому дволітерним кодом, як показано нижче:

Language
template_lang (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.

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

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

Приклади:

Last updated