Chatbot API · dazo/docs

POST /api/chatbot-api adalah endpoint percakapan utama. Dipanggil backend-go sebagai EngineBot saat ada pesan masuk dari WhatsApp gateway.

POST /api/chatbot-api

Handler: controllers/mainController.js — functionRouteBot

Auth: JWT Bearer wajib (atau IP allowlist bypass)

Request fields

Field	Wajib	Fungsi
`store_id`	Ya	Tenant/store ID
`customer_id`	Ya	Nomor/identifier customer
`agent_id`	Ya	Agent configuration ID
`question`	Kondisional	Pesan text; dapat kosong bila media ada
`image`	Tidak	URL gambar untuk vision/proof flow
`audio`	Tidak	URL audio untuk transcription
`replied_message`	Tidak	Isi pesan yang sedang dibalas
`team_id`	Dipakai downstream	Team pengirim pesan
`device_id`	Dipakai downstream	Device WhatsApp dan order scope
`conversations`	Tidak	Array `{role, content}` dari client
`time_reply`	Praktis wajib	Delay batching dalam detik

Contoh request

json

{
  "store_id": "store-1",
  "customer_id": "628123456789",
  "agent_id": "agent-1",
  "team_id": "team-1",
  "device_id": "device-1",
  "question": "Saya mau beli produk A dua",
  "image": null,
  "audio": null,
  "replied_message": "",
  "conversations": [],
  "time_reply": 2
}

Normal response (HTTP 201)

json

{
  "statusCode": 201,
  "idUser": "628123456789",
  "idAgent": "agent-1",
  "idStore": "store-1",
  "data": {
    "answer": ["Balasan chatbot"],
    "images": [
      {
        "caption": "Nama produk",
        "image": ["https://cdn.dazo.id/path/image.jpg"]
      }
    ],
    "history": []
  }
}

Dedup behavior

Payload text dan replied message sama dalam 10 detik tidak diproses ulang. Key dedup: customer_id (tidak tenant-safe — lihat Tech Debt).

Kondisi	Response
Response sebelumnya tersedia	HTTP 200, response sebelumnya dikembalikan
Masih diproses	HTTP 200, `answer: []` + `meta.dedup: true`

Buffer behavior

Pesan cepat dari customer sama digabung berdasarkan time_reply (detik). Timer terakhir memegang satu Express response. Shared promise tidak di-await. Error timer tidak mengirim HTTP error.

Response formatting

Main orchestrator diminta menghasilkan JSON dengan answer dan images. Controller tetap memiliki fallback untuk:

Raw text — bila orchestrator tidak return JSON
Markdown image extraction — ![Nama](URL) dipindahkan ke images array
extractAndCleanImages — hanya URL gambar yang lolos aturan yang dipindahkan

Hanya URL gambar yang lolos aturan extractAndCleanImages yang dipindahkan ke response images. Teks balasan dibersihkan dari syntax gambar Markdown.

Request Lifecycle (ringkas)

text

1. verifyToken          — auth (JWT atau IP allowlist)
2. functionRouteBot     — validate store_id, customer_id, agent_id
3. dedup                — 10 detik, key customer_id
4. userBuffer           — message batching (time_reply)
5. context loader       — customer, agent, store, history (maks 10), active order
6. media processing     — audio transcription, image vision/proof
7. fast path check      — konfirmasi alamat → checkShippingCost
8. intent detection     — service/intent.js (dilewati saat order follow-up)
9. main orchestrator    — prompt/main-agent.md → specialist tool
10. response formatter   — JSON, image extraction, token tracking
11. follow-up scheduler  — scheduler/workerService.js (optional)

Detail lifecycle ada di Agent Architecture.

Catatan

time_reply tidak divalidasi — bisa negatif atau sangat besar
Error/not-found response chatbot tidak konsisten dengan HTTP status normal (201 untuk sukses, tapi error juga bisa 200)
Bila question kosong dan tidak ada media, handler tetap diproses (intent mungkin kosong)
conversations array dari client dipakai sebagai history, dipotong jadi 10 messages terakhir

Kembali ke

API Reference Index — daftar semua grup
Agent Architecture — detail lifecycle
Auth & JWT — cara middleware bekerja