Вебхуктар

Вебхук — Chato мен сіздің бағдарламаңыздың арасындағы көпір: сайт, қойма, 1С, CRM. Ол екі бағытта жұмыс істейді, әрі бағыттар бір-біріне тәуелді емес: біреуін ғана қосуға болады.

• Шығыс — бірдеңе болғанда Chato сізге өзі хабарласады және клиентпен әңгіме кезінде сізден сұрайды.
• Кіріс — бағдарламаңыз Chato-ға хабарласады: клиентке жазады, менеджерді шақырады, картаны түзетеді, жазысуды оқиды.

Баптау кабинетте: ИИ-ассистент → Қосылымдар → Вебхук.

Шығыс: сіздің мекенжайыңызға келетін оқиғалар

Мекенжайды (тек https), қаласаңыз қолтаңба үшін құпия сөзді және өз тақырыпшаларыңызды жазыңыз — әдетте бұл бағдарламаңызға кіру кілті. Содан кейін нені хабарлау керегін белгілеңіз:

Chato мынадай денесі бар POST жібереді:

{
  "workspaceId": "cmr4sk0ya0001o701hl7ghbqk",
  "event": "message.received",
  "sentAt": "2026-09-08T10:00:00.000Z",
  "data": {
    "conversationId": "cmt9x1a2b0003o701abcd1234",
    "channelId": "cmt9x0zzz0001o701wxyz9876",
    "messageId": "cmt9x2c3d0005o701efgh5678",
    "direction": "INBOUND",
    "type": "TEXT",
    "text": "Сәлеметсіз бе, тапсырыс дайын ба?",
    "sentAt": "2026-09-08T10:00:00.000Z",
    "isFirstMessage": false
  }
}

200 кодымен жауап беріңіз — жауап денесін Chato талдамайды. Егер сіздің серверіңіз үнсіз қалса немесе қатемен жауап берсе, клиентпен әңгіме кідірмейді: оқиға жай ғана жеткізілмейді, ал ол туралы жазба біздің журналдарда қалады.

Сұраудың қолтаңбасы

Құпия сөз берілсе, Chato x-chato-signature тақырыпшасына сұрау денесінің HMAC-SHA256 мәнін оналтылық жол түрінде салады. Оны өзіңізде тексеріңіз — сонда біздің сұрауды бөгденікінен ажыратасыз:

const crypto = require('node:crypto');
const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = expected === req.headers['x-chato-signature'];

Қолтаңбаны шикі дене бойынша, JSON-ды талдағанға дейін есептеңіз: қайта жиналған нысан басқа байт тізбегін береді және қолтаңба сәйкес келмейді.

Әңгіме кезінде бағдарламаңызды шақыру

Дәл сол мекенжай көмекші «Функцияны шақыру» қадамында бағдарламаңыздан сұрағанда қолданылады — «42-ші өлшемде қызылы бар ма». Дене: workspaceId, conversationId, sentAt және көмекші жинағаны бар data. Сіз не жауап берсеңіз, ол клиентке соны өз сөзімен айтады, сондықтан қысқа әрі түсінікті JSON-мен жауап беріңіз.

Кіріс сілтеме: бағдарламаңыз диалогта әрекет етеді

Сілтеме жасау түймесін басып, оны бағдарламашыға беріңіз. Ол былай көрінеді:

POST https://chato.kz/api/v1/ai-assistant/inbound/СІЗДІҢ_КІЛТ
Content-Type: application/json

Диалог не өзінің conversationId арқылы, не клиенттің телефоны арқылы көрсетіледі: нөмір кез келген түрде қабылданады — +7 771 525 89 15, 87715258915.

Клиентке жазу

curl -X POST https://chato.kz/api/v1/ai-assistant/inbound/СІЗДІҢ_КІЛТ \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+7 771 525 89 15","text":"Тапсырыс жиналды, 19:00-ге дейін күтеміз"}'

Жауабы: {"status":"sent","conversationId":"..."}.

Файл тіркеу

{
  "phone": "77715258915",
  "text": "Сіздің шотыңыз",
  "fileUrl": "https://сіздің-сервис.kz/schet-2026-09.pdf",
  "fileName": "Қыркүйек айының шоты.pdf"
}

Файл сілтеме бойынша алынады (тек https, 20 МБ дейін) және клиентке тіркеме болып кетеді. Бұл жағдайда text міндетті емес.

Бірінші болып жазу

Егер бұл адаммен диалог әлі жоқ болса, channelId қосыңыз — қай арнадан жазу керегін:

{ "phone": "77715258915", "channelId": "cmt9x0zzz0001o701wxyz9876", "text": "Сәлеметсіз бе!" }

channelId болмаса, бейтаныс нөмірге ештеңе жіберілмейді — әйтпесе тарап кеткен сілтеме таратылымға айналар еді.

Қалған әрекеттер

Олардың бәрі сол мекенжайға жіберіледі, тек action өрісі өзгереді.

Өрістер туралы: text — мәтін (note үшін бұл белгі, handoff үшін себеп, ол міндетті емес); contact — { name, phone } нысаны, тек жіберілгені өзгереді; limit — 1-ден 100-ге дейін, әдепкі 20; status — OPEN, WAITING, IN_PROGRESS немесе CLOSED. Белгіні клиент көрмейді, ал reopen кейін көмекші диалогта қайта жауап береді.

Мысал — диалогты адамға беру:

{ "action": "handoff", "conversationId": "cmt9x1a2b0003o701abcd1234", "text": "клиент менеджерді сұрайды" }

Мысал — бұл кім екенін және диалогтың күйін білу:

{ "action": "contact.get", "phone": "77715258915" }

{
  "status": "ok",
  "conversationId": "cmt9x1a2b0003o701abcd1234",
  "contact": { "id": "...", "name": "Әсем", "phone": "77715258915", "username": null },
  "conversation": { "id": "...", "status": "OPEN", "channelId": "...", "unreadCount": 2 }
}

conversations.list — диалог қажет емес жалғыз әрекет: идентификатор болмағанда керегін дәл сонымен табады.

Қате болғанда не қайтады

Кілт әрқашан тек сіздің компанияңыз аясында жұмыс істейді: сұрау денесіндегі бөгде conversationId ештеңе бермейді.

Мәмілелер және CRM вебхуктары

Өз CRM-іңіз үшін бөлек вебхук мекенжайлары бар: мәміле оқиғаларын таңдау (deal.created, deal.won, task.completed және басқалар), уақыт белгісі бар HMAC-SHA256 қолтаңбасы, қателерде қайталау, жеткізу журналы және «Қайта жіберу» батырмасы. Сол жерде құқықтары бар ашық API кілттері шығарылады. Барлығы Мәмілелердің ашық API-і және CRM вебхуктары мақаласында сипатталған; жоғарыда сипатталған ассистент мекенжайы бұрынғыдай жұмыс істейді.