Connect
Документація API

Документація API

UMIND Connect API забезпечує надсилання SMS, повідомлень через Telegram- і Viber-ботів, одноразових кодів та автоматизовані дзвінки. Довідник містить параметри методів, формати відповідей і приклади інтеграції.

Базова адреса APIhttps://connect.umind.group/api/

Початок інтеграції

  1. Створіть API-токен

    У кабінеті UMIND Connect відкрийте «API-токени», виберіть «Створити токен» і вкажіть назву інтеграції. Повне значення відображається один раз. Збережіть токен у змінній середовища UMIND_API_TOKEN на сервері інтеграції.

  2. Перевірте авторизацію

    Виконайте запит auth/me. Успішна відповідь містить профіль компанії, баланс і доступні альфаімена. Метод не виконує платних відправлень.

  3. Підключіть потрібний канал

    Сформуйте запит за специфікацією методу. Перевірте HTTP-статус і поле success. Зберігайте ідентифікатори відправлень для зіставлення зі статистикою. Для групового SMS перевіряйте також messages[].state.

Перший запит · cURL
curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --request POST 'https://connect.umind.group/api/auth/me' \
  --header "Authorization: Bearer ${UMIND_API_TOKEN:?Set UMIND_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --write-out '\nHTTP %{http_code}\n'

Авторизація

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

Заголовки запиту
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json
  • 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

Для кожного методу наведено параметри, умови їх обов’язковості, приклад запиту, структуру відповіді та правила обробки результату.

Шлях після /api/ПризначенняHTTP
sms/singleНадсилання SMSPOST
sms/bulkМасове надсилання SMSPOST
telegram/botНадсилання через Telegram-ботаPOST
viber/botНадсилання через Viber-ботаPOST
telegram/otpНадсилання OTP у TelegramPOST
call/otpOTP через телефонний дзвінокPOST
call/actПідтвердження дією під час дзвінкаPOST
pipeline/otpКаскадне надсилання OTPPOST
stat/getСтатистика відправленьPOST / GET
stat/pdfЕкспорт статистики у PDFPOST / GET
balance/getПеревірка балансуPOST / GET
balance/historyІсторія руху коштівPOST / GET
auth/meПрофіль компаніїPOST / GET
settings/alphanamesАльфаімена компаніїPOST / GET
settings/alphanames/submitДодавання альфаіменіPOST
settings/alphanames/deleteВидалення альфаіменіPOST

Приклади інтеграції

Виберіть метод і мову програмування. Приклади містять авторизацію, тайм-аут та перевірку відповіді; для 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 і персональні дані у загальнодоступні журнали.

Надсилання повідомлень і кодів

Методи одиночного та групового надсилання. Доступність каналів і вартість визначаються налаштуваннями компанії.

POST/api/sms/singleAPI-токен компанії

Надсилання SMS

Надсилає текстове повідомлення одному одержувачу. Відправник задається підтвердженим альфаіменем компанії.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostringТакУкраїнський номер. Рекомендований формат: +380671234567. Один номер на запит.
alphanamestringТакПідтверджене альфаім’я саме компанії, з точним регістром.
textstringТакНепорожній текст UTF-8. Підставте імена та інші змінні до запиту.
lifetimeintegerНіЧас очікування доставки, 0–86400 секунд; типово 86400. Це не строк дії коду у вашій системі.
Тіло POST · JSON
{
  "to": "+380671234567",
  "alphaname": "MyBrand",
  "text": "Ваше замовлення готове до отримання.",
  "lifetime": 3600
}
Відповідь · HTTP 200 · приклад
{
  "method": "sms/single",
  "success": true,
  "id": 1201,
  "segments": 1
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
segmentsintegerКількість частин SMS.

Особливості використання

  • segments містить кількість частин SMS, за якими розраховується вартість відправлення. Кількість частин залежить від довжини та кодування тексту.
  • Персоналізація виконується на стороні інтеграції: у text передається сформований текст. Підстановка {{name}} та інших змінних методом не виконується.
  • Для кількох номерів використовуйте sms/bulk. Поле to у цьому методі приймає одного одержувача.
  • Статус доставки доступний через stat/get за методом sms/single та отриманим id.
Приклади інтеграції: sms/single
POST/api/sms/bulkAPI-токен компанії

Масове надсилання SMS

Надсилає однаковий текст групі від 1 до 1000 українських номерів. Відправлення об’єднуються в кампанію; кожен одержувач має окремий результат і запис статистики.

Параметри запиту

ПараметрТипОбов’язковістьОпис
recipientsarray<string>ТакВід 1 до 1000 номерів у вхідному масиві. Рекомендований формат: +380671234567. Дублікати видаляються після нормалізації. Некоректний номер спричиняє відмову всього запиту до надсилання.
alphanamestringТакПідтверджене альфаім’я компанії. Регістр має збігатися з підтвердженою назвою.
textstringТакНепорожній текст UTF-8, до 10 000 символів, без нульового символу. Один текст для всіх одержувачів запиту. Підстановка змінних виконується на стороні інтеграції.
lifetimeintegerНіСтрок очікування доставки: 0–86400 секунд; типово 86400. Округлюється в більший бік до повної хвилини, мінімум — 1 хвилина.
campaign_namestringНіНазва нової кампанії, до 120 символів після видалення пробілів на початку й у кінці, без керувальних символів і переносів рядка. Якщо назву пропущено або передано порожній рядок, вона формується за датою та часом.
campaign_idintegerНіДодатний ID наявної кампанії вашої компанії. Додає до неї наступну групу відправлень. Не передається разом із campaign_name.
Тіло POST · JSON
{
  "recipients": [
    "+380671234567",
    "+380501234567"
  ],
  "alphaname": "MyBrand",
  "text": "Ваше замовлення готове.",
  "lifetime": 3600,
  "campaign_name": "Замовлення за вересень"
}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "method": "sms/bulk",
  "stat_method": "sms/single",
  "campaign": {
    "id": 42,
    "name": "Замовлення за вересень"
  },
  "messages": [
    {
      "to": "+380671234567",
      "state": "accepted",
      "status": "ACCEPTED",
      "message": "Прийнято до відправлення",
      "id": 1201,
      "segments": 1,
      "price": 1.25
    },
    {
      "to": "+380501234567",
      "state": "accepted",
      "status": "ACCEPTED",
      "message": "Прийнято до відправлення",
      "id": 1202,
      "segments": 1,
      "price": 1.25
    }
  ],
  "money_spend": 2.5
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішної обробки загальної відповіді. Результат кожного відправлення визначається через messages[].state.
methodstringМетод запиту: sms/bulk.
stat_methodstringКанал статистики: sms/single.
campaign.idintegerID кампанії для наступних груп і фільтра статистики.
campaign.namestringНазва кампанії. Не входить до тексту SMS.
messagesarray<object>По одному результату для кожного унікального нормалізованого номера. Зіставляйте результати за to.
messages[].tostringНормалізований номер у форматі +380…
messages[].statestringaccepted, failed або uncertain. Правила обробки наведено нижче.
messages[].messagestringОпис результату для діагностики. Програмна обробка має спиратися на state і status.
messages[].idintegerІдентифікатор запису UMIND. Є для accepted і failed; відсутній для uncertain.
messages[].statusstringСтатус відправлення: наприклад ACCEPTED або REJECTED. Відсутній для uncertain.
messages[].segmentsintegerКількість сегментів одного SMS. Є для accepted і failed; відсутня для uncertain.
messages[].pricenumberСписана сума у гривнях: кількість сегментів × тариф sms/single для accepted, 0 для failed. Відсутня для uncertain.
money_spendnumberСума 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.

Частковий результат · HTTP 200 · приклад
{
  "success": true,
  "method": "sms/bulk",
  "stat_method": "sms/single",
  "campaign": {
    "id": 42,
    "name": "Замовлення за вересень"
  },
  "messages": [
    {
      "to": "+380671234567",
      "state": "accepted",
      "status": "ACCEPTED",
      "message": "Прийнято до відправлення",
      "id": 1201,
      "segments": 1,
      "price": 1.25
    },
    {
      "to": "+380501234567",
      "state": "failed",
      "status": "REJECTED",
      "message": "Оператор відхилив повідомлення.",
      "id": 1202,
      "segments": 1,
      "price": 0
    },
    {
      "to": "+380931234567",
      "state": "uncertain",
      "message": "Немає однозначного підтвердження. Перевірте статистику перед повтором."
    }
  ],
  "money_spend": 1.25
}

Кампанія з кількох запитів

  1. У першому запиті передайте campaign_name або пропустіть обидва поля кампанії. Збережіть повернений campaign.id.
  2. Поділіть решту номерів на групи до 1000 елементів. У наступних запитах передавайте збережений campaign_id без campaign_name.
  3. Виконуйте запити послідовно та зберігайте результат кожної групи. Для 10 000 номерів з однаковим текстом достатньо 10 запитів по 1000 номерів.
  4. Для персоналізації згрупуйте одержувачів за однаковим готовим текстом. Передавайте ці групи в межах тієї самої кампанії; кожен номер має входити лише в одну групу.
Додавання наступної групи
POST /api/sms/bulk · наступна група
{
  "recipients": [
    "+380931234567",
    "+380991234567"
  ],
  "alphaname": "MyBrand",
  "text": "Ваше замовлення готове.",
  "lifetime": 3600,
  "campaign_id": 42
}

campaign_id групує відправлення та запобігає повтору вже записаних номерів. Він не є універсальним ключем ідемпотентності. Після тайм-ауту, HTTP 502 або uncertain автоматично повторювати групу не слід.

Статистика кампанії

Для stat/get і stat/pdf передавайте methods: ["sms/single"] та campaign_id. Вибірка обмежується зазначеним періодом; запис одержувача містить його campaign_id.

POST /api/stat/get · кампанія
{
  "start": "2026-09-01",
  "finish": "2026-09-22",
  "methods": [
    "sms/single"
  ],
  "campaign_id": 42
}

Помилки групового запиту

HTTP / кодПричинаОбробка
400 · INVALID_RECIPIENTSПоле recipients не є списком із 1–1000 елементів.Перевірити формат і розмір групи до видалення дублікатів сервером.
400 · INVALID_PHONEПринаймні один номер некоректний.Виправити список; цей запит не виконує відправлень.
400 · INVALID_TEXT, INVALID_LIFETIMEТекст або строк доставки не відповідає вимогам.Перевірити параметри за таблицею запиту.
400 · INVALID_CAMPAIGN, INVALID_CAMPAIGN_NAMEНекоректний ID чи назва або одночасно передано обидва поля.Передати campaign_id для наявної кампанії або campaign_name для нової.
402 · INSUFFICIENT_BALANCEКоштів недостатньо для всієї групи.Поповнити баланс або зменшити групу. Надсилання цього запиту не виконується.
403 · ALPHANAME_NOT_ALLOWED, METHOD_UNAVAILABLEАльфаім’я не підтверджене або SMS недоступні для компанії.Перевірити відправника та доступ до SMS.
404 · CAMPAIGN_NOT_FOUNDКампанія не існує або не належить компанії токена.Використати власний campaign.id із відповіді.
409 · CAMPAIGN_RECIPIENT_EXISTSУ кампанії вже є запис хоча б для одного номера групи.Запит відхиляється повністю. Зіставити номери зі статистикою до формування нової групи.
422 · OPERATOR_REJECTEDЗапит відхилено без прийнятих відправлень.Перевірити параметри та відправника; списання за цим запитом не виконується.
502 · REQUEST_ERROR, INVALID_RESPONSEРезультат запиту не підтверджено.Перевірити статистику й уточнити результат перед повтором.

Помилки авторизації, обмеження частоти та недоступність сервісу описано в загальному розділі помилок.

Приклади інтеграції: sms/bulk
POST/api/telegram/botAPI-токен компанії

Надсилання через Telegram-бота

Надсилає текст, зображення та кнопки від імені Telegram-бота. Токен UMIND передається в Authorization, токен бота — у полі token.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostring | integerТакchat_id (також від’ємний для груп) або @username каналу/супергрупи. Номер телефону не підтримується.
tokenstringТакТокен вашого Telegram-бота, формат 123456789:YOUR_BOT_TOKEN.
textstringБез photoТекст до 4096 символів; із photo — підпис до 1024. Обов’язковий, якщо немає photo.
photostringНіПублічне HTTP/HTTPS-посилання або file_id Telegram. Base64 і завантаження файлу цим методом не підтримуються.
parse_modestringНіHTML, Markdown або MarkdownV2. Без параметра текст звичайний; для розмітки остаточні ліміти перевіряє Telegram.
buttonsarrayНіМасив рядків кнопок. Кожна кнопка: text і рівно одне з url (http/https/tg) або callback_data (1–64 байти).
buttonobjectНіОдна кнопка як альтернатива buttons. Не передавайте одночасно з buttons.
Тіло POST · JSON
{
  "to": "123456789",
  "token": "123456789:YOUR_BOT_TOKEN",
  "text": "<b>Замовлення готове</b>",
  "parse_mode": "HTML",
  "buttons": [
    [
      {
        "text": "Відкрити замовлення",
        "url": "https://example.com/orders/42"
      }
    ]
  ]
}
Відповідь · HTTP 200 · приклад
{
  "method": "telegram/bot",
  "success": true,
  "id": 1202,
  "message_id": 85,
  "chat_id": 123456789
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
message_idintegerІдентифікатор повідомлення Telegram.
chat_idintegerІдентифікатор чату Telegram.

Особливості використання

  • Для особистого повідомлення потрібен chat_id користувача, який почав взаємодію з ботом. Для каналу або супергрупи бот повинен мати відповідні права.
  • @username підтримується для каналу або супергрупи. Username особистого облікового запису не замінює chat_id.
  • Кнопки callback_data обробляються застосунком бота через його webhook або getUpdates.
  • Статус SENT підтверджує прийняття повідомлення Telegram. Підтвердження доставки та прочитання бот-повідомлень у статистиці UMIND не надається.
Приклади інтеграції: telegram/bot
POST/api/viber/botAPI-токен компанії

Надсилання через Viber-бота

Надсилає повідомлення одному підписнику Viber-бота. Підтримуються текст, зображення та клавіатура з кнопками. Для розсилки використовується окремий запит для кожного одержувача.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostringТакІдентифікатор підписника Viber, 1–255 символів. Допустимі A–Z, a–z, 0–9, +, /, _, =, -. Числовий номер телефону не приймається. Регістр і спеціальні символи зберігаються без змін.
tokenstringТакТокен Viber-бота: 16–255 латинських літер, цифр, _ або -. Відрізняється від Bearer-токена UMIND.
senderobjectТакПараметри відправника. Обов’язково містить name; може містити avatar.
sender.namestringТакНепорожня назва відправника, від 1 до 28 символів.
sender.avatarstringНіHTTP/HTTPS URL аватара, до 2000 байтів.
textstringБез photoТекст повідомлення: 1–7000 символів. За наявності photo — підпис до 768 символів; може бути порожнім або пропущеним.
photostringНіHTTP/HTTPS URL зображення, до 2000 байтів. Шлях URL має завершуватися .jpg, .jpeg, .png або .gif. Анімовані GIF, Base64 і завантаження файлу у тілі запиту не підтримуються.
buttonsarray<array<object>>НіКлавіатура: масив рядків із 1–3 кнопками в кожному. Не більше 20 кнопок загалом. Формат кнопки наведено нижче.
buttonobjectНіОдна кнопка як альтернатива buttons. Одночасне передавання button і buttons не допускається.

Формат кнопки

ПараметрТипОбов’язковістьОпис
textstringТакТекст кнопки, 1–100 символів.
urlstringАбо callback_dataHTTP/HTTPS URL до 2000 байтів.
callback_datastringАбо urlВміст відповіді боту, 1–64 байти UTF-8.
Тіло POST · JSON
{
  "to": "01234567890A=",
  "token": "YOUR_VIBER_BOT_TOKEN",
  "sender": {
    "name": "MyBrand"
  },
  "text": "Замовлення №42 готове до отримання.",
  "buttons": [
    [
      {
        "text": "Переглянути замовлення",
        "url": "https://example.com/orders/42"
      }
    ]
  ]
}
Відповідь · HTTP 200 · приклад
{
  "method": "viber/bot",
  "success": true,
  "id": 1207,
  "message_id": "18446744073709551614",
  "to": "01234567890A="
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
message_idstringІдентифікатор повідомлення Viber.
tostringІдентифікатор одержувача з запиту.

Особливості використання

  • Для надсилання потрібні активний 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.

Viber · зображення та кнопки · JSON
{
  "to": "01234567890A=",
  "token": "YOUR_VIBER_BOT_TOKEN",
  "sender": {
    "name": "MyBrand",
    "avatar": "https://example.com/brand/avatar.png"
  },
  "text": "Замовлення №42 готове до отримання.",
  "photo": "https://example.com/orders/42.jpg",
  "buttons": [
    [
      {
        "text": "Переглянути",
        "url": "https://example.com/orders/42"
      },
      {
        "text": "Підтвердити",
        "callback_data": "confirm_order:42"
      }
    ]
  ]
}

Перед надсиланням замініть приклади URL на доступні адреси власних ресурсів. Натискання кнопки з callback_data обробляється webhook вашого бота.

Відмови Viber

Відмова провайдера повертається з error.code: "VIBER_REJECTED" і числовим error.viber_code. Для обмеження частоти використовується RATE_LIMIT_EXCEEDED. Основні коди:

viber_codeHTTPПричина та обробка
2422Недійсний токен бота. Перевірте значення token.
5422Одержувач не зареєстрований у Viber. Перевірте актуальність його ID.
6422Одержувач не підписаний на бота. Припиніть надсилання до поновлення підписки.
10422Не налаштований webhook бота. Перевірте конфігурацію бота у Viber.
12429Перевищено допустиму частоту запитів. Призупиніть чергу; повтор планується відповідно до політики обмеження частоти.
Відмова 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.

Приклади інтеграції: viber/bot
POST/api/telegram/otpAPI-токен компанії

Надсилання OTP у Telegram

Надсилає одноразовий код на номер телефону через Telegram. Використовується code або code_length; токен Telegram-бота не потрібен.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostringТакУкраїнський номер. Рекомендований формат: +380671234567. Один номер на запит.
codestringБез code_lengthВаш код із 4–8 цифр. Передайте code або code_length; якщо є обидва, використовується code.
code_lengthintegerБез code4–8: сервер згенерує код цієї довжини, якщо немає code.
lifetimeintegerНі30–3600 секунд; типово 3600.
Тіло POST · JSON
{
  "to": "+380671234567",
  "code": "123456",
  "lifetime": 300
}
Відповідь · HTTP 200 · приклад
{
  "method": "telegram/otp",
  "success": true,
  "id": 1203,
  "code": 123456
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
codeintegerНадісланий OTP. Початкові нулі не зберігаються в числовому представленні.

Особливості використання

  • Поле code у відповіді має числовий тип. Для коду з початковими нулями зберігайте вихідний рядок, переданий у запиті. Якщо код сформовано за code_length, доповнюйте значення відповіді нулями зліва до заданої довжини.
  • У разі одночасного передавання code і code_length надсилається значення code.
  • Перевірка введеного коду, строк його дії та ліміт спроб реалізуються на стороні інтеграції.
Приклади інтеграції: telegram/otp
POST/api/call/otpAPI-токен компанії

OTP через телефонний дзвінок

Ініціює дзвінок для підтвердження номера телефону. Код формується оператором і повертається у відповіді.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostringТакУкраїнський номер. Рекомендований формат: +380671234567. Один номер на запит.
Тіло POST · JSON
{
  "to": "+380671234567"
}
Відповідь · HTTP 200 · приклад
{
  "method": "call/otp",
  "success": true,
  "id": 1204,
  "code": 1234
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
codestring | integerКод, сформований оператором.

Особливості використання

  • Тип поля code залежить від оператора: рядок або число. Зберігайте його як рядок у своїй системі.
  • Поля code і code_length не задають код дзвінка. Для перевірки використовуйте значення з відповіді.
  • Сценарій отримання коду одержувачем залежить від підключеної послуги. Його параметри погоджуються під час підключення каналу.
  • Очікуваний OTP не повинен передаватися клієнтському застосунку.
Приклади інтеграції: call/otp
POST/api/call/actAPI-токен компанії

Підтвердження дією під час дзвінка

Ініціює дзвінок із підтвердженням дією одержувача. Результат передається POST-запитом на callback_url.

Параметри запиту

ПараметрТипОбов’язковістьОпис
tostringТакУкраїнський номер. Рекомендований формат: +380671234567. Один номер на запит.
callback_urlstringТакАдреса вашого обробника callback. Використовуйте публічний HTTPS URL.
Тіло POST · JSON
{
  "to": "+380671234567",
  "callback_url": "https://example.com/webhooks/umind-call"
}
Відповідь · HTTP 200 · приклад
{
  "method": "call/act",
  "success": true,
  "id": 1205,
  "phone": "+380441234567"
}

Основні поля відповіді

ПолеТипОпис
successbooleanОзнака успішного виконання запиту.
methodstringМетод, який виконав операцію.
idintegerІдентифікатор запису UMIND Connect. Використовується разом із method.
phonestring | nullНомер, пов’язаний зі сценарієм дзвінка; може бути відсутнім у даних оператора.

Особливості використання

  • Успішна відповідь підтверджує запуск дзвінка. Результат дії надходить окремим callback.
  • Поле phone містить номер, пов’язаний зі сценарієм дзвінка. Значення визначається підключеною послугою.
  • Формат події та вимоги до перевірки підпису наведено в розділі «Callback дзвінка».
Приклади інтеграції: call/act
POST/api/pipeline/otpAPI-токен компанії

Каскадне надсилання OTP

Виконує послідовність каналів у порядку, заданому в method. Обробка завершується після першої успішної відповіді каналу.

Параметри запиту

ПараметрТипОбов’язковістьОпис
methodarray<string>ТакНепорожній список, не більше 6 елементів. Порядок визначає чергу: tg, sms, tg-bot, viber-bot, call-otp, call-act; telegram/bot і viber/bot — синоніми відповідних бот-кроків. Повтори одного каналу прибираються.
tostringДля телефонних каналівНомер телефону. Можна пропустити, лише якщо всі кроки — Telegram/Viber-боти зі своїми to.
codestringБез code_length4–8 цифр; зберігає початкові нулі. Передайте code або code_length.
code_lengthintegerБез code4–8; використовується за відсутності code.
lifetimeintegerНіПередається крокам. Для спільного Telegram OTP + SMS обирайте 30–3600 секунд.
smsobjectДля кроку smsПотрібний для кроку sms: alphaname — підтверджений відправник; text — шаблон із %c.
tg-botobjectДля кроку tg-botПотрібний для кроку tg-bot: token, to (chat_id), text із %c; також photo, parse_mode, button або buttons. Допускається ключ telegram/bot замість tg-bot, але не обидва.
viber-botobjectДля кроку viber-botПараметри Viber-бота: token, to (ID підписника), sender, text із %c та за потреби photo/buttons. Допускається ключ viber/bot замість viber-bot, але не обидва.
call-actobjectДля кроку call-actДля кроку call-act передайте callback_url.
Тіло POST · JSON
{
  "method": [
    "tg",
    "sms"
  ],
  "to": "+380671234567",
  "code": "012345",
  "lifetime": 300,
  "sms": {
    "alphaname": "MyBrand",
    "text": "Ваш код: %c"
  }
}
Відповідь · HTTP 200 · приклад
{
  "method": "sms/single",
  "success": true,
  "id": 1206,
  "segments": 1,
  "code": "012345"
}

Основні поля відповіді

ПолеТипОпис
successbooleanРезультат виконання каскаду.
methodstringКанал, який підтвердив надсилання.
idintegerІдентифікатор операції у журналі успішного каналу.
codestringКод, повернений успішним каналом.
last_errorobjectПовертається при невдалому каскаді: method та error останньої спроби.

Особливості використання

  • method у відповіді містить фактично успішний канал. Набір інших полів відповідає цьому каналу; додатково повертається code.
  • У шаблонах SMS, Telegram-бота та Viber-бота %c замінюється кодом. Якщо %c відсутній, надсилається лише код.
  • Для call/otp повертається код оператора, який може відрізнятися від code, переданого в каскад.
  • Каскад обробляє результати запитів синхронно. Статуси доставки або прочитання не впливають на послідовність після завершення запиту.
  • Права доступу, доступність каналів, альфаім’я та параметри Viber перевіряються до виконання відповідних операцій. Помилка попередньої перевірки може завершити весь запит.
  • Якщо жоден канал не підтвердив надсилання, повертається HTTP 502 з DELIVERY_FAILED і last_error.
  • За мережевої помилки попередній канал міг прийняти повідомлення. Перехід до іншого каналу не гарантує відсутності дублювання.
Приклад: Viber із резервним SMS

Якщо Viber повертає відмову, каскад переходить до SMS. Після прийняття Viber-повідомлення каскад завершується незалежно від подальшого статусу доставки.

Каскад Viber → SMS · JSON
{
  "method": [
    "viber-bot",
    "sms"
  ],
  "to": "+380671234567",
  "code": "012345",
  "lifetime": 300,
  "viber-bot": {
    "to": "01234567890A=",
    "token": "YOUR_VIBER_BOT_TOKEN",
    "sender": {
      "name": "MyBrand"
    },
    "text": "Код підтвердження: %c"
  },
  "sms": {
    "alphaname": "MyBrand",
    "text": "Код підтвердження: %c"
  }
}
Приклади інтеграції: pipeline/otp

Статистика та рух коштів

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

POSTGET/api/stat/getAPI-токен компанії

Статистика відправлень

Повертає відправлення за період, згруповані за каналами, зведення витрат і поточний баланс компанії.

Параметри запиту

ПараметрТипОбов’язковістьОпис
startstringТакПочаток періоду, YYYY-MM-DD, включно.
finishstringТакКінець періоду, YYYY-MM-DD, включно; не раніше start.
methodsarray<string>НіКанали: sms/single, telegram/bot, viber/bot, telegram/otp, call/otp, call/act. Пропущено — усі; [] — жодного, лише зведення. Відправлення sms/bulk включаються до sms/single; sms/bulk і pipeline/otp не є окремими каналами статистики.
sms_kindstringНіall (типово) — усі SMS; single — SMS без кампанії; campaign — SMS у кампаніях. Значення single/campaign обмежують вибірку каналом sms/single.
campaign_idintegerНіДодатний ID кампанії вашої компанії. Вибірка обмежується її SMS у заданому періоді. Не поєднується з sms_kind: single.
Тіло POST · JSON
{
  "start": "2026-09-01",
  "finish": "2026-09-21",
  "methods": [
    "sms/single"
  ]
}
Відповідь · HTTP 200 · приклад
{
  "method": "stat/get",
  "success": true,
  "company": "Приклад компанії",
  "period": {
    "start": "2026-09-01",
    "finish": "2026-09-21"
  },
  "methods": [
    "sms/single"
  ],
  "summary": {
    "count": 1,
    "sms_segments": 1,
    "money_spend": 1.25,
    "balance": 1498.75
  },
  "data": [
    {
      "method": "sms/single",
      "count": 1,
      "money_spend": 1.25,
      "segments": 1,
      "records": [
        {
          "id": 1201,
          "date": "2026-09-21 10:00:00",
          "from": "MyBrand",
          "to": "+380671234567",
          "text": "Ваше замовлення готове до отримання.",
          "lifetime": 3600,
          "segments": 1,
          "status": "DELIVERED",
          "status_date": "2026-09-21 10:00:05",
          "price": 1.25,
          "status_text": "Доставлено",
          "campaign_id": null
        }
      ]
    }
  ],
  "campaigns": []
}

Основні поля відповіді

ПолеТипОпис
companystringНазва компанії.
periodobjectДати start і finish.
methodsarray<string>Перелік каналів, включених у відповідь.
summary.countintegerКількість відправлень за період.
summary.sms_segmentsintegerЗагальна кількість частин SMS.
summary.money_spendnumberВитрати за вибраними каналами та періодом.
summary.balancenumberПоточний баланс компанії.
dataarray<object>Групи каналів: method, count, money_spend, records; для SMS також segments.
campaignsarray<object>Кампанії компанії за період: id, name, created_at.
data[].records[].campaign_idinteger | nullID кампанії SMS; null для одиночних.

Особливості використання

  • summary.balance містить поточний баланс на момент запиту, а не залишок на дату finish.
  • data[].records містить записи відповідного каналу. Для пошуку результату відправлення зіставляйте data[].method і records[].id.
  • Пагінація та фільтри за id або одержувачем не передбачені. Для обмеження обсягу відповіді використовуйте період і список каналів.
  • Дати інтерпретуються в часовому поясі сервісу. Часові мітки у відповіді не містять UTC-зміщення.
  • Суми наведено у гривнях. Значення у прикладах ілюстративні; вартість визначається тарифами компанії.
  • Фільтри SMS-кампаній застосовуються до записів та підсумкових сум. Інші канали виключаються при sms_kind: single/campaign або campaign_id.
  • Масив campaigns містить кампанії компанії за період, зокрема без підтверджених відправлень. Він не обмежується фільтром campaign_id; фільтр застосовується до записів у data.
Запит статистики Viber
POST /api/stat/get · JSON
{
  "start": "2026-09-01",
  "finish": "2026-09-22",
  "methods": [
    "viber/bot"
  ]
}

Відправлення містяться у data[].records групи з method: "viber/bot". Поле message_id зберігає рядковий тип.

Приклади інтеграції: stat/get
POSTGET/api/stat/pdfAPI-токен компанії

Експорт статистики у PDF

Формує PDF-звіт за періодом і набором каналів. Параметри відповідають stat/get.

Параметри запиту

ПараметрТипОбов’язковістьОпис
startstringТакПочаток періоду, YYYY-MM-DD, включно.
finishstringТакКінець періоду, YYYY-MM-DD, включно; не раніше start.
methodsarray<string>НіКанали: sms/single, telegram/bot, viber/bot, telegram/otp, call/otp, call/act. Пропущено — усі; [] — жодного, лише зведення. Відправлення sms/bulk включаються до sms/single; sms/bulk і pipeline/otp не є окремими каналами статистики.
sms_kindstringНіall (типово) — усі SMS; single — SMS без кампанії; campaign — SMS у кампаніях. Значення single/campaign обмежують вибірку каналом sms/single.
campaign_idintegerНіДодатний ID кампанії вашої компанії. Вибірка обмежується її SMS у заданому періоді. Не поєднується з sms_kind: single.
Тіло POST · JSON
{
  "start": "2026-09-01",
  "finish": "2026-09-21",
  "methods": [
    "sms/single",
    "telegram/bot"
  ]
}
Відповідь · HTTP 200 · приклад
HTTP 200
Content-Type: application/pdf

%PDF-… (бінарний вміст файлу)

Особливості використання

  • Успішна відповідь має HTTP 200 та Content-Type: application/pdf. Тіло містить бінарні дані файлу.
  • Помилки повертаються у форматі JSON. Перевіряйте HTTP-статус і Content-Type до збереження файлу.
  • Приклади завантаження PDF доступні в розділі «Приклади коду».
  • Фільтри SMS-кампаній застосовуються до записів та підсумкових сум. Інші канали виключаються при sms_kind: single/campaign або campaign_id.
Приклади інтеграції: stat/pdf
POSTGET/api/balance/getAPI-токен компанії

Перевірка балансу

Повертає поточний баланс компанії без періоду й завантаження історії операцій.

Параметри запиту

Параметри не передбачені. Тіло POST-запиту: {}.

Тіло POST · JSON
{}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "balance": 1498.75,
  "currency": "UAH"
}

Основні поля відповіді

ПолеТипОпис
balancenumberПоточний баланс у гривнях.
currencystringUAH — українська гривня.

Особливості використання

  • Компанію визначає API-токен; переданий user_id не змінює компанію.
  • Баланс може бути нульовим або від’ємним. Від’ємне значення означає заборгованість.
  • Це залишок на момент запиту, а не резервування коштів для наступного відправлення.
  • Якщо баланс недоступний, API повертає помилку; недоступний баланс не підміняється нулем.
Приклади інтеграції: balance/get
POSTGET/api/balance/historyAPI-токен компанії

Історія руху коштів

Повертає поповнення та списання за платні відправлення компанії за вибраний період.

Параметри запиту

ПараметрТипОбов’язковістьОпис
startstringТакПочаток періоду, YYYY-MM-DD, включно.
finishstringТакКінець періоду, YYYY-MM-DD, включно; не раніше start.
typestringНіall (типово), credit — поповнення, debit — списання.
offsetintegerНіЗміщення 0–10000000; типово 0. До 50 записів на сторінку.
Тіло POST · JSON
{
  "start": "2026-09-01",
  "finish": "2026-09-21",
  "type": "all",
  "offset": 0
}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "movements": [
    {
      "id": "sms/single:1201",
      "user_id": 7,
      "date": "2026-09-21 10:00:00",
      "type": "debit",
      "amount": 1.25,
      "method": "sms/single",
      "recipient": "+380671234567",
      "comment": null,
      "created_by": null,
      "company_name": "Приклад компанії"
    }
  ],
  "total": 1,
  "summary": {
    "balance": 1498.75,
    "credited": 0,
    "debited": 1.25
  }
}

Основні поля відповіді

ПолеТипОпис
movementsarray<object>Операції: id, user_id, date, type, amount, method, recipient, comment, created_by, company_name.
totalintegerЗагальна кількість операцій з урахуванням фільтра type.
summary.balancenumberПоточний баланс.
summary.creditednumberСума поповнень за період.
summary.debitednumberСума списань за період.

Особливості використання

  • Відповідь містить до 50 операцій. Для наступної сторінки збільшуйте offset на 50; total враховує фільтр type.
  • amount є додатним значенням. Напрям операції визначається полем type: credit або debit.
  • summary.credited і summary.debited обчислюються за весь період незалежно від type. summary.balance містить поточний баланс.
  • Відправлення з нульовою вартістю не створюють записів руху коштів.
  • Дані обмежені компанією, визначеною API-токеном. Передане у запиті поле user_id не змінює область доступу.
Приклади інтеграції: balance/history

Дані компанії

Профіль, тарифи та керування іменами відправника компанії, визначеної API-токеном.

POSTGET/api/auth/meAPI-токен компанії

Профіль компанії

Повертає дані компанії, поточний баланс, тарифи та підтверджені альфаімена.

Параметри запиту

Параметри не передбачені. Тіло POST-запиту: {}.

Тіло POST · JSON
{}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "client": null,
  "account": {
    "id": 7,
    "name": "Приклад компанії",
    "balance": 1500,
    "credit": false,
    "alphanames": [
      "MyBrand"
    ],
    "alphanames_managed": true,
    "tariffs": {
      "sms/single": 1.25
    }
  },
  "csrf_token": null
}

Основні поля відповіді

ПолеТипОпис
account.idintegerІдентифікатор компанії.
account.namestringНазва компанії.
account.balancenumber | nullПоточний баланс у гривнях.
account.creditbooleanОзнака дозволеного кредитування.
account.alphanamesarray<string>Підтверджені альфаімена для SMS.
account.tariffsobjectТарифи з ключами у форматі шляху каналу.
clientobject | nullДані користувача сесії; null для Bearer.
csrf_tokenstring | nullCSRF-токен сесії; null для Bearer.

Особливості використання

  • Для Bearer-авторизації поля client і csrf_token мають значення null.
  • account.balance: null означає, що баланс недоступний; це не нульовий залишок.
  • account.tariffs містить доступні тарифні дані. Порожній об’єкт не слід інтерпретувати як нульову вартість усіх каналів.
  • Відповідь може містити додаткові поля стану підключення: remote, connected, service_error. Секретні токени у профілі не повертаються.
Приклади інтеграції: auth/me
POSTGET/api/settings/alphanamesAPI-токен компанії

Альфаімена компанії

Повертає перелік назв відправника та статуси їх підтвердження.

Параметри запиту

Параметри не передбачені. Тіло POST-запиту: {}.

Тіло POST · JSON
{}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "alphanames": [
    {
      "id": 4,
      "user_id": 7,
      "name": "MyBrand",
      "status": "approved",
      "request_note": "Сервісні повідомлення",
      "review_note": "Підтверджено",
      "created_at": "2026-09-01 10:00:00",
      "updated_at": "2026-09-02 10:00:00",
      "reviewed_at": "2026-09-02 10:00:00"
    }
  ]
}

Основні поля відповіді

ПолеТипОпис
alphanamesarray<object>Перелік заявок і підтверджених назв.
alphanames[].idinteger | stringІдентифікатор запису.
alphanames[].namestringНазва відправника.
alphanames[].statusstringpending або approved.
alphanames[].request_notestringКоментар до заявки.
alphanames[].review_notestringРезультат розгляду заявки.
alphanames[].reviewed_atstring | nullЧас підтвердження; null до підтвердження.

Особливості використання

  • Для SMS допускаються лише альфаімена зі статусом approved. Передавайте назву з тим самим регістром символів.
  • pending означає, що заявка перебуває на розгляді.
  • Для використання відправника потрібне погодження назви у відповідного оператора.
Приклади інтеграції: settings/alphanames
POST/api/settings/alphanames/submitAPI-токен компанії

Додавання альфаімені

Створює заявку на нове ім’я SMS-відправника для компанії власника токена.

Параметри запиту

ПараметрТипОбов’язковістьОпис
namestringТак3–11 символів: латинські літери, цифри, пробіл, крапка, дефіс або підкреслення. Хоча б одна літера. Крайні пробіли видаляються.
request_notestringНіКоментар до заявки, до 1000 символів.
Тіло POST · JSON
{
  "name": "MyBrand",
  "request_note": "Сповіщення інтернет-магазину"
}
Відповідь · HTTP 201 · приклад
{
  "success": true,
  "alphaname": {
    "id": 5,
    "user_id": 7,
    "name": "MyBrand",
    "status": "pending",
    "request_note": "Сповіщення інтернет-магазину",
    "review_note": "",
    "created_at": "2026-10-13 12:00:00",
    "updated_at": "2026-10-13 12:00:00",
    "reviewed_at": null
  }
}

Основні поля відповіді

ПолеТипОпис
alphanameobjectСтворена заявка; формат запису такий самий, як у списку альфаімен.
alphaname.idinteger | stringID для подальшого видалення.
alphaname.statusstringЗавжди pending при створенні.

Особливості використання

  • Нове ім’я завжди має статус pending. API-токен не може самостійно підтвердити ім’я.
  • Використовуйте ім’я для SMS лише після статусу approved у settings/alphanames.
  • Повторна назва в цій компанії повертає HTTP 409 / ALPHANAME_EXISTS. Після втраченої відповіді перевірте список перед повтором.
  • user_id, status і review_note з тіла запиту ігноруються.
Приклади інтеграції: settings/alphanames/submit
POST/api/settings/alphanames/deleteAPI-токен компанії

Видалення альфаімені

Видаляє заявку або підтверджене альфаім’я своєї компанії за його ID.

Параметри запиту

ПараметрТипОбов’язковістьОпис
idinteger | stringТакДодатний ID запису зі settings/alphanames.
Тіло POST · JSON
{
  "id": 5
}
Відповідь · HTTP 200 · приклад
{
  "success": true,
  "deleted_id": 5
}

Основні поля відповіді

ПолеТипОпис
deleted_idintegerID видаленого запису.

Особливості використання

  • Ім’я зникає зі списку всієї компанії; нові SMS із ним будуть відхилені. Уже прийняті відправлення та історія зберігаються.
  • Повернення імені потребує нової заявки та повторного підтвердження.
  • Чужий, відсутній або вже видалений ID повертає HTTP 404 / NOT_FOUND. При повторі власної операції це означає, що запис уже відсутній.
  • Некоректний ID повертає HTTP 400 / INVALID_ID. GET не підтримується: HTTP 405.
Приклади інтеграції: settings/alphanames/delete

Розсилка через Viber

Розсилка виконується послідовністю викликів 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 за номерами телефонів цим методом не підтримується.

Організація черги

  1. Сформуйте список активних підписників. Видаліть дублікати ID без зміни регістру або спеціальних символів. Персоналізуйте текст до відправлення запиту.
  2. Створіть запис для кожної пари «розсилка — одержувач». Зберігайте стан обробки, час спроби та результат, щоб відновлення черги не повторювало підтверджені відправлення.
  3. Надсилайте запити послідовно. Після успіху збережіть id, рядковий message_id та стан прийняття. success: true не підтверджує доставку або прочитання.
  4. Відмови viber_code: 5 і 6 обробляйте для конкретного одержувача. Для коду 6 припиніть надсилання до поновлення підписки.
  5. За 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, ROUTINGSMS прийнято, поставлено в чергу або передано на маршрутизацію.Очікувати подальшого статусу.
SENT, sentКанал прийняв повідомлення до надсилання.Не інтерпретувати як доставку чи прочитання.
DELIVERED, deliveredПровайдер підтвердив доставку.Позначити як доставлене.
READ, readПровайдер підтвердив прочитання.Позначити як прочитане.
EXPIRED, expiredСтрок очікування доставки завершився.Не вважати успішною доставкою.
UNDELIVERABLE, REJECTED, DELETED, INSUFFICIENTFUNDSНедоставка, відмова, скасування або недостатність коштів у каналі.Визначити причину перед повторним надсиланням.
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.
  • Telegram OTP: lifetime, message_id, status, status_date, status_text.
  • Telegram-бот: bot_id, chat_id, text, photo, parse_mode, buttons, message_id, 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 забезпечує надсилання коду. Сервер інтеграції відповідає за його перевірку, строк чинності, кількість спроб і одноразове використання.

  1. Створіть спробу підтвердження, пов’язану з конкретним користувачем, одержувачем і дією.
  2. Згенеруйте код криптографічно стійким генератором або використовуйте код із відповіді telegram/otp, call/otp чи pipeline/otp.
  3. Зберігайте очікуваний код на сервері з обмеженим строком чинності та кількістю спроб. Для коротких кодів використовуйте захищене сховище або HMAC із серверним секретом.
  4. Перевіряйте введене значення на сервері. Після успішної перевірки або завершення строку чинності закривайте спробу.

Очікуваний code не повинен передаватися клієнтському застосунку. У відповіді клієнту достатньо ідентифікатора спроби та результату надсилання. Параметр lifetime каналу не встановлює строк чинності коду у вашій системі.

Для каскаду з call/otp використовуйте код із фактичної відповіді: оператор може сформувати значення, відмінне від переданого. Статус доставки не замінює перевірку OTP.

Callback дзвінка

Метод call/act передає подію на адресу callback_url HTTP-запитом POST із JSON-тілом.

Callback · POST на ваш URL · приклад
{
  "method": "call/act",
  "id": 1205,
  "externalNumber": "+380671234567",
  "internalNumber": "+380441234567",
  "press": 1
}

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 призначений для діагностики; логіка інтеграції має спиратися на код помилки.

Помилка · HTTP 403 · приклад
{
  "success": false,
  "error": {
    "code": "ALPHANAME_NOT_ALLOWED",
    "message": "Для відправлення оберіть підтверджене альфаім’я вашої компанії."
  }
}
HTTP / кодПричинаОбробка
400 · INVALID_JSON, INVALID_FIELDНекоректний JSON або тип поля.Перевірити структуру об’єкта та типи параметрів.
400 · INVALID_PHONE, TEXT_REQUIRED, INVALID_LIFETIMEНекоректні параметри надсилання.Перевірити номер, текст і діапазон lifetime.
400 · OTP_OR_LENGTH_REQUIRED, INVALID_OTP_LENGTHКод або його довжину не задано чи задано некоректно.Передати code із 4–8 цифр або code_length від 4 до 8.
400 · INVALID_BOT_TOKEN, INVALID_CHAT_ID, INVALID_VIBER_IDНекоректний токен бота або ідентифікатор одержувача.Звірити формат із специфікацією відповідного бота.
400 · INVALID_SENDER, INVALID_AVATARНекоректні дані відправника Viber.Перевірити sender.name і URL sender.avatar.
400 · INVALID_TEXT, INVALID_PHOTO, INVALID_BUTTONS, INVALID_PARSE_MODE, MESSAGE_TOO_LARGEНекоректний вміст повідомлення або перевищено обмеження.Перевірити текст, зображення й кнопки. Для Viber не передавати parse_mode.
400 · DATE_RANGE_REQUIRED, INVALID_DATE_FORMAT, INVALID_DATE_VALUE, INVALID_DATE_RANGE, INVALID_DATEНекоректний період звіту.Передати календарні дати у потрібному форматі; start ≤ finish.
400 · INVALID_METHODS, INVALID_METHODS_FORMAT, METHOD_NOT_ALLOWED, INVALID_FILTERНекоректний список каналів або фільтр.Перевірити method/methods, type і offset за специфікацією методу.
401 · UNAUTHORIZED, INVALID_TOKEN, ACCOUNT_DISABLEDАвторизація не пройдена або компанію заблоковано.Перевірити заголовок Bearer, чинність токена та доступ компанії.
402 · INSUFFICIENT_BALANCEНедостатньо коштів.Перевірити баланс і поповнити рахунок.
403 · TOKEN_SCOPE_DENIED, METHOD_UNAVAILABLE, ALPHANAME_NOT_ALLOWEDНедостатні права, канал недоступний або альфаім’я не підтверджено.Перевірити доступ до каналу й статус відправника.
404 / 405Шлях не знайдено або HTTP-метод не підтримується.Перевірити адресу /api/{method} і дозволений HTTP-метод.
400 / 409 · INVALID_ALPHANAME, ALPHANAME_EXISTSНекоректна або вже зареєстрована назва.Перевірити формат і список альфаімен.
404 · NOT_FOUNDАльфаім’я відсутнє або належить іншій компанії.Оновити список альфаімен і перевірити ID.
413 / 415Перевищено розмір тіла або некоректний Content-Type.Зменшити запит або встановити application/json.
422 · DELIVERY_NOT_POSSIBLETelegram OTP недоступний для номера.Використати інший канал або каскад.
422 · VIBER_REJECTEDViber відхилив повідомлення.Перевірити error.viber_code за таблицею Viber.
429 · ACCOUNT_BUSY, RATE_LIMIT_EXCEEDEDКомпанія має незавершену операцію або канал обмежив частоту запитів.Призупинити чергу; врахувати error.retry_after, якщо поле присутнє.
502 · DELIVERY_FAILEDЖоден крок каскаду не підтвердив надсилання.Перевірити last_error і статистику перед повтором.
Помилки каналів · REQUEST_ERROR, OPERATOR_REJECTED, OPERATOR_REJECTED_HTTP, TELEGRAM_REJECTED, VIBER_REJECTED, INVALID_RESPONSEВідмова провайдера, помилка зв’язку або неочікувана відповідь.Перевірити код, додаткові поля та результат операції. HTTP-статус залежить від каналу.
502 · SERVICE_AUTH_FAILED, SERVICE_UNAVAILABLE, SERVICE_INVALID_RESPONSEПомилка взаємодії із сервісом доставки.Уточнити результат відправлення; передати підтримці метод, час і код помилки.
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. Метод перевіряє доступ і повертає профіль компанії без платної операції надсилання.