Руководство по интеграции API сообщений: REST, SMPP, вебхуки

Это руководство предназначено для backend-разработчиков, архитекторов решений и технических директоров, которые интегрируют приложение с провайдером сообщений для WhatsApp, SMS или email. В нём объясняется, какой интерфейс выбрать и как организовать аутентификацию, идемпотентность, отчёты о доставке, повторы, лимиты запросов и тестирование; приведены условные примеры запросов и ответов. О синхронизации диалогов с CRM читайте в сопутствующем руководстве по подключению CRM через вебхуки.

Какой интерфейс выбрать: REST, SMPP или вебхуки?

Используйте REST для отправки, вебхуки — для приёма, а SMPP — только для массовых SMS-рассылок большого объёма, если вы уже работаете по SMPP. Эти интерфейсы дополняют друг друга, а не конкурируют: большинство интеграций сочетают исходящие вызовы REST и входящие вебхуки.

Сессии SMPP (Short Message Peer-to-Peer) начинаются с bind (transmitter, receiver или transceiver), сообщения отправляются командой submit_sm, отчёты о доставке и входящие SMS приходят через deliver_sm, а соединение поддерживается командой enquire_link. Протокол эффективен, но в эксплуатации сложнее, чем HTTPS.

Как организовать аутентификацию?

Используйте самый надёжный метод, который предлагает провайдер, не храните секреты в коде и аутентифицируйте оба направления.

• Исходящие вызовы: API-ключи или bearer-токены OAuth 2.0 в заголовке Authorization поверх TLS. Храните их в менеджере секретов и ротируйте по расписанию, а также после смены сотрудников.
• SMPP: system ID и пароль при bind, как правило, с ограничением по списку разрешённых IP-адресов и, где это поддерживается, поверх TLS.
• Входящие вебхуки: проверяйте подпись каждого события. Meta подписывает payload вебхуков WhatsApp Cloud API подписью HMAC-SHA256 в заголовке X-Hub-Signature-256, вычисляемой с секретом вашего приложения; провайдеры обычно предлагают похожую схему. Вычисляйте подпись по необработанному телу запроса до его разбора.

Используйте отдельные учётные данные для каждой среды, чтобы утёкший тестовый ключ не мог отправлять боевой трафик.

Как безопасно отправить сообщение?

Отправляйте через очередь, передавайте ключ идемпотентности и воспринимайте ответ как «принято», а не «доставлено».

Пример запроса на отправку

Структура ниже — это псевдо-JSON для иллюстрации, а не API конкретного провайдера.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Пример ответа

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Сразу сохраняйте message_id вместе с вашим собственным идентификатором. Всё, что произойдёт дальше, приходит асинхронно.

Почему важна идемпотентность?

Потому что сети дают тайм-аут уже после того, как сервер выполнил действие. Если запрос на отправку завершился тайм-аутом и вы повторяете его вслепую, клиент может получить два OTP-кода (одноразовых кода) или два уведомления об отправке. Ключ идемпотентности позволяет серверу распознать повтор и вернуть исходный результат.

Правила, которые работают:

1. Формируйте ключ из бизнес-события (например, ID заказа плюс тип события), а не из случайного значения для каждой попытки.
2. Используйте один и тот же ключ для всех повторов одной и той же отправки.
3. Делайте ключи достаточно долгоживущими, чтобы они покрывали окно ваших повторов.
4. Если провайдер не поддерживает ключи, дедуплицируйте отправки на своей стороне до вызова API.

Проект стандарта IETF для заголовка Idempotency-Key закрепляет этот паттерн для HTTP API; реализации у провайдеров различаются, поэтому читайте их документацию.

Как работают отчёты о доставке?

Статус доставки приходит позже в виде событий: через вебхуки для WhatsApp и большинства REST API и через отчёты deliver_sm в SMPP. Значения статусов зависят от канала; каждый из них разобран в нашем руководстве по статусам доставки сообщений.

Пример вебхука со статусом

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Обрабатывайте события статусов с запасом прочности:

• Дедуплицируйте по event_id либо по ID сообщения и статусу.
• Не допускайте отката: не переводите сообщение из «прочитано» обратно в «доставлено», если события пришли не по порядку.
• Быстро отвечайте 2xx, а обработку выполняйте из очереди.
• Записывайте коды ошибок для недоставленных сообщений и решайте, какие из них допускают повтор.
• Ожидайте пропусков: некоторые SMS-маршруты возвращают ограниченные отчёты, а статус «прочитано» зависит от канала и настроек пользователя.

Как обрабатывать повторы и лимиты запросов?

Повторяйте только то, что может завершиться успехом, делайте экспоненциальную задержку с джиттером и учитывайте сигналы сервера.

RFC 9110 определяет заголовок Retry-After, который может содержать секунды или дату. Поставьте на своей стороне ограничитель скорости перед отправкой, чтобы укладываться в документированные лимиты провайдера, а не узнавать о них по ошибкам. У WhatsApp есть и лимиты на стороне Meta на количество уникальных клиентов, которым можно писать; они описаны в статье о лимитах сообщений и рейтинге качества.

Как тестировать перед запуском?

Проверяйте сценарии сбоев, а не только «счастливый путь».

Чек-лист перед запуском в production

1. Отправьте каждый шаблон со значениями реальной длины, включая текст на арабском.
2. Спровоцируйте тайм-аут и убедитесь, что повтор не создаёт дубликат.
3. Отправьте сообщение на неверный номер и убедитесь, что ошибка обработана без повтора.
4. Воспроизведите вебхук дважды и не по порядку; убедитесь, что итоговое состояние одно.
5. Отправьте вебхук с неверной подписью и убедитесь, что он отклонён.
6. Вызовите ответы 429 нагрузочным тестом в песочнице, если это разрешено.
7. Выполните ротацию API-ключа и убедитесь, что простоя нет.
8. Проверьте, что в логах есть ID сообщений, но нет полного текста сообщений и OTP-кодов.
9. Проведите небольшой пилот в production с внутренними номерами в каждом канале.

Песочницы редко в точности воспроизводят поведение операторов и Meta, поэтому продолжайте мониторинг в первые недели работы в production.

Рабочий пример: сервис OTP и уведомлений о заказах

«Qafilah Logistics» (условный пример) — компания по доставке посылок в Саудовской Аравии — отправляет обновления по заказам в WhatsApp с резервным каналом (fallback) в виде SMS, а также аутентификационные OTP-коды.

• Архитектура: события заказов попадают в очередь; рабочий процесс отправки вызывает REST API с ключом идемпотентности shipment-id:event.
• Резервный канал: если WhatsApp возвращает статус сбоя для пользователя без WhatsApp, процесс отправляет SMS с новым ключом shipment-id:event:sms.
• OTP: коды быстро истекают, поэтому отправки OTP не повторяются после окончания срока действия; вместо этого пользователь запрашивает новый код. См. руководство по аутентификационным сообщениям с OTP.
• Отчёты о доставке: приёмник вебхуков проверяет подписи, дедуплицирует события и обновляет таблицу статусов, которая никогда не откатывается назад.
• Лимиты: ограничитель token bucket удерживает скорость отправки по каждому каналу ниже документированных лимитов.

Какие ошибки интеграции встречаются чаще всего?

• Воспринимать «принято» как «доставлено».
• Использовать новый ключ идемпотентности при каждой попытке повтора.
• Выполнять тяжёлую обработку прямо в запросе вебхука.
• Пропускать проверку подписи вебхуков.
• Повторять в цикле запросы с ошибками валидации 4xx.
• Логировать OTP-коды и полное содержимое сообщений.
• Использовать боевые учётные данные в тестовых средах.

Чем помогает OmniChannels.ai

OmniChannels.ai на базе BroadNet Technologies предлагает публично документированный REST/JSON API со спецификацией OpenAPI 3.1 и TypeScript SDK. API охватывает SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, email и push, включая аутентификационные шаблоны WhatsApp с OTP-кодами (одноразовыми кодами) one-tap, zero-tap и copy-code. Вебхуки передают статусы доставки в едином нормализованном формате, SMPP 3.4 поверх TLS обслуживает массовые SMS-рассылки большого объёма, а MCP-сервер подключает ИИ-агентов. Отчёты о доставке с фильтрами и экспортом в CSV помогают сверить то, что отправила ваша интеграция. Начните с документации для разработчиков и краткого руководства по запуску.