Вебхуктар

Вебхук — 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
  }
}

10 секунд ішінде кез келген 2xx кодымен жауап беріңіз — жауап денесін Chato талдамайды. Қайта бағыттаулар (3xx) орындалмайды. Бұл мекенжайда қайталау жоқ: серверіңіз үнсіз қалса немесе қатемен жауап берсе, оқиға жай ғана жеткізілмейді, ал клиентпен әңгіме бұдан кідірмейді. Қайталаулар мен жеткізу журналы керек болса, мекенжайды CRM вебхуктарына қосыңыз, оған чаттың сол оқиғалары келеді.

conversation.handoff, conversation.reopened және conversation.closed оқиғаларында data ішінде conversationId, oldStatus, newStatus және changedBy жатады; conversation.assigned ішінде — conversationId, operatorId, operatorEmail, operatorName және assignedBy; channel.disconnected ішінде — channelId және status. conversation.created денесі message.received денесімен бірдей.

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

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

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-ге дейін күтеміз"}'

Жауабы: {"data":{"status":"sent","conversationId":"..."}}. Chato-ның бүкіл API-індегідей, нәтиже data өрісінде жатады.

Файл тіркеу

{
  "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" }

{
  "data": {
    "status": "ok",
    "conversationId": "cmt9x1a2b0003o701abcd1234",
    "contact": { "id": "...", "name": "Әсем", "phone": "77715258915", "username": null, "avatarUrl": null },
    "conversation": {
      "id": "...",
      "status": "OPEN",
      "channelId": "...",
      "assignedOperatorId": null,
      "unreadCount": 2,
      "lastMessageAt": "2026-09-08T10:00:00.000Z"
    }
  }
}

Қалған әрекеттер не қайтарады: status (sent, noted, handoff, closed, reopened, assigned, updated) және conversationId; messages.list — қосымша messages (жаңалары жоғарыда: id, direction, type, content, sentAt); conversations.list — conversations (id, status, channelId, lastMessageAt, lastMessageText, contactName, contactPhone); мәмілелермен әрекеттер — status (deal_created, deal_moved, note_added) және deal.

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

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

Қате денесі — {"message": "Диалог не найден", "statusCode": 404, ...}: себебі message ішінде орыс тілінде жазылады.

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

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

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