Хабарлама жіберу

POST /messages/ сұрауында text, файл немесе template беріңіз. Файлға text қолтаңба ретінде қосылады; template мәтінмен де, файлмен де бірге берілмейді. Өз client_msg_id мәніңіз сұрауды қайталауға мүмкіндік береді: сол мәнмен және сол денемен қайталасаңыз, бұрынғы message_id қайтады, екінші хабарлама жасалмайды; сол client_msg_id басқа денемен 409 idempotency_conflict қайтарады. chat_type міндетті емес: жеткізу тәсілін арна анықтайды. Оны берсеңіз және мәні арнаға сәйкес келмесе, сұрау қабылданбайды. reply_to тек осы диалогтегі хабарламаның message_id мәнін қабылдайды.

curl -X POST https://dialogs.tehprof.kz/api/v1/gw/messages/ \
  -H "Authorization: Bearer gw_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "32",
    "chat_type": "whatsapp",
    "chat_id": "77010009988",
    "client_msg_id": "order-42-reply",
    "text": "Заказ принят, спасибо!"
  }'

201 { "message_id": "msg_7f3c" }

Файлдар. Алдымен файлды жүктеңіз: POST /media/, file өрісінде (multipart/form-data), 100 МБ-қа дейін. Жауапта media_url, file_name және file_mimetype келеді; үшеуін де POST /messages/ сұрауына беріңіз. Сыртқы сілтемелердегі файлдарды біз жүктемейміз. Файл қоймасының квотасы таусылса, 413 storage_quota_exceeded келеді. note: true бейнені дөңгелек етіп, voice: true аудионы дауыстық хабарлама етіп жібереді.

curl -X POST https://dialogs.tehprof.kz/api/v1/gw/media/ \
  -H "Authorization: Bearer gw_xxx" \
  -F "file=@invoice-42.pdf"

201 { "media_url": "/media/17/2de7….pdf",
      "file_name": "invoice-42.pdf",
      "file_mimetype": "application/pdf" }

curl -X POST https://dialogs.tehprof.kz/api/v1/gw/messages/ \
  -H "Authorization: Bearer gw_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "32",
    "chat_id": "77010009988",
    "client_msg_id": "invoice-42",
    "text": "Шот тіркемеде",
    "media_url": "/media/17/2de7….pdf",
    "file_name": "invoice-42.pdf",
    "file_mimetype": "application/pdf"
  }'

Жауап жоғалды. Желі үзіліп, жіберудің қабылданғанын білмесеңіз, POST сұрауын сол client_msg_id мәнімен қайталаңыз немесе GET /commands/<client_msg_id>/ арқылы сұраңыз. outcome: accepted (қабылданды), sending (жіберілуде), sent (мессенджерге берілді), rejected (қабылданбады), unknown (мессенджердегі нәтиже белгісіз — statuses ағынын қараңыз). delivery_status — ағымдағы жеткізу күйі; failed кезінде қасында себебі бар error келеді (statuses ағынындағыдай). 404 — бұл кілтпен мұндай жіберу болмаған.

curl https://dialogs.tehprof.kz/api/v1/gw/commands/order-42-reply/ \
  -H "Authorization: Bearer gw_xxx"

200 { "client_msg_id": "order-42-reply", "message_id": "msg_7f3c",
      "outcome": "sent", "delivery_status": "delivered" }

201 жауабы хабарламаның жіберуге қабылданғанын білдіреді; бұл жеткізілгенін растамайды. WABA төлемі жоқ немесе нөмір бұғатталған болса, кейін statuses ағынында failed күйі келеді. Жеткізілуін HTTP жауап кодымен емес, хабарлама күйімен тексеріңіз.

24 сағаттық мерзім аяқталғанда мақұлданған шаблон жіберуге болады. Кәдімгі мәтін жіберілмейді. POST /messages/ сұрауында text және media_url орнына template: { name, language, params? } беріңіз. template өрісін text немесе media_url өрістерімен бірге қолдануға болмайды. params ішіндегі body және header массивтері {{1}}, {{2}} айнымалыларының мәндерін береді:

curl -X POST https://dialogs.tehprof.kz/api/v1/gw/messages/ \
  -H "Authorization: Bearer gw_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "32",
    "chat_type": "whatsapp",
    "chat_id": "77010009988",
    "client_msg_id": "order-42-tpl",
    "template": {
      "name": "order_shipped",
      "language": "ru",
      "params": { "body": ["A-42", "DHL"] }
    }
  }'

201 { "message_id": "msg_7f3c" }

Қазір не жіберуге болатынын GET /allowed/?channel_id=&chat_id= сұрауымен тексеріңіз. 24 сағатты өз сервисіңізде қайта есептемеңіз. mode: free_text кәдімгі мәтінді жіберуге болатынын, expires_in_seconds қалған уақытты көрсетеді; арнада мұндай шектеу болмаса, мәні null болады. mode: templates кезінде кәдімгі мәтін жіберілмейді; templates өрісінде қолдануға болатын мақұлданған шаблондар көрсетіледі. Мерзімді тек клиенттен келген жаңа хабарлама ұзартады, сіздің жауабыңыз ұзартпайды. Әр нөмірдің мерзімін бөлек тексеріңіз. Бұл GET сұрауы жаңа диалог жасамайды.

curl "https://dialogs.tehprof.kz/api/v1/gw/allowed/?channel_id=32&chat_id=77010009988" \
  -H "Authorization: Bearer gw_xxx"

# окно открыто
200 { "mode": "free_text", "expires_in_seconds": 6000, "templates": [] }

# окно закрыто — свободный текст нельзя, только эти шаблоны
200 {
  "mode": "templates",
  "expires_in_seconds": 0,
  "templates": [
    { "template_id": "123", "name": "order_shipped",
      "language": "ru", "status": "APPROVED", "category": "UTILITY" }
  ]
}

Хат алмасу тарихы. GET /messages/?channel_id=&chat_id= интеграцияңыз қосылмай тұрып келген немесе сервисіңіз жұмыс істемеген кезде өткізіп алған хабарламаларды береді. Хабарламалар жаңадан ескіге қарай ішкі ретімен орналасады; рет уақыт белгісіне тәуелді емес. Келесі ескі бет үшін жауаптағы next_before_id мәнін before_id параметрі ретінде беріңіз. Бос next_before_id диалогтің басына жеткеніңізді білдіреді. Беттерді уақыт бойынша сұрамаңыз. limit шегі — 200, әдепкі мәні — 50.

curl "https://dialogs.tehprof.kz/api/v1/gw/messages/?channel_id=32&chat_id=77010009988&limit=50" \
  -H "Authorization: Bearer gw_xxx"

200 {
  "messages": [
    { "message_id": "8842", "channel_id": "32",
      "chat_type": "whatsapp", "chat_id": "77010009988",
      "direction": "incoming", "source": "customer",
      "text": "Где мой заказ?", "content_type": "text",
      "media_url": "", "file_name": "", "file_mimetype": "",
      "reply_to": "", "sender_name": "Айгерим",
      "sender_phone": "77010009988", "metadata": {}, "edited": false,
      "timestamp": "2026-08-08T09:12:44.512000+00:00",
      "status": "delivered" }
  ],
  "next_before_id": "8842"
}

Тарихтағы хабарлама messages вебхугындағы объектімен бірдей; оған timestamp (хабарламаны сақтаған уақыт) және status (ағымдағы жеткізілу күйі) қосылады. Бір өңдеушіні вебхукке де, тарихқа да қолдануға болады. Реакциялар мен жіберуші бәріне өшірген хабарламалар тарихқа кірмейді. Бұл арнаға ешқашан жазбаған нөмір үшін қате емес, бос тізім қайтады.