Як надіслати першу SMS через API за 5 хвилин – повний посібник
Більшість «SMS-шлюзів» потребують днів на запуск: заявка, договір, розмова з менеджером, власний SDK. Ми йдемо іншим шляхом – першу SMS через API ви надішлете за 5 хвилин: створіть акаунт, згенеруйте токен, зробіть один HTTP-запит. У цьому посібнику пройдемо весь шлях: від акаунта через робочий код чотирма мовами до вебхуків, ідемпотентності та обробки помилок – речей, що вирішують успіх у продакшні.
Крок 1: акаунт і Bearer Token
Створіть акаунт на сторінці реєстрації – отримаєте 100 безкоштовних SMS, без картки й без договору. Активація миттєва. У панелі в Налаштування → API → Згенерувати створіть Bearer Token. Поводьтеся з ним як із паролем – у змінних середовища (напр. ACTIO_TOKEN), ніколи в репозиторії чи у фронтенді. У разі витоку відкличте його в панелі й згенеруйте новий.
Крок 2: перший запит (curl)
Найшвидший тест – один виклик із терміналу. Endpoint приймає JSON і повертає Message ID та статус:
curl -X POST https://msg-api.actio.pl/api/sms \
-H "Authorization: Bearer $ACTIO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "ВашБренд",
"to": "48732129000",
"body": "Ваш код входу: 482910"
}'Працюють три поля: from (ім’я відправника або номер у E.164), to (отримувач у E.164 без «+») і body (текст UTF-8). Повний опис із необов’язковими полями, як-от scheduled_at та idempotency_key, є в документації.
Крок 3: інтеграція у ваш стек
API – це чистий REST і працює з будь-якою мовою, що вміє HTTP, без закритих бібліотек. У Node.js достатньо вбудованого fetch, у Python – requests.post(...), у PHP – cURL, у Go – стандартний net/http. Готові сніпети п’ятьма мовами є в документації – скопіюйте, замініть токен, готово.
Крок 4: вебхуки замість опитування
Надіслати SMS – це лише пів справи; ви хочете знати, чи вона дійшла. Замість опитувати API в циклі, налаштуйте вебхук: вкажіть свій URL, і ми надішлемо подію за кожної зміни статусу – sms.delivered, sms.failed, sms.expired, sms.bounced. Payload містить message_id, мітку часу й мережу отримувача, тож ваша система реагує в реальному часі.
Ідемпотентність і обробка помилок
У продакшні важлива стійкість до повторів. Якщо ваш сервер надішле той самий запит двічі (таймаут, повтор черги), без захисту отримувач дістане дві SMS. Рішення – поле idempotency_key (UUID v4): той самий ключ гарантує рівно одну доставку. Обробляйте також типові коди статусу: 401 (хибний токен), 402 (немає коштів), 422 (невалідний номер/текст), 429 (ліміт – дивіться заголовок Retry-After).
Один API, три поширені сценарії
Той самий API покриває три дуже різні сценарії без зміни інтеграції: транзакційні сповіщення, коди 2FA/OTP та масові кампанії на тисячі отримувачів. Оплата pay-as-you-go, без підписки й порогу входу – тариф під ваш обсяг дивіться в цінах.
FAQ
Чи потрібен договір, щоб протестувати API?+
Ні. Ви реєструєтеся за email, отримуєте 100 безкоштовних SMS і тестуєте одразу – без договору й без картки.
Якими мовами є приклади коду?+
curl, Node.js, Python, PHP і Go – усі в документації, готові до копіювання.
Як дізнатися, що SMS доставлено?+
Вебхук надсилає на ваш URL подію за кожної зміни статусу (delivered, failed, expired, bounced) – у реальному часі й без доплат.
Як уникнути подвійного надсилання при повторі?+
Використовуйте поле idempotency_key (UUID v4). Той самий ключ гарантує рівно одну доставку навіть за кількох запитів.