FAQ API Direct Hub

HTTP 200 означає, що Direct Hub прийняв повідомлення. У відповіді приходить { id, status }, де status = WaitingToSend.

• HTTP 200 ніколи не містить відмови у відправленні. Відмова Viber приходить пізніше, вебхуком MessageSendError.
• Помилка не може повернутися з HTTP 200.
• Помилки, виявлені до прийняття повідомлення, повертаються кодами 4xx/5xx у форматі application/problem+json з полями title, status, detail, traceId (див. HTTP-помилки під час відправлення).

Кожному етапу відповідає таке:

Статус у відповіді на відправлення — WaitingToSend. Далі приходять події:

• До події MessageDelivered повідомлення не слід показувати як доставлене.
• MessageDelivered може прийти кілька разів, якщо в отримувача Viber встановлено на кількох пристроях.

Строк доставки — 10 хвилин. Повідомлення, не доставлене за цей час, отримує MessageExpired.

• коди Viber — BadRecipient, RecipientNotRegistered, RecipientBlockedMessages, DoesNotSupportDevice, AttemptExceededSession, BadParameters та інші;
• мережеві збої під час передавання у Viber — Network error has occurred., Timeout has occurred., Unsuccessful status code..

• відмови за отримувачем (немає Viber, блокування, неправильний номер) повторювати безглуздо;
• після мережевого збою під час передавання у Viber повідомлення могло все ж піти, тому повтор із новим ключем може дати дубль.

Наразі API не дає змоги:

• отримати статус за messageId;
• знайти повідомлення за trackingData;
• вивантажити історію за період;
• отримати список поточних сесій і підписок.

Стан потрібно накопичувати у себе за вебхуками. Події, пропущені під час недоступності вашого сервера, повторно не доставляються (див. доставку вебхуків).

Дізнатися поточний статус конкретного повідомлення можна одним способом: повторити запит на відправлення з тим самим idempotencyKey (див. Ідемпотентність і повтори). Нове повідомлення при цьому не створюється.

• Ключ обов'язковий для всіх ендпоінтів відправлення. Без ключа або з порожнім GUID запит відхиляється з кодом 400.
• Ключ унікальний у межах бізнес-номера, до якого прив'язано API-токен, і зберігається стільки ж, скільки саме повідомлення.

Повторний запит із тим самим ключем повертає HTTP 200 з тим самим id і поточним status першого повідомлення, а також заголовок Idempotent-Replayed: true. Нове повідомлення не створюється, оплата повторно не списується, сесійний ліміт не витрачається.

Ключ шукається серед повідомлень того самого бізнес-номера, тобто того самого API-токена. Якщо повідомлення з таким ключем знайдено, порівнюється тільки отримувач:

• отримувач той самий — запит вважається повтором: HTTP 200, попередній id, поточний status і заголовок Idempotent-Replayed: true;
• отримувач інший — відповідь 422 «Idempotency key already used».

Інші поля запиту (текст, шаблон і його параметри, зображення або файл, trackingData) не порівнюються. Запит із тим самим ключем і тим самим отримувачем, але з іншим текстом, поверне вже створене повідомлення, а нове не буде відправлено. Тому для кожного нового повідомлення використовуйте новий ключ.

Ні. Повтор не відправляє повідомлення заново, навіть якщо перше завершилося помилкою: ключ означає «те саме повідомлення». Щоб відправити заново, використайте новий ключ.

Якщо перший запит було відхилено до створення повідомлення (коди 400, 402, 403, 503), повідомлення з цим ключем немає, і повтор із ним виконується як нова спроба.

Той самий ключ з іншим отримувачем відхиляється з кодом 422.

Одночасні запити з одним ключем безпечні: буде створено одне повідомлення.

Якщо перший запит із цим ключем ще виконується довше 2 секунд (наприклад, завантажується великий файл), повтор отримає 409. Повторіть запит через кілька секунд: прийде результат першого запиту із заголовком Idempotent-Replayed: true.

Генеруйте новий ключ для кожного нового повідомлення і повторюйте запит із тим самим ключем, якщо відповідь не отримано (таймаут, обрив з'єднання) або отримано 503.

Рекомендовані інтервали повторів — див. З якими інтервалами повторювати запити?, а дії для кожного коду — у таблиці HTTP-помилок.

+380XXXXXXXXX, із плюсом. Наразі підтримуються лише номери України.

У тому вигляді, в якому його передає Viber, із плюсом.

Ні, такої попередньої перевірки немає.

• неправильний формат номера — одразу відповідь 400;
• номер некоректний за даними Viber — MessageSendError, error = "BadRecipient";
• в отримувача немає Viber — "RecipientNotRegistered";
• отримувач заблокував бізнес-акаунт — "RecipientBlockedMessages";
• пристрій не підтримує такий тип повідомлення — "DoesNotSupportDevice".

Ліміти діють на IP-адресу клієнта: для IPv4 — на конкретну адресу, для IPv6 — на підмережу /64. Методи поділено на групи, і в кожної групи свій лічильник:

• Рахунок ведеться у фіксованому вікні: воно починається з першого запиту і триває хвилину. Сплеск усередині вікна допустимий, доки не вичерпано ліміт.
• Окремого обмеження на кількість паралельних запитів немає.

Одразу повертається HTTP 429 із заголовком Retry-After (через скільки секунд відкриється нове вікно). Запит не виконується і не тарифікується.

• після 429 — чекати стільки секунд, скільки вказано в Retry-After;
• після 503 і мережевих помилок — експоненційна затримка, наприклад 1, 2, 4, 8 секунд, із тим самим idempotencyKey.

Використовуйте розсилки: вони не витрачають ліміт на відправлення повідомлень.

Обмеження Bot API до Direct Hub не застосовуються. Діють такі:

Так. Сесію відкриває будь-яке вхідне повідомлення від користувача, зокрема відповідь на розсилку.

Ні. Вікно фіксоване: 24 години від першого вхідного. Нове вхідне не продовжує його і не скидає ліміт у 60, але знімає паузу після 10 вихідних поспіль без відповіді.

Сесійні відправлення (текст, зображення, файл), прийняті Direct Hub. Місце в ліміті витрачається в момент прийняття і не повертається, навіть якщо Viber потім відмовить. Платні повідомлення та повтори з тим самим idempotencyKey у ліміт не входять.

API для цього немає. Залишок рахується так: 60 мінус кількість прийнятих сесійних відправлень з моменту події SessionOpened.

• За часом: сесія закривається через 24 години після відкриття. Подія SessionClosed (Expired) може прийти із затримкою до кількох хвилин, але відправлення в сесію, що минула, відхиляється одразу.
• За кількістю: сесія закривається одразу на 60-му повідомленні, приходить SessionClosed (MessageLimitReached).

Причини закриття сесії (closeReason):

• Expired — минули 24 години;
• MessageLimitReached — вичерпано ліміт у 60 повідомлень;
• ViberRejected — Viber повідомив, що сесію на його боці вже закрито.

Проходять рівно 60. Решта отримують 400 або йдуть платно, якщо ввімкнено автоперехід (див. автоматичний перехід до платного відправлення).

Viber може відхилити повідомлення. Тоді прийдуть MessageSendError (AttemptExceededSession) і SessionClosed (ViberRejected). Відхилене повідомлення не тарифікується.

Автоперехід вмикається прапорцем у запиті або налаштуванням номера. Для нових номерів налаштування номера ввімкнене за замовчуванням. Тому false або відсутність прапорця самі по собі не забороняють платне відправлення. Щоб його виключити, зверніться до нас із проханням вимкнути налаштування на вашому номері.

Автоперехід спрацьовує лише тоді, коли безкоштовне відправлення неможливе, зокрема під час паузи через 10 повідомлень без відповіді. За інших помилок він не спрацьовує.

Повертається 400:

• No active Viber session — сесії немає, її закрито або вичерпано ліміт;
• Viber session paused due to unanswered outbound messages limit — відправлено 10 повідомлень поспіль без відповіді.

В обох випадках нічого не списується.

Для зображень є. /api/message/session/image приймає той самий прапорець fallbackToPromotional, і на нього так само діє налаштування номера. Без сесії зображення йде платним промоповідомленням «лише зображення» за тарифом цього типу.

Для файлів немає: у Viber немає промоповідомлення з файлом. Без сесії /api/message/session/file повертає 400 незалежно від налаштування номера.

Вебхук — єдиний механізм отримання подій.

Direct Hub чекає на відповідь 2xx 10 секунд і робить одну спробу без повторів. Події, пропущені під час недоступності вашого сервера, повторно не доставляються.

Кожен вебхук — це POST із JSON-тілом і двома заголовками:

Як перевірити:

1. Візьміть тіло запиту як є, у байтах, до розбору JSON.
2. Декодуйте секрет вебхука з hex: 64 hex-символи дають 32 байти. Ці байти і є ключем HMAC.
3. Обчисліть HMAC-SHA256 від тіла цим ключем, переведіть результат у hex у нижньому регістрі й додайте префікс sha256=.
4. Порівняйте результат із заголовком X-Webhook-Signature функцією порівняння за сталий час. Якщо значення не збігаються, відхиліть запит і не обробляйте подію.

Найчастіша помилка — використати як ключ сам рядок секрету. Ключ HMAC — це байти, отримані декодуванням hex-секрету. З рядком як ключем підпис не збігатиметься ніколи.

Інші причини розбіжності:

• підпис рахують від JSON, який повторно серіалізували після розбору: порядок полів, пробіли або екранування змінюються, і підпис уже не збігається. Підпис рахується тільки від сирого тіла;
• ваш фреймворк або проксі змінив тіло до вашого коду (перекодування, обрізання пробілів).

Node.js

const crypto = require('crypto');

// rawBody — Buffer із сирим тілом запиту (наприклад, express.raw({ type: 'application/json' }))
function verifyWebhook(rawBody, signatureHeader, secretHex) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', Buffer.from(secretHex, 'hex'))
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hashlib
import hmac

def verify_webhook(raw_body: bytes, signature_header: str, secret_hex: str) -> bool:
    expected = "sha256=" + hmac.new(bytes.fromhex(secret_hex), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

C#

using System.Security.Cryptography;
using System.Text;

static bool VerifyWebhook(byte[] rawBody, string? signatureHeader, string secretHex)
{
    var hash = HMACSHA256.HashData(Convert.FromHexString(secretHex), rawBody);
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.ASCII.GetBytes(expected),
        Encoding.ASCII.GetBytes(signatureHeader ?? ""));
}

PHP

// $rawBody = file_get_contents('php://input');
// $signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
function verifyWebhook(string $rawBody, string $signatureHeader, string $secretHex): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, hex2bin($secretHex));
    return hash_equals($expected, $signatureHeader);
}

• Секрет генерується під час реєстрації вебхука і повертається один раз, у полі secret відповіді на створення. Це рядок із 64 hex-символів (32 випадкові байти).
• Повторно отримати секрет не можна: у списку вебхуків і в інших відповідях його немає. Збережіть секрет одразу після створення.
• Секрет не змінюється, коли ви змінюєте URL або типи подій вебхука.
• Якщо секрет втрачено або скомпрометовано, видаліть вебхук і зареєструйте новий. Новий вебхук отримає новий секрет.

Як перевіряти підпис — див. Як перевірити підпис вебхука?

Користувач може надіслати фото, відео або файл. У вебхуку NewMessage приходять поля fileUrl і fileName. Посилання веде на сервер Viber. За документацією Viber файл зберігається до 7 днів, після цього недоступний, і відновити його не можна.

Рекомендуємо завантажувати файл одразу після отримання події.