API арқылы үлгісіз мәзір мен батырмалар

Үлгісіз мәзір мен жауап батырмалары

POST /v1/messages/send арқылы клиентке интерактивті хабарлама жіберуге болады: тізім-мәзір немесе жауап батырмалары. Бұл үшін үлгі де, Meta мақұлдауы да қажет емес. Чат-боттар үшін ыңғайлы: клиент «Старт» деп жазады, ботыңыз жауап ретінде мәзірді көрсетеді.

Екі түрі

type	Клиент не көреді	Нұсқа саны
list	Хабарлама астында бір батырма, мысалы «Мәзірді ашу». Басқанда тізім ашылады, клиент бір тармақты таңдайды	10-ға дейін
buttons	Батырмалар хабарлама мәтінінің дәл астында	3-ке дейін

Клиентте қалай көрінеді

Мәзірі бар хабарлама: тақырып, мәтін, қолтаңба және «Мәзірді ашу» батырмасы.

Басқанда тармақтар тізімі ашылады. Сол жақта телефон, оң жақта компьютердегі WhatsApp.

Клиент тармақты басады, ал оның таңдауы тармақтың id-імен вебхугіңізге келеді.

Қашан жіберуге болады

• Тек WhatsApp Business API желілерінде (whatsapp_waba). Басқа желілер үшін API 400 қатесін қайтарады.
• Тек клиенттің соңғы хабарламасынан кейін 24 сағат ішінде. Бұл WhatsApp ережесі: терезеден тыс тек үлгі жіберуге болады. Терезе жабылса, WhatsApp хабарламаны қабылдамайды, ал мәртебе вебхугіне қате келеді.
• Тізім-мәзірді үлгіге және жаппай таратуға қосуға болмайды, бұл да WhatsApp ережесі. Үлгіде 10-ға дейін жылдам жауап батырмасын жасауға болады: кабинеттегі «Үлгілер» бөлімі.

URL

POST https://api.wazzabee.com/api-gateway/v1/messages/send

Тақырыптар

Authorization: Bearer СІЗДІҢ_API_КІЛТІҢІЗ
Content-Type: application/json

interactive өрісінің параметрлері

Параметр	Түрі	Міндетті	Сипаттама
type	string	✅	list немесе buttons
body	string	✅	Хабарлама мәтіні: мәзірде 4096 таңбаға дейін, батырмаларда 1024-ке дейін
header	string	Жоқ	Мәтін үстіндегі тақырып, 60 таңбаға дейін
footer	string	Жоқ	Мәтін астындағы ұсақ жазу, 60 таңбаға дейін
button	string	list үшін ✅	Мәзірді ашатын батырма жазуы, 20 таңбаға дейін
rows	array	list үшін ✅*	Мәзір тармақтары: id 200 таңбаға дейін, title 24-ке дейін, description 72-ге дейін (міндетті емес). Барлығы 10 тармаққа дейін
sections	array	list үшін ✅*	Бөлімдерге топталған тармақтар: { "title": "...", "rows": [...] }. 10 бөлімге дейін, атауы 24 таңбаға дейін, бөлім біреуден көп болса міндетті. Барлығы 10 тармаққа дейін
buttons	array	buttons үшін ✅	1-ден 3-ке дейін батырма: id 256 таңбаға дейін, title 20-ға дейін

* Мәзір үшін rows немесе sections жіберіңіз.

interactive өрісін text, mediaUrl және templateName өрістерімен бірге жіберуге болмайды: хабарлама мәтіні interactive.body ішіне жазылады. Тармақтар мен батырмалардың id-і, сондай-ақ батырма жазулары қайталанбауы керек. Сұраудың басқа өрістері (channelId, chatId, campaignId, senderName, automated) әдеттегідей жұмыс істейді, қараңыз: Хабарламаларды жіберу.

Мысал: алты тармақты мәзір

curl -X POST "https://api.wazzabee.com/api-gateway/v1/messages/send" \
  -H "Authorization: Bearer СІЗДІҢ_API_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "желіңіздің-uuid",
    "chatId": "77071234567",
    "interactive": {
      "type": "list",
      "header": "Басты мәзір",
      "body": "Сәлеметсіз бе! Сізді не қызықтыратынын таңдаңыз",
      "footer": "9:00-ден 19:00-ге дейін жұмыс істейміз",
      "button": "Мәзірді ашу",
      "rows": [
        { "id": "prices", "title": "Бағалар", "description": "Тарифтер мен құны" },
        { "id": "catalog", "title": "Каталог" },
        { "id": "delivery", "title": "Жеткізу және төлем" },
        { "id": "order_status", "title": "Тапсырыс мәртебесі" },
        { "id": "address", "title": "Мекенжай мен кесте" },
        { "id": "manager", "title": "Менеджермен байланыс" }
      ]
    }
  }'

Мысал: бөлімдері бар мәзір

"interactive": {
  "type": "list",
  "body": "Қызметті таңдаңыз",
  "button": "Қызметтер",
  "sections": [
    { "title": "Шаш қию", "rows": [
      { "id": "cut_men", "title": "Ерлерге" },
      { "id": "cut_women", "title": "Әйелдерге" }
    ]},
    { "title": "Бояу", "rows": [
      { "id": "color_full", "title": "Толық бояу" }
    ]}
  ]
}

Мысал: жауап батырмалары

"interactive": {
  "type": "buttons",
  "body": "Ертең сағат 10:00-ге жазылуды растайсыз ба?",
  "buttons": [
    { "id": "confirm", "title": "Иә, барамын" },
    { "id": "reschedule", "title": "Ауыстыру" },
    { "id": "cancel", "title": "Бас тарту" }
  ]
}

Жауап (202)

{
  "success": true,
  "queued": true,
  "queueId": "uuid",
  "campaignId": null,
  "message": "Сообщение поставлено в очередь на отправку"
}

Қателер (400)

Шектеулер жіберуге дейін бірден тексеріледі. Бірдеңе дұрыс болмаса, API 400 қайтарып, қай өрісті түзету керегін жазады. Қате мәтіндері орыс тілінде, мысалы:

{ "error": "В меню не больше 10 пунктов всего, сейчас 11" }
{ "error": "interactive.rows[2].title: не длиннее 24 символов" }
{ "error": "interactive доступен только для линий WhatsApp Business API (whatsapp_waba)" }

Клиент не таңдағанын қалай білуге болады

messages_button жазылымын қосыңыз (қараңыз: Webhooks). Клиент мәзір тармағын таңдағанда немесе батырманы басқанда оқиға келеді:

{
  "buttons": [{
    "messageId": "uuid",
    "channelId": "uuid",
    "chatId": "77071234567",
    "contactId": "uuid",
    "conversationId": "uuid",
    "button": {
      "type": "list_reply",
      "id": "prices",
      "title": "Бағалар",
      "description": "Тарифтер мен құны"
    },
    "replyTo": {
      "messageId": "uuid",
      "queueId": "uuid",
      "campaignId": null,
      "broadcastId": null
    },
    "timestamp": "2026-10-03T12:00:00Z"
  }]
}

Мәзір тармағы үшін button.type мәні list_reply, жауап батырмасы үшін button_reply. button.id ішінде сіздің id келеді, ол арқылы бот сценарийін әрі қарай жүргізу оңай. replyTo.queueId клиент қай жіберілімге жауап бергенін көрсетеді.

Оператор не көреді

Кабинет чатында хабарлама мәтін және оның астындағы мәзір тармақтары немесе батырмалар түрінде көрсетіледі, клиент қалай көрсе, солай. Клиенттің таңдауы чатқа тармақ атауымен кәдімгі кіріс хабарлама болып келеді.