Gateway API — подключаем свой сервис

Единый API: принимайте и отправляйте сообщения WhatsApp через Dialogs. Любой сервис, бот или сценарий n8n подключается к одному шлюзу — входящие приходят на ваш вебхук, ответы уходят одним POST.

База — https://dialogs.tehprof.kz/api/v1/gw/. Каждый запрос авторизуется заголовком Authorization: Bearer gw_… с вашим ключом.

Быстрый старт — пять шагов:

  1. Ключ. Владелец или администратор открывает Настройки → API, создаёт ключ: название, хотя бы одна линия и хотя бы одно право. Ключ gw_… показывается один раз — сразу сохраните его в своём сервисе. Отозвать ключ можно там же.
  2. GET /channels/ — узнайте channel_id своих линий.
  3. PUT /webhook/ — зарегистрируйте свой URL, в ответ придёт hmac_secret для проверки подписи.
  4. Принимайте входящие на свой URL и сверяйте подпись X-Wahub-Signature-V2.
  5. Отвечайте через POST /messages/.

Права ключа. channels:read — список линий; messages:read — история и итог отправки; messages:send — отправка и загрузка файлов; templates:read и templates:write — чтение и изменение шаблонов; webhooks:manage — вебхук, подписки, добор и повтор доставок. GET /allowed/ требует messages:send и templates:read. Запрос без нужного права вернёт 403 forbidden. Ключ видит только выбранные линии: остальные для него не существуют и дают 404 channel_not_found.

Полное описание шлюза в формате OpenAPI открыто без входа: https://dialogs.tehprof.kz/api/v1/gw/schema/ (YAML, для JSON добавьте ?format=json). Его можно импортировать в Postman, Insomnia или генератор клиента.

OpenAPI-описание Gateway API

Список каналов. GET /channels/ возвращает подключённые номера — их channel_id нужен для отправки:

curl https://dialogs.tehprof.kz/api/v1/gw/channels/ \
  -H "Authorization: Bearer gw_xxx"

{
  "channels": [
    { "channel_id": "32", "chat_type": "whatsapp",
      "plain_id": "77010001122", "state": "healthy",
      "connection_mode": "cloud" }
  ]
}

Проверяйте состояние канала перед отправкой. healthy — подключён без предупреждений. degraded_quality, degraded_ratelimit и degraded_transient — отправка ещё доступна, но возможны ограничения, задержки или временные отказы; учитывайте предупреждение и проверяйте статус сообщения. requires_reauth, soft_disconnected и hard_disconnected — отправка недоступна до восстановления подключения. Незнакомое значение считайте недоступным для отправки. connection_mode (cloud, coexistence) описывает способ подключения и не заменяет проверку состояния.