Gateway API: өз сервисіңізді қосу

WhatsApp хабарламаларын Dialogs арқылы қабылдап, жіберіңіз. Сервис, бот немесе n8n сценарийі бір API-ге қосылады: хабарламалар сіздің вебхугыңызға келеді, жауаптар 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 немесе клиент генераторына импорттауға болады.

Gateway API OpenAPI сипаттамасы

Арналар тізімі. 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) қосылу тәсілін көрсетеді; ол арна күйін тексеруді алмастырмайды.