# Event & payload

> Tiga event webhook CSKU, contoh JSON lengkap, dan arti setiap field.


Setiap request webhook berisi satu pesan dan satu event. Bentuk payload sama untuk semua event; hanya field `message.agent` dan `message.ai` yang muncul sesuai event.

## Daftar event

| Event | Kapan dikirim |
| --- | --- |
| `channel.message_in` | Pesan pelanggan masuk dan tersimpan. Berlaku untuk semua channel, termasuk Webchat, dan tetap dikirim walau percakapan sedang ditangani agen. |
| `ai.message_generated` | AI agent selesai membuat balasan dan balasan tersimpan, tepat sebelum dikirim ke pelanggan. |
| `agent.message_out` | Balasan agen dari dashboard atau aplikasi mobile berhasil terkirim ke channel. Termasuk pesan sistem CSAT (permintaan penilaian dan ucapan terima kasih). |

> **Catatan: Jeda balasan AI**
>
> AI agent menunggu sekitar 30 detik untuk menggabungkan beberapa pesan pelanggan sebelum membalas. Jadi `ai.message_generated` biasanya datang beberapa detik sampai sekitar 30 detik setelah `channel.message_in` terakhir.

> **Peringatan: Pesan dari Public API tidak memicu webhook**
>
> Pesan yang Anda kirim lewat [Kirim pesan](https://docs.csku.ai/api/kirim-pesan) (`POST /v1/message`) atau lewat [Proxy WABA](https://docs.csku.ai/waba/proxy) **tidak** memicu `agent.message_out`. Sistem Anda sudah tahu pesan itu, jadi catat langsung di sisi Anda.

## Contoh payload

### channel.message_in

```json
{
  "event": "channel.message_in",
  "timestamp": 1792041600,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 0,
  "message": {
    "id": "MSG_01JQ8Z3M2A7B8C9D0E1F2G3H4J",
    "sender_name": "Budi Santoso",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "text",
      "text": "Halo kak, pesanan saya sudah dikirim belum?"
    }
  }
}
```

### ai.message_generated

```json
{
  "event": "ai.message_generated",
  "timestamp": 1792041631,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 0,
  "message": {
    "id": "MSG_01JQ8Z4N9Q1R2S3T4U5V6W7X8Y",
    "sender_name": "Asisten - Sari",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "text",
      "text": "Halo Kak Budi, pesanan Kakak sudah dikirim hari ini via JNE ya."
    },
    "ai": {
      "name": "Sari",
      "id": "AI241005QWE5678"
    }
  }
}
```

### agent.message_out

```json
{
  "event": "agent.message_out",
  "timestamp": 1792041900,
  "conversation_id": "CO_01JQ8Z3K4M5N6P7R8S9T0V1W2X",
  "conversation_label": "Budi Santoso",
  "need_human": 1,
  "message": {
    "id": "MSG_01JQ8Z8D3F4G5H6J7K8L9M0N1P",
    "sender_name": "Dewi",
    "channel": {
      "id": "WHATSAPP_01JP4R6T8V0X2Z4B6D8F0H2K4M",
      "name": "CS Toko Utama",
      "engine": "whatsapp"
    },
    "bisnis": {
      "id": "BIZ241005ABC1234",
      "name": "Rina Wijaya"
    },
    "user": {
      "id": "MER241005XYZ0001",
      "name": "Rina Wijaya"
    },
    "content": {
      "type": "image",
      "attachments": [
        {
          "url": "https://bukakios-storage.b-cdn.net/chat/resi-budi.jpg",
          "mime_type": "image/jpeg"
        }
      ]
    },
    "agent": {
      "name": "Dewi"
    }
  }
}
```

## Referensi field

| Field | Tipe | Keterangan |
| --- | --- | --- |
| `event` | string | Nama event. Lihat [daftar event](#daftar-event). |
| `timestamp` | integer | Unix time (detik) saat request dikirim. Berubah di setiap retry, jadi jangan dipakai untuk deduplikasi. |
| `conversation_id` | string | ID percakapan. Sama dengan `conversation_id` di Public API. |
| `conversation_label` | string | Nama tampilan percakapan, biasanya nama pelanggan. |
| `need_human` | integer | `1` jika percakapan sedang ditangani agen (AI berhenti membalas), `0` jika tidak. |
| `message.id` | string | ID unik pesan. Pakai untuk deduplikasi. |
| `message.sender_name` | string | Nama pengirim: pelanggan, AI agent, atau agen. Bisa kosong untuk pesan sistem. |
| `message.channel.id` | string | ID channel di CSKU. |
| `message.channel.name` | string | Label channel yang Anda isi di **Integrasi**. |
| `message.channel.engine` | string | Jenis channel. Lihat [nilai engine](#nilai-engine). |
| `message.bisnis.id` | string | Business ID Anda. |
| `message.bisnis.name` | string | Nama akun pemilik bisnis. |
| `message.user.id` | string | ID akun pemilik bisnis. |
| `message.user.name` | string | Nama akun pemilik bisnis. |
| `message.content` | object | Isi pesan. Lihat [tipe konten](#tipe-konten). |
| `message.agent.name` | string | Hanya di `agent.message_out`. Nama agen yang membalas. |
| `message.ai.name` | string | Hanya di `ai.message_generated`, jika channel punya AI agent. Label AI agent. |
| `message.ai.id` | string | ID AI agent. |

## Tipe konten

Pesan teks:

```json
{ "type": "text", "text": "Halo kak" }
```

Pesan selain teks memakai `attachments`. `url` berisi alamat file, `mime_type` berisi tipe file.

```json
{
  "type": "document",
  "attachments": [
    { "url": "https://bukakios-storage.b-cdn.net/chat/invoice.pdf", "mime_type": "application/pdf" }
  ]
}
```

Contoh nilai `type`: `image`, `video`, `audio`, `document`. Nilai lain bisa muncul tergantung channel. Perlakukan `type` selain `text` yang tidak Anda kenal sebagai lampiran biasa.

> **Catatan: Caption tidak ikut**
>
> Untuk pesan media, payload hanya berisi `url` dan `mime_type`. Teks caption tidak disertakan.

## Nilai engine

| `engine` | Channel |
| --- | --- |
| `whatsapp` | WhatsApp (Scan QR) |
| `waba` | WhatsApp API (Token manual) |
| `whatsapp_meta` | WhatsApp API (Login Meta) |
| `telegram` | Telegram |
| `instagram` | Instagram |
| `facebook` | Facebook |
| `intercom` | Intercom |
| `slack` | Slack |
| `socialchat` | SocialChat |
| `webchat` | Webchat |