UMIND Connect API забезпечує надсилання SMS, повідомлень через Telegram- і Viber-ботів, одноразових кодів та автоматизовані дзвінки. Довідник містить параметри методів, формати відповідей і приклади інтеграції.
Базова адреса APIhttps://connect.umind.group/api/
Початок інтеграції
Створіть API-токен
У кабінеті UMIND Connect відкрийте «API-токени», виберіть «Створити токен» і вкажіть назву інтеграції. Повне значення відображається один раз. Збережіть токен у змінній середовища UMIND_API_TOKEN на сервері інтеграції.
Перевірте авторизацію
Виконайте запит auth/me. Успішна відповідь містить профіль компанії, баланс і доступні альфаімена. Метод не виконує платних відправлень.
Підключіть потрібний канал
Сформуйте запит за специфікацією методу. Перевірте HTTP-статус і поле success. Зберігайте ідентифікатори відправлень для зіставлення зі статистикою. Для групового SMS перевіряйте також messages[].state.
API-токен — рядок із 64 латинських літер і цифр. Він підтримує всі методи цього довідника; доступність платних каналів визначається налаштуваннями компанії.
Параметр user_id для вибору компанії не передається. Сесія кабінету, cookie та X-CSRF-Token для Bearer-запитів не потрібні.
Зберігайте токен у серверному сховищі секретів. Клієнтські застосунки мають звертатися до API через ваш сервер.
Для telegram/bot і viber/bot токен відповідного бота передається окремо в JSON-полі token. Він не замінює API-токен UMIND.
У разі втрати токена створіть новий. Скомпрометований токен необхідно відкликати в кабінеті.
Клієнтський застосунок→Сервер інтеграції→UMIND Connect API
Формат запитів і відповідей
Параметр протоколу
Вимоги
Транспорт
HTTPS. Кодування запитів і текстових відповідей — UTF-8.
HTTP-метод
Усі методи підтримують POST. Для методів читання також доступний GET, зазначений у специфікації.
Тіло запиту
JSON-об’єкт. Для POST без параметрів передавайте {}. Максимальний розмір тіла — 1 048 576 байтів; окремі канали мають додаткові обмеження.
Заголовки
Authorization: Bearer … і Content-Type: application/json обов’язкові, зокрема для GET. Accept: application/json або application/pdf для PDF-звіту.
Одержувач
Телефонні канали приймають українські номери рядками, рекомендований формат +380671234567. Для sms/bulk список передається у recipients; для одиночного надсилання — номер у to. Telegram-бот використовує chat_id; Viber-бот — ID підписника.
OTP
Передавайте код рядком для збереження початкових нулів: "012345". Тип поверненого коду зазначено в описі відповідного методу.
Успішна відповідь
HTTP 2xx та success: true. Для sms/bulk додатково перевіряйте стан кожного елемента messages. Для PDF — HTTP 200 і Content-Type: application/pdf.
Помилка
success: false та об’єкт error з полями code і message. Додаткові поля залежать від каналу.
Ідентифікатори
id ідентифікує запис UMIND у межах каналу. Зберігайте його разом із method. Для sms/bulk використовуйте messages[].id разом зі stat_method. Для Telegram- і Viber-ботів message_id — ідентифікатор повідомлення відповідної платформи; для Viber завжди рядок.
Періоди й суми
Дати: YYYY-MM-DD, обидві межі включно. Часові мітки наведено в часовому поясі сервісу без UTC-зміщення; пояс слід узгодити під час інтеграції. Грошові суми — у гривнях.
Для GET використовуйте query string, наприклад ?start=2026-09-01&finish=2026-09-22&methods[]=viber%2Fbot. Масиви та порожній список methods: [] зручно передавати через POST із JSON.
Методи надсилання виконують реальні операції з тарифікацією за умовами компанії. Режими sandbox і dry-run не передбачені. Значення одержувачів, токенів, URL і вартості у прикладах ілюстративні.
Методи API
Для кожного методу наведено параметри, умови їх обов’язковості, приклад запиту, структуру відповіді та правила обробки результату.
Виберіть метод і мову програмування. Приклади містять авторизацію, тайм-аут та перевірку відповіді; для stat/pdf — збереження PDF-файлу. JavaScript призначений для серверного середовища Node.js.
POST /api/sms/single · cURL
# Задайте UMIND_API_TOKEN у середовищі вашого сервера.
# Збережіть тіло запиту у request.json:
cat > request.json <<'JSON'
{
"to": "+380671234567",
"alphaname": "MyBrand",
"text": "Ваше замовлення готове до отримання.",
"lifetime": 3600
}
JSON
# Без автоматичного повтору або переходу за redirect.
curl --silent --show-error --connect-timeout 10 --max-time 90 \
--request POST 'https://connect.umind.group/api/sms/single' \
--header "Authorization: Bearer ${UMIND_API_TOKEN:?Set UMIND_API_TOKEN}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-binary @request.json \
--dump-header response.headers \
--output response.json \
--write-out 'HTTP %{http_code} | %{content_type}\n'
# Перевірте HTTP-статус вище та success у response.json.
cat response.json
Для sms/bulk перевірки success недостатньо: проаналізуйте messages[].state для всіх одержувачів і збережіть прийняті, відхилені та невизначені результати окремо. Формат наведено в специфікації методу.
API-токен читається зі змінної середовища UMIND_API_TOKEN. Значення YOUR_… та дані одержувачів у прикладах замініть власними; токени ботів у робочій інтеграції також завантажуйте зі сховища секретів. Не записуйте токени, OTP і персональні дані у загальнодоступні журнали.
Надсилання повідомлень і кодів
Методи одиночного та групового надсилання. Доступність каналів і вартість визначаються налаштуваннями компанії.
Надсилає однаковий текст групі від 1 до 1000 українських номерів. Відправлення об’єднуються в кампанію; кожен одержувач має окремий результат і запис статистики.
Параметри запиту
Параметр
Тип
Обов’язковість
Опис
recipients
array<string>
Так
Від 1 до 1000 номерів у вхідному масиві. Рекомендований формат: +380671234567. Дублікати видаляються після нормалізації. Некоректний номер спричиняє відмову всього запиту до надсилання.
alphaname
string
Так
Підтверджене альфаім’я компанії. Регістр має збігатися з підтвердженою назвою.
text
string
Так
Непорожній текст UTF-8, до 10 000 символів, без нульового символу. Один текст для всіх одержувачів запиту. Підстановка змінних виконується на стороні інтеграції.
lifetime
integer
Ні
Строк очікування доставки: 0–86400 секунд; типово 86400. Округлюється в більший бік до повної хвилини, мінімум — 1 хвилина.
campaign_name
string
Ні
Назва нової кампанії, до 120 символів після видалення пробілів на початку й у кінці, без керувальних символів і переносів рядка. Якщо назву пропущено або передано порожній рядок, вона формується за датою та часом.
campaign_id
integer
Ні
Додатний ID наявної кампанії вашої компанії. Додає до неї наступну групу відправлень. Не передається разом із campaign_name.
Тіло POST · JSON
{
"recipients": [
"+380671234567",
"+380501234567"
],
"alphaname": "MyBrand",
"text": "Ваше замовлення готове.",
"lifetime": 3600,
"campaign_name": "Замовлення за вересень"
}
Ознака успішної обробки загальної відповіді. Результат кожного відправлення визначається через messages[].state.
method
string
Метод запиту: sms/bulk.
stat_method
string
Канал статистики: sms/single.
campaign.id
integer
ID кампанії для наступних груп і фільтра статистики.
campaign.name
string
Назва кампанії. Не входить до тексту SMS.
messages
array<object>
По одному результату для кожного унікального нормалізованого номера. Зіставляйте результати за to.
messages[].to
string
Нормалізований номер у форматі +380…
messages[].state
string
accepted, failed або uncertain. Правила обробки наведено нижче.
messages[].message
string
Опис результату для діагностики. Програмна обробка має спиратися на state і status.
messages[].id
integer
Ідентифікатор запису UMIND. Є для accepted і failed; відсутній для uncertain.
messages[].status
string
Статус відправлення: наприклад ACCEPTED або REJECTED. Відсутній для uncertain.
messages[].segments
integer
Кількість сегментів одного SMS. Є для accepted і failed; відсутня для uncertain.
messages[].price
number
Списана сума у гривнях: кількість сегментів × тариф sms/single для accepted, 0 для failed. Відсутня для uncertain.
money_spend
number
Сума messages[].price за поточний запит, із точністю до 4 знаків після коми.
Особливості використання
Вартість одного сегмента дорівнює вартості одного сегмента одиночного SMS за тарифом sms/single. Для кожного прийнятого повідомлення вартість визначається як кількість сегментів × тариф за сегмент.
HTTP 200 і success: true підтверджують обробку запиту, але не успіх усіх відправлень. Перевіряйте messages[].state для кожного номера.
Статистика зберігається в каналі sms/single. Для зіставлення використовуйте stat_method та messages[].id; для вибірки всієї кампанії — campaign.id.
Перед надсиланням перевіряється достатність балансу для всіх унікальних номерів групи з урахуванням дозволеного кредитування. Фактичне списання міститься в money_spend.
Якщо campaign_id не передано, створюється нова кампанія. Однакова campaign_name не об’єднує запити й не захищає від повторного надсилання.
При передаванні campaign_id наявність хоча б одного номера з уже записаним результатом у цій кампанії спричиняє HTTP 409 для всього запиту. Це стосується також записів зі станом failed.
Результати uncertain не створюють запису відправлення та списання в цій відповіді. Це не доводить відсутність фактичного надсилання; перед повтором необхідно уточнити результат.
Вартість і кількість сегментів
Один сегмент SMS у sms/bulk коштує стільки ж, скільки один сегмент у sms/single. Використовується тариф компанії account.tariffs["sms/single"] із відповіді auth/me. Окремої плати за створення кампанії або груповий запит немає.
Вартість одного прийнятого відправлення: segments × тариф за сегмент. Вартість групи: сума вартості прийнятих відправлень. Наприклад, за тарифу 1,25 грн два одержувачі з одним сегментом кожен коштують 2,50 грн; із двома сегментами кожен — 5,00 грн.
Кодування тексту
Односегментне SMS
Багатосегментне SMS
GSM-7
До 160 одиниць.
По 153 одиниці на сегмент.
Unicode, зокрема український текст
До 70 одиниць UTF-16.
По 67 одиниць UTF-16 на сегмент.
Для тексту довше односегментного ліміту кількість сегментів визначається діленням на 153 або 67 з округленням угору. Символи розширеного набору GSM-7, зокрема ^, {, }, €, займають дві одиниці. Символи Unicode поза основною площиною, зокрема багато emoji, займають дві одиниці UTF-16. Після персоналізації кількість сегментів слід розраховувати для кожного готового тексту.
Обробка результатів
messages[].state
Значення
Дії інтеграції
accepted
Надсилання прийнято. Є запис статистики та списання за сегменти.
Зберегти id і суму. Для результату доставки перевіряти status у статистиці.
failed
Отримано відмову. Запис збережено, price: 0.
Зафіксувати відмову та з’ясувати причину перед новим відправленням.
uncertain
Однозначного результату немає. Поля id, status, segments, price відсутні.
Зупинити автоматичні повтори для цього номера й уточнити результат. Відсутність запису не гарантує, що SMS не надіслано.
Стан accepted описує прийняття до надсилання, а не остаточний результат доставки. В одному запиті можуть бути різні результати. Зберігайте повну відповідь і зіставляйте елементи messages за нормалізованим номером to.
Приклад частково успішної відповіді
Запит містив три унікальні номери. Одне відправлення прийнято, одне відхилено, для третього результат невизначений. HTTP-статус відповіді — 200.
У першому запиті передайте campaign_name або пропустіть обидва поля кампанії. Збережіть повернений campaign.id.
Поділіть решту номерів на групи до 1000 елементів. У наступних запитах передавайте збережений campaign_id без campaign_name.
Виконуйте запити послідовно та зберігайте результат кожної групи. Для 10 000 номерів з однаковим текстом достатньо 10 запитів по 1000 номерів.
Для персоналізації згрупуйте одержувачів за однаковим готовим текстом. Передавайте ці групи в межах тієї самої кампанії; кожен номер має входити лише в одну групу.
campaign_id групує відправлення та запобігає повтору вже записаних номерів. Він не є універсальним ключем ідемпотентності. Після тайм-ауту, HTTP 502 або uncertain автоматично повторювати групу не слід.
Статистика кампанії
Для stat/get і stat/pdf передавайте methods: ["sms/single"] та campaign_id. Вибірка обмежується зазначеним періодом; запис одержувача містить його campaign_id.
Надсилає повідомлення одному підписнику Viber-бота. Підтримуються текст, зображення та клавіатура з кнопками. Для розсилки використовується окремий запит для кожного одержувача.
Параметри запиту
Параметр
Тип
Обов’язковість
Опис
to
string
Так
Ідентифікатор підписника Viber, 1–255 символів. Допустимі A–Z, a–z, 0–9, +, /, _, =, -. Числовий номер телефону не приймається. Регістр і спеціальні символи зберігаються без змін.
token
string
Так
Токен Viber-бота: 16–255 латинських літер, цифр, _ або -. Відрізняється від Bearer-токена UMIND.
sender
object
Так
Параметри відправника. Обов’язково містить name; може містити avatar.
sender.name
string
Так
Непорожня назва відправника, від 1 до 28 символів.
sender.avatar
string
Ні
HTTP/HTTPS URL аватара, до 2000 байтів.
text
string
Без photo
Текст повідомлення: 1–7000 символів. За наявності photo — підпис до 768 символів; може бути порожнім або пропущеним.
photo
string
Ні
HTTP/HTTPS URL зображення, до 2000 байтів. Шлях URL має завершуватися .jpg, .jpeg, .png або .gif. Анімовані GIF, Base64 і завантаження файлу у тілі запиту не підтримуються.
buttons
array<array<object>>
Ні
Клавіатура: масив рядків із 1–3 кнопками в кожному. Не більше 20 кнопок загалом. Формат кнопки наведено нижче.
button
object
Ні
Одна кнопка як альтернатива buttons. Одночасне передавання button і buttons не допускається.
Ідентифікатор запису UMIND Connect. Використовується разом із method.
message_id
string
Ідентифікатор повідомлення Viber.
to
string
Ідентифікатор одержувача з запиту.
Особливості використання
Для надсилання потрібні активний Viber-бот із налаштованим webhook, токен бота, ідентифікатор підписника та доступний канал viber/bot для компанії.
Поле message_id завжди повертається рядком. Не перетворюйте його на число: значення може перевищувати точність стандартних числових типів.
success: true і статус SENT підтверджують прийняття повідомлення Viber. Статистика UMIND не оновлює його до станів доставки або прочитання.
Кнопки відображаються як клавіатура Viber. url відкриває посилання; callback_data надсилає відповідь боту, яку обробляє ваш webhook.
parse_mode не підтримується. Тип повідомлення визначається за наявністю photo: зображення або текст.
Розмір сформованого повідомлення, переданого Viber, не повинен перевищувати 30 000 байтів UTF-8, включно з параметрами відправника та клавіатурою.
Повідомлення відображаються у stat/get і stat/pdf за каналом viber/bot; платні операції — у balance/history.
Зображення та кнопки
Зображення має бути доступним за публічним URL. Для сумісності з клієнтами Viber рекомендовано розмір до 1 МБ. Вимоги до медіа наведено в документації Viber.
Перед надсиланням замініть приклади URL на доступні адреси власних ресурсів. Натискання кнопки з callback_data обробляється webhook вашого бота.
Відмови Viber
Відмова провайдера повертається з error.code: "VIBER_REJECTED" і числовим error.viber_code. Для обмеження частоти використовується RATE_LIMIT_EXCEEDED. Основні коди:
viber_code
HTTP
Причина та обробка
2
422
Недійсний токен бота. Перевірте значення token.
5
422
Одержувач не зареєстрований у Viber. Перевірте актуальність його ID.
6
422
Одержувач не підписаний на бота. Припиніть надсилання до поновлення підписки.
10
422
Не налаштований webhook бота. Перевірте конфігурацію бота у Viber.
12
429
Перевищено допустиму частоту запитів. Призупиніть чергу; повтор планується відповідно до політики обмеження частоти.
Відмова Viber · HTTP 422 · приклад
{
"success": false,
"error": {
"code": "VIBER_REJECTED",
"message": "Одержувач не підписаний на Viber-бота.",
"viber_code": 6
}
}
Якщо відповідь провайдера має HTTP 5xx, UMIND може повернути HTTP 502. Повний перелік кодів провайдера наведено в Viber REST Bot API. Правила обробки помилок UMIND описано в загальному розділі.
Організація черги та приклад надсилання кільком підписникам: розсилка через Viber.
Ідентифікатор запису UMIND Connect. Використовується разом із method.
code
integer
Надісланий OTP. Початкові нулі не зберігаються в числовому представленні.
Особливості використання
Поле code у відповіді має числовий тип. Для коду з початковими нулями зберігайте вихідний рядок, переданий у запиті. Якщо код сформовано за code_length, доповнюйте значення відповіді нулями зліва до заданої довжини.
У разі одночасного передавання code і code_length надсилається значення code.
Перевірка введеного коду, строк його дії та ліміт спроб реалізуються на стороні інтеграції.
Виконує послідовність каналів у порядку, заданому в method. Обробка завершується після першої успішної відповіді каналу.
Параметри запиту
Параметр
Тип
Обов’язковість
Опис
method
array<string>
Так
Непорожній список, не більше 6 елементів. Порядок визначає чергу: tg, sms, tg-bot, viber-bot, call-otp, call-act; telegram/bot і viber/bot — синоніми відповідних бот-кроків. Повтори одного каналу прибираються.
to
string
Для телефонних каналів
Номер телефону. Можна пропустити, лише якщо всі кроки — Telegram/Viber-боти зі своїми to.
code
string
Без code_length
4–8 цифр; зберігає початкові нулі. Передайте code або code_length.
code_length
integer
Без code
4–8; використовується за відсутності code.
lifetime
integer
Ні
Передається крокам. Для спільного Telegram OTP + SMS обирайте 30–3600 секунд.
sms
object
Для кроку sms
Потрібний для кроку sms: alphaname — підтверджений відправник; text — шаблон із %c.
tg-bot
object
Для кроку tg-bot
Потрібний для кроку tg-bot: token, to (chat_id), text із %c; також photo, parse_mode, button або buttons. Допускається ключ telegram/bot замість tg-bot, але не обидва.
viber-bot
object
Для кроку viber-bot
Параметри Viber-бота: token, to (ID підписника), sender, text із %c та за потреби photo/buttons. Допускається ключ viber/bot замість viber-bot, але не обидва.
Ідентифікатор операції у журналі успішного каналу.
code
string
Код, повернений успішним каналом.
last_error
object
Повертається при невдалому каскаді: method та error останньої спроби.
Особливості використання
method у відповіді містить фактично успішний канал. Набір інших полів відповідає цьому каналу; додатково повертається code.
У шаблонах SMS, Telegram-бота та Viber-бота %c замінюється кодом. Якщо %c відсутній, надсилається лише код.
Для call/otp повертається код оператора, який може відрізнятися від code, переданого в каскад.
Каскад обробляє результати запитів синхронно. Статуси доставки або прочитання не впливають на послідовність після завершення запиту.
Права доступу, доступність каналів, альфаім’я та параметри Viber перевіряються до виконання відповідних операцій. Помилка попередньої перевірки може завершити весь запит.
Якщо жоден канал не підтвердив надсилання, повертається HTTP 502 з DELIVERY_FAILED і last_error.
За мережевої помилки попередній канал міг прийняти повідомлення. Перехід до іншого каналу не гарантує відсутності дублювання.
Приклад: Viber із резервним SMS
Якщо Viber повертає відмову, каскад переходить до SMS. Після прийняття Viber-повідомлення каскад завершується незалежно від подальшого статусу доставки.
Повертає відправлення за період, згруповані за каналами, зведення витрат і поточний баланс компанії.
Параметри запиту
Параметр
Тип
Обов’язковість
Опис
start
string
Так
Початок періоду, YYYY-MM-DD, включно.
finish
string
Так
Кінець періоду, YYYY-MM-DD, включно; не раніше start.
methods
array<string>
Ні
Канали: sms/single, telegram/bot, viber/bot, telegram/otp, call/otp, call/act. Пропущено — усі; [] — жодного, лише зведення. Відправлення sms/bulk включаються до sms/single; sms/bulk і pipeline/otp не є окремими каналами статистики.
sms_kind
string
Ні
all (типово) — усі SMS; single — SMS без кампанії; campaign — SMS у кампаніях. Значення single/campaign обмежують вибірку каналом sms/single.
campaign_id
integer
Ні
Додатний ID кампанії вашої компанії. Вибірка обмежується її SMS у заданому періоді. Не поєднується з sms_kind: single.
Групи каналів: method, count, money_spend, records; для SMS також segments.
campaigns
array<object>
Кампанії компанії за період: id, name, created_at.
data[].records[].campaign_id
integer | null
ID кампанії SMS; null для одиночних.
Особливості використання
summary.balance містить поточний баланс на момент запиту, а не залишок на дату finish.
data[].records містить записи відповідного каналу. Для пошуку результату відправлення зіставляйте data[].method і records[].id.
Пагінація та фільтри за id або одержувачем не передбачені. Для обмеження обсягу відповіді використовуйте період і список каналів.
Дати інтерпретуються в часовому поясі сервісу. Часові мітки у відповіді не містять UTC-зміщення.
Суми наведено у гривнях. Значення у прикладах ілюстративні; вартість визначається тарифами компанії.
Фільтри SMS-кампаній застосовуються до записів та підсумкових сум. Інші канали виключаються при sms_kind: single/campaign або campaign_id.
Масив campaigns містить кампанії компанії за період, зокрема без підтверджених відправлень. Він не обмежується фільтром campaign_id; фільтр застосовується до записів у data.
Формує PDF-звіт за періодом і набором каналів. Параметри відповідають stat/get.
Параметри запиту
Параметр
Тип
Обов’язковість
Опис
start
string
Так
Початок періоду, YYYY-MM-DD, включно.
finish
string
Так
Кінець періоду, YYYY-MM-DD, включно; не раніше start.
methods
array<string>
Ні
Канали: sms/single, telegram/bot, viber/bot, telegram/otp, call/otp, call/act. Пропущено — усі; [] — жодного, лише зведення. Відправлення sms/bulk включаються до sms/single; sms/bulk і pipeline/otp не є окремими каналами статистики.
sms_kind
string
Ні
all (типово) — усі SMS; single — SMS без кампанії; campaign — SMS у кампаніях. Значення single/campaign обмежують вибірку каналом sms/single.
campaign_id
integer
Ні
Додатний ID кампанії вашої компанії. Вибірка обмежується її SMS у заданому періоді. Не поєднується з sms_kind: single.
Розсилка виконується послідовністю викликів POST /api/viber/bot. Кожен запит адресовано одному підписнику й має окремий результат. Масив одержувачів у to і окремий метод пакетного надсилання не передбачені.
Підготовка одержувачів
Використовуйте активний Viber-бот із налаштованим HTTPS webhook. Ідентифікатор користувача доступний у sender.id події message або user.id події subscribed. Перше повідомлення користувача також оформлює підписку, але не створює окремої події subscribed. Зберігайте ID у власній базі та враховуйте подію unsubscribed; API Viber не надає метод отримання повного списку підписників. Формати подій описано в документації Viber.
Поле to приймає саме ID підписника вашого бота. Номер телефону не можна використовувати замість цього ID. Надсилання через Viber Business Messages за номерами телефонів цим методом не підтримується.
Організація черги
Сформуйте список активних підписників. Видаліть дублікати ID без зміни регістру або спеціальних символів. Персоналізуйте текст до відправлення запиту.
Створіть запис для кожної пари «розсилка — одержувач». Зберігайте стан обробки, час спроби та результат, щоб відновлення черги не повторювало підтверджені відправлення.
Надсилайте запити послідовно. Після успіху збережіть id, рядковий message_id та стан прийняття. success: true не підтверджує доставку або прочитання.
Відмови viber_code: 5 і 6 обробляйте для конкретного одержувача. Для коду 6 припиніть надсилання до поновлення підписки.
За HTTP 429 призупиніть чергу. Помилки авторизації, балансу або конфігурації потребують усунення причини. За тайм-ауту, обриву з’єднання чи HTTP 5xx перевірте результат операції перед повтором.
Послідовна розсилка Viber · Node.js 18+
// Node.js 18+. Секрети задаються у середовищі сервера.
async function main() {
const apiToken = process.env.UMIND_API_TOKEN;
const botToken = process.env.VIBER_BOT_TOKEN;
if (!apiToken || !botToken) {
throw new Error('Задайте UMIND_API_TOKEN і VIBER_BOT_TOKEN');
}
// Приклади ID: замініть їх ідентифікаторами підписників свого бота.
const recipients = ['01234567890A=', '01234567890B='];
const uniqueRecipients = [...new Set(recipients)];
for (const to of uniqueRecipients) {
let response;
let result;
try {
response = await fetch('https://connect.umind.group/api/viber/bot', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + apiToken,
'Content-Type': 'application/json',
Accept: 'application/json'
},
body: JSON.stringify({
to,
token: botToken,
sender: { name: 'MyBrand' },
text: 'Інформація про ваше замовлення доступна в особистому кабінеті.',
buttons: [[{
text: 'Переглянути',
url: 'https://example.com/orders'
}]]
}),
signal: AbortSignal.timeout(90000),
redirect: 'error'
});
result = await response.json();
} catch {
// Результат може бути невизначеним: автоматичного повтору немає.
throw new Error('Чергу зупинено: перевірте результат запиту для ' + to);
}
if (response.ok && result?.success === true) {
// У робочій інтеграції збережіть результат у БД перед наступним запитом.
console.log({
to,
state: 'accepted',
id: result.id,
message_id: result.message_id // Зберігається рядком.
});
continue;
}
// Відмови для конкретного одержувача не зупиняють усю розсилку.
if (response.status === 422
&& result?.error?.code === 'VIBER_REJECTED'
&& [5, 6].includes(result.error.viber_code)) {
console.log({ to, state: 'rejected', viber_code: result.error.viber_code });
continue;
}
// 429, помилки доступу/балансу/конфігурації та 5xx зупиняють чергу.
throw new Error(
'Чергу зупинено: HTTP ' + response.status + '; ' +
(result?.error?.code ?? 'UNEXPECTED_RESPONSE')
);
}
}
main().catch(error => {
console.error(error.message);
process.exitCode = 1;
});
Приклад демонструє послідовну обробку та зупинку за помилки без автоматичного повтору. Для постійної черги замініть виведення результатів на збереження в БД і вибирайте лише необроблені записи. Ключ ідемпотентності API не підтримує: повторний запуск з тим самим списком може створити повторні повідомлення.
Статистика розсилки доступна через stat/get з methods: ["viber/bot"]. Для OTP з резервним каналом використовуйте pipeline/otp з кроком viber-bot.
Статуси відправлень
Успішна відповідь методу надсилання підтверджує прийняття запиту каналом. Для зіставлення з результатом у stat/get використовуйте пару method і id. Для sms/bulk це stat_method: "sms/single" і messages[].id; кампанія визначається полем campaign_id.
Статус
Значення
Обробка
ACCEPTED, QUEUED, ROUTING
SMS прийнято, поставлено в чергу або передано на маршрутизацію.
Недоставка, відмова, скасування або недостатність коштів у каналі.
Визначити причину перед повторним надсиланням.
UNKNOWN або невідоме значення
Результат не визначено.
Зберегти первинне значення; не позначати як успіх.
Для програмної обробки використовуйте status. Поле status_text призначене для відображення і не замінює перевірку технічного статусу. Набір станів залежить від каналу.
Telegram- і Viber-боти: статистика UMIND містить SENT після прийняття повідомлення провайдером. Оновлення до DELIVERED або READ для цих методів не надається. Дзвінки: використовують статуси оператора; для call/act результат дії передається через callback.
Поля записів статистики за каналами
Спільні:id, date, to, price. За відсутності даних окремі поля можуть містити null.
SMS:campaign_id (ID кампанії або null для одиночного SMS), from, text, lifetime, segments, status, status_date, status_text.
Viber-бот:sender_name, text, photo, buttons, рядковий message_id, status, status_date, status_text. Поле to містить Viber ID; токен бота не повертається.
Call OTP:status, status_date, status_text.
Call ACT:callback — URL обробника події; callback_response — HTTP-статус його відповіді; callback_date — час виклику.
Окремі поля з OTP і секретами провайдерів у статистиці відсутні. Якщо код входить до тексту повідомлення, він може бути присутній у полі text; доступ до таких даних слід обмежити.
Валідація OTP
API забезпечує надсилання коду. Сервер інтеграції відповідає за його перевірку, строк чинності, кількість спроб і одноразове використання.
Створіть спробу підтвердження, пов’язану з конкретним користувачем, одержувачем і дією.
Згенеруйте код криптографічно стійким генератором або використовуйте код із відповіді telegram/otp, call/otp чи pipeline/otp.
Зберігайте очікуваний код на сервері з обмеженим строком чинності та кількістю спроб. Для коротких кодів використовуйте захищене сховище або HMAC із серверним секретом.
Перевіряйте введене значення на сервері. Після успішної перевірки або завершення строку чинності закривайте спробу.
Очікуваний code не повинен передаватися клієнтському застосунку. У відповіді клієнту достатньо ідентифікатора спроби та результату надсилання. Параметр lifetime каналу не встановлює строк чинності коду у вашій системі.
Для каскаду з call/otp використовуйте код із фактичної відповіді: оператор може сформувати значення, відмінне від переданого. Статус доставки не замінює перевірку OTP.
Callback дзвінка
Метод call/act передає подію на адресу callback_url HTTP-запитом POST із JSON-тілом.
id — ідентифікатор дзвінка UMIND; externalNumber — номер одержувача; internalNumber — номер сценарію оператора; press — значення дії. Семантика дії визначається підключеним сценарієм.
Заголовок X-Signature: sha256=… містить HMAC-SHA256 від сирого тіла запиту. Ключ підпису — повне значення того самого API-токена, який ви передали в Authorization: Bearer … під час створення цього дзвінка через call/act. Використовуйте сам рядок токена без префікса Bearer , без хешування та без декодування hex. Окремий секрет для callback створювати чи передавати не потрібно.
Формула: X-Signature = "sha256=" + hex(HMAC-SHA256(API_TOKEN, raw_body)). Після sha256= йдуть 64 шістнадцяткові символи в нижньому регістрі. Сервіс підписує саме ті байти JSON, які надсилає. Токен не передається в callback.
Створіть іменований API-токен у кабінеті, збережіть його на сервері інтеграції й використовуйте для запиту та перевірки callback. Якщо інтеграція використовує кілька токенів, зберігайте зв’язок між id дзвінка і використаним токеном. Перейменування токена не змінює підпис; після відкликання вже прийняті дзвінки підписуються початковим токеном, а нові запити з ним відхиляються. Збережіть старий токен до завершення очікуваних callback.
Перевірка підпису callback · PHP
<?php
// Той самий токен, з яким інтеграція створила дзвінок через call/act.
$apiToken = getenv('UMIND_API_TOKEN');
if (!is_string($apiToken) || !preg_match('/^[A-Za-z0-9]{64}$/D', $apiToken)) {
http_response_code(500);
exit;
}
$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if ($rawBody === false) {
http_response_code(400);
exit;
}
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $apiToken);
if (!hash_equals($expected, $received)) {
http_response_code(403);
exit;
}
try {
$event = json_decode($rawBody, true, 32, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
http_response_code(400);
exit;
}
// Перевірте method, id і номер за очікуваною операцією.
// Надійно збережіть подію з захистом від повторної обробки.
// Поверніть HTTP 200 лише після успішного збереження.
Приклад використовує один токен інтеграції. За кількох токенів виберіть очікуваний ключ для дзвінка зі свого серверного сховища; дані події вважайте довіреними лише після перевірки підпису.
Для власної інтеграції створюйте дзвінки через API з Bearer-токеном. Дзвінки, створені через сесію кабінету, підписуються його серверним системним токеном. Для дзвінків, прийнятих до встановлення цього оновлення, зберігається попередній ключ компанії.
Перевіряйте підпис за сирими байтами тіла до повторного кодування JSON. Порівняння підписів має виконуватися за сталий час.
Зіставляйте id, метод і номер з очікуваною операцією. Забезпечте ідемпотентну обробку повторно отриманої події.
Поверніть HTTP 200 після надійного збереження валідної події. Тривалу обробку виконуйте асинхронно.
Автоматична повторна доставка callback не гарантована. Результат звернення до обробника доступний у callback_response і callback_date статистики.
Для статусів SMS і Telegram OTP використовуйте stat/get. Події власного Viber- або Telegram-бота обробляються його webhook.
Помилки та повторні запити
Обробляйте HTTP-статус разом із error.code. Текст error.message призначений для діагностики; логіка інтеграції має спиратися на код помилки.
Уточнити результат відправлення; передати підтримці метод, час і код помилки.
503
Сервіс недоступний.
Призупинити надсилання та звернутися до підтримки, передавши код помилки з відповіді.
500 · SERVER_ERROR
Внутрішня помилка API.
Зафіксувати час і метод; перевірити результат операції перед повтором.
Політика повторів
Методи надсилання не підтримують універсальний ключ ідемпотентності. Для sms/bulk повтор уже записаного номера в тій самій кампанії відхиляється з HTTP 409; результати uncertain або втрачені відповіді цей механізм не покриває. Зберігайте стан операції на стороні інтеграції: повторний запит може створити окреме повідомлення та списання.
Помилка валідації: виправте параметри до наступного запиту.
Тайм-аут, обрив з’єднання або 5xx: результат може залишатися невизначеним. Перевірте статистику; відсутність запису одразу після помилки не гарантує, що повідомлення не надіслано.
ACCOUNT_BUSY: операція не отримала доступ до виконання. Використовуйте послідовну чергу та обмежену затримку перед повтором.
RATE_LIMIT_EXCEEDED: призупиніть надсилання. Якщо присутнє error.retry_after, значення визначає мінімальну затримку в секундах. Поле не гарантоване для всіх каналів, зокрема Viber.
Приклади використовують тайм-аут 90 секунд; окремі клієнти додатково обмежують встановлення з’єднання 10 секундами. Це налаштування клієнта. Допустиму інтенсивність розсилки слід узгодити для каналів компанії.
Поширені запитання
Як отримати поточний баланс?
Виконайте balance/get з тілом {} і прочитайте balance. Валюта — UAH. Дати не потрібні. Метод stat/get також повертає поточний баланс у summary.balance.
Чи підтримується розсилка на список одержувачів?
Для SMS використовуйте sms/bulk: до 1000 номерів в одному запиті. Кілька груп можна об’єднати через campaign_id. Telegram- і Viber-боти надсилають одному одержувачу за запит; для Viber наведено приклад послідовної розсилки.
Який тариф застосовується до групового SMS?
Вартість одного сегмента дорівнює тарифу sms/single. Сума залежить від кількості сегментів і прийнятих відправлень. Окрема плата за кампанію відсутня. Деталі: вартість і сегменти.
Чи можна надіслати Viber-повідомлення за номером телефону?
Метод viber/bot приймає лише ID підписника бота. Телефонний номер і Viber ID не є взаємозамінними. Список телефонів не можна використати для цього методу без відповідних ID підписників.
Що означає Viber-код 6?
Одержувач не має активної підписки на бота. Виключіть його з черги та відновлюйте надсилання лише після поновлення підписки.
Чи переходить каскад до SMS, якщо Viber або Telegram не прочитано?
Каскад завершується після першого підтвердження прийняття повідомлення каналом. Подальший статус прочитання не запускає наступний крок.
Чому GET-запит повертає HTTP 415?
Заголовок Content-Type: application/json потрібен також для GET без тіла. Додайте його разом із заголовком авторизації.
Який метод використовувати для перевірки токена?
Використовуйте auth/me. Метод перевіряє доступ і повертає профіль компанії без платної операції надсилання.