Огляд BSG WhatsApp API

Цей посібник ознайомить вас із надсиланням повідомлень WhatsApp через BSG API: як проходити автентифікацію, які є методи надсилання та для чого призначений кожен із них, як формується запит на template і як відстежувати доставку. Він містить посилання на конкретні методи OneAPI із деталями запиту/відповіді — на сторінці кожного методу наведено повний перелік параметрів і приклади, а перевірити виклики можна в Swagger explorer.

Швидкий старт

Виконайте ці кроки послідовно для першого надсилання або перейдіть до будь-якого з них:

1. Автентифікація — обміняйте свій API key на bearer token.
2. Виберіть метод надсилання — single, campaign або universal.
3. Сформуйте запит на template — назва, мова та значення параметрів.
4. Відстеження доставки — через callback або перевірку статусу.

Також на цій сторінці: SMS fallback · Обробка помилок · Читання даних вашого акаунта.

Перш ніж почати

Вам знадобиться:

• Підключений WhatsApp Business Account (WABA) — якщо ви ще не підключили жодного, почніть із Початок роботи з 1-way WhatsApp на BSG.
• Щонайменше один схвалений template (створений у Meta WhatsApp Manager та синхронізований у BSG).
• Ваш Live API key — із Management → Integrations & API → SMPP/API – password у BSG cabinet.

Base URL: https://one-api.bsg.world

1. Автентифікація

Обміняйте свій API key на bearer token (JWT), потім надсилайте його в заголовку Authorization: Bearer <JWT> у кожному наступному запиті. Токен має обмежений термін дії, тож за потреби оновлюйте його. Ваш Live key надсилає реальні повідомлення; Test key повертає зразкові дані для розробки вашої інтеграції (без реальних надсилань і без списань).

→ Receive JWT token · Refresh JWT token

2. Виберіть метод надсилання

Три методи, залежно від вашого сценарію використання — усі надсилають схвалені templates (type: template):

Виберіть single для транзакційних разових повідомлень, campaign для масових/запланованих надсилань і universal, якщо ви інтегруєте WhatsApp як один із каналів у багатоканальному потоці. Надайте кожному отримувачу reference_id, щоб згодом зіставляти оновлення про доставку. Надсилання повертає status: accepted — фінальна доставка надходить через callback або перевірку статусу (Розділ 5).

3. Сформуйте запит на template

Надсилання template повторює структуру самої Meta — BSG передає ваші components до Meta, тож ви формуєте ту саму структуру, яку очікує WhatsApp:

• name та language.code ідентифікують схвалений template.
• components — це масив типізованих частин: body (ваші текстові параметри, за порядком), header (опційно — текст або медіа) та button (динамічні значення для кнопок URL / quick-reply / copy-code, які адресуються через sub_type та index).
• Типи параметрів включають text, а також currency та date_time для локалізованих значень.
• Ви надсилаєте лише значення параметрів; фіксований текст template, кнопки та структура беруться зі схваленого визначення в Meta.

Щоб знайти назву template, мову та параметри, скористайтеся Search WhatsApp templates та Get WhatsApp template. Точна структура components/parameters задокументована на сторінках методів надсилання, наведених вище.

Медіа-заголовки: якщо template має заголовок із зображенням, відео чи документом, надайте медіа під час надсилання всередині компонента header — або як публічний HTTPS URL, який ви розміщуєте самостійно, або як media id, наданий BSG (ніколи не власний media id Meta). Дотримуйтесь обмежень розміру Meta (зображення 5 MB / відео 16 MB / документ 100 MB).

4. SMS fallback (опційно)

Якщо повідомлення WhatsApp не доставлено, BSG може автоматично повторно надіслати його як SMS — це корисно для термінових повідомлень, як-от OTP. Додайте об’єкт alternative_channel.sms (текст SMS + sender, опційно термін дії та перевірка stop-list) до свого запиту на надсилання; пропустіть його для надсилання лише через WhatsApp. SMS тарифікується окремо BSG за його SMS-тарифами. Точні поля наведено на сторінках Send Single WhatsApp Message та Send WhatsApp campaign.

5. Відстеження доставки

Через callback. Встановіть Callback URL For WhatsApp у Integrations & API (або callback_url для окремого запиту при single-надсиланні). У міру проходження кожного повідомлення BSG надсилає оновлення, що містить BSG message id, ваш reference, поточний статус та — у разі невдачі — код помилки. Single-надсилання та campaigns використовують ту саму структуру, і ви отримуєте одне оновлення на кожну зміну статусу (наприклад, accepted → delivered). Переадресація вхідних повідомлень/кнопок надходитиме на цей самий URL у майбутньому. Точний payload і поля дивіться у Callback-и WhatsApp на BSG.

Значення статусу: scheduled, moderation, accepted, sending, sent, delivered, read, expired, failed, undelivered, unknown.

Або запитуйте статус. Знайдіть повідомлення за вашим reference_id, за campaign_id (усі повідомлення в campaign) або за BSG message id — див. Get Single Message Info.

6. Обробка помилок

BSG дзеркалить коди помилок Meta (наскрізна передача, без переінтерпретації). Швидка діагностика: rejected означає, що потрібно щось виправити на боці запиту (некоректні параметри, ліміт або білінг — наприклад, BSG code 99 = ліміт балансу/тарифу); undeliverable означає, що запит був коректним, але повідомлення не змогло досягти отримувача. HTTP 429 означає надто часті/дубльовані запити — зробіть паузу та повторіть спробу. Найімовірніші коди та способи їх усунення дивіться у Поширені помилки WhatsApp API (надсилання).

7. Читання даних вашого акаунта

Керуйте campaign (список, деталі, розрахунок ціни, зупинка) за допомогою універсальних методів Campaign. Зверніть увагу, що призупинення або зупинка campaign наразі завершує цей запуск, а не відновлює його самостійно; коли будете готові продовжити, запустіть нову campaign для отримувачів, яких ви ще хочете охопити.

Корисно знати

• Templates керуються в Meta. BSG синхронізує їх лише для читання (приблизно щогодини); створюйте та редагуйте їх у WhatsApp Manager або через API Meta.
• Пропускна здатність висока (порядку ~1 000 повідомлень/сек); також діють ліміти Meta на рівні portfolio — див. Ліміти WhatsApp на BSG.
• SDKs доступні для PHP, Node.js, Go, Python, Ruby та Java — див. SDK documentation.

Наступні кроки та пов’язані посібники

• Початок роботи з 1-way WhatsApp на BSG — підключіть свій WABA та налаштуйте callback.
• Callback-и WhatsApp на BSG — payload і поля callback зі статусом доставки.
• Поширені помилки WhatsApp API (надсилання) — найпоширеніші помилки надсилання та способи їх усунення.
• Як підключити BSG як паралельного другого провайдера на Whatsapp — перевірте BSG паралельно з вашим поточним провайдером.
• Повна довідка: BSG API documentation · Swagger explorer.