Vebhuklar

Vebhuk — Chato bilan sizning dasturingiz oʻrtasidagi koʻprik: sayt, ombor, 1C, CRM. U ikki tomonga ishlaydi va tomonlar bir-biriga bogʻliq emas: faqat bittasini yoqish ham mumkin.

• Chiquvchi — biror narsa sodir boʻlganda Chato sizga oʻzi murojaat qiladi va mijoz bilan suhbat vaqtida sizdan soʻraydi.
• Kiruvchi — dasturingiz Chato’ga murojaat qiladi: mijozga yozadi, menejerni chaqiradi, kartani tuzatadi, yozishmalarni oʻqiydi.

Sozlash kabinetda: AI-yordamchi → Ulanishlar → Vebhuk.

Chiquvchi: manzilingizga keladigan hodisalar

Manzilni (faqat https), xohlasangiz imzo uchun maxfiy soʻzni va oʻz sarlavhalaringizni kiriting — odatda bu dasturingizga kirish kaliti. Soʻng nima haqida xabar berishni belgilang:

Chato quyidagi tanaga ega POST yuboradi:

{
  "workspaceId": "cmr4sk0ya0001o701hl7ghbqk",
  "event": "message.received",
  "sentAt": "2026-09-08T10:00:00.000Z",
  "data": {
    "conversationId": "cmt9x1a2b0003o701abcd1234",
    "channelId": "cmt9x0zzz0001o701wxyz9876",
    "messageId": "cmt9x2c3d0005o701efgh5678",
    "direction": "INBOUND",
    "type": "TEXT",
    "text": "Assalomu alaykum, buyurtma tayyormi?",
    "sentAt": "2026-09-08T10:00:00.000Z",
    "isFirstMessage": false
  }
}

200 kodi bilan javob bering — javob tanasini Chato tahlil qilmaydi. Agar serveringiz jim tursa yoki xato bilan javob bersa, mijoz bilan suhbat kechikmaydi: hodisa shunchaki yetkazilmaydi, bu haqda yozuv bizning jurnallarimizda qoladi.

Soʻrov imzosi

Maxfiy soʻz berilgan boʻlsa, Chato x-chato-signature sarlavhasiga soʻrov tanasining HMAC-SHA256 qiymatini oʻn oltilik satr koʻrinishida qoʻyadi. Uni oʻzingizda tekshiring — shunda bizning soʻrovni begonasidan ajratasiz:

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

Imzoni xom tana boʻyicha, JSON tahlil qilinishidan oldin hisoblang: qayta yigʻilgan obyekt boshqa baytlar ketma-ketligini beradi va imzo mos kelmaydi.

Suhbat vaqtida dasturingizni chaqirish

Xuddi shu manzil yordamchi «Funksiyani chaqirish» qadamida dasturingizdan soʻraganda ishlatiladi — «42-oʻlchamda qizili bormi». Tana: workspaceId, conversationId, sentAt va yordamchi yigʻgan narsalar bilan data. Nima javob bersangiz, u mijozga shuni oʻz soʻzi bilan aytadi, shuning uchun qisqa va tushunarli JSON bilan javob bering.

Kiruvchi havola: dasturingiz suhbatda harakat qiladi

Havola yaratish tugmasini bosing va uni dasturchingizga bering. U shunday koʻrinadi:

POST https://chato.kz/api/v1/ai-assistant/inbound/SIZNING_KALITINGIZ
Content-Type: application/json

Suhbat yo oʻzining conversationId orqali, yo mijozning telefoni orqali koʻrsatiladi: raqam istalgan koʻrinishda qabul qilinadi — +7 771 525 89 15, 87715258915.

Mijozga yozish

curl -X POST https://chato.kz/api/v1/ai-assistant/inbound/SIZNING_KALITINGIZ \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+7 771 525 89 15","text":"Buyurtma yigʻildi, 19:00 gacha kutamiz"}'

Javobi: {"status":"sent","conversationId":"..."}.

Fayl ilova qilish

{
  "phone": "77715258915",
  "text": "Sizning hisobingiz",
  "fileUrl": "https://sizning-xizmatingiz.kz/hisob-2026-09.pdf",
  "fileName": "Sentyabr hisobi.pdf"
}

Fayl havola boʻyicha olinadi (faqat https, 20 MB gacha) va mijozga ilova sifatida yuboriladi. Bu holda text majburiy emas.

Birinchi boʻlib yozish

Agar bu odam bilan suhbat hali boʻlmasa, channelId qoʻshing — qaysi kanaldan yozish kerakligini:

{ "phone": "77715258915", "channelId": "cmt9x0zzz0001o701wxyz9876", "text": "Assalomu alaykum!" }

channelId boʻlmasa, notanish raqamga hech narsa yuborilmaydi — aks holda tarqalib ketgan havola ommaviy tarqatishga aylanardi.

Qolgan harakatlar

Ularning barchasi oʻsha manzilga yuboriladi, faqat action maydoni farq qiladi.

Maydonlar haqida: text — matn (note uchun bu izoh, handoff uchun sabab, u majburiy emas); contact — { name, phone } obyekti, faqat yuborilgani oʻzgaradi; limit — 1 dan 100 gacha, birlamchi 20; status — OPEN, WAITING, IN_PROGRESS yoki CLOSED. Izohni mijoz koʻrmaydi, reopen dan keyin esa yordamchi suhbatda yana javob beradi.

Misol — suhbatni odamga berish:

{ "action": "handoff", "conversationId": "cmt9x1a2b0003o701abcd1234", "text": "mijoz menejerni soʻrayapti" }

Misol — bu kimligini va suhbat holatini bilish:

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

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

conversations.list — suhbat kerak boʻlmaydigan yagona harakat: identifikator boʻlmaganda keraklisini aynan shu bilan topasiz.

Xato boʻlganda nima qaytadi

Kalit doim faqat sizning kompaniyangiz doirasida ishlaydi: soʻrov tanasidagi begona conversationId hech narsa bermaydi.

Bitimlar va CRM vebxuklari

O‘z CRM ingiz uchun alohida vebxuk manzillari bor: bitim hodisalarini tanlash (deal.created, deal.won, task.completed va boshqalar), vaqt belgisi bilan HMAC-SHA256 imzosi, xatolarda qayta yuborish, yetkazish jurnali va «Qayta yuborish» tugmasi. U yerda huquqli ochiq API kalitlari ham chiqariladi. Hammasi Bitimlar uchun ochiq API va CRM vebxuklari maqolasida tasvirlangan; yuqorida tasvirlangan assistent manzili avvalgidek ishlaydi.