# Kanal Aplikasi: chat pengguna aplikasi Anda di Inbox Klik Flow.

Kanal Aplikasi membuat chat di aplikasi Anda sendiri bekerja seperti live chat website. Server aplikasi mengirim pesan pengguna lewat API v2, chat masuk Inbox berlabel Aplikasi, AI Agent dan otomasi "Pesan masuk" menjawab langsung di jawaban permintaan, dan balasan tim dikirim ke aplikasi lewat Webhook v2.

Sumber: https://klikflow.id/docs/api/kanal-aplikasi

## Apa beda Kanal Aplikasi dengan Tanya AI Agent?

Tanya AI Agent hanya meminta jawaban AI: tidak ada chat di Inbox dan tim tidak ikut membalas. Kanal Aplikasi memasukkan setiap pesan ke Inbox sebagai chat, jadi AI Agent, otomasi, dan tim bisa membalas, dan chat bisa dioper ke tim.

## Siapkan kanal

- Buka Live Chat › Widget baru, pilih jenis "Kanal Aplikasi (API)", beri nama, lalu buat. Petunjuk sambungannya menampilkan ID kanal. Kanal Aplikasi dihitung sebagai satu widget paket.
- Pilih AI Agent di kartu kanal dan nyalakan AI bila pesan perlu dijawab otomatis.
- Buat kunci di Pengaturan › API & Webhook dengan izin `app_channels:write` (Kanal Aplikasi: kirim pesan pengguna).
- Tambahkan webhook dengan event `message.sent`, dan bila perlu `conversation.handoff` serta `conversation.resolved`, di Pengaturan › API & Webhook › Webhook.

## Kunci hanya di server

Kunci API adalah rahasia. Aplikasi HP atau halaman web Anda mengirim pesan pengguna ke server Anda, lalu server Anda yang memanggil Klik Flow. Server Anda juga yang menerima webhook dan meneruskan balasan ke aplikasi. Jangan menaruh kunci di aplikasi HP atau kode halaman web.

## Kirim pesan pengguna

```
curl -X POST "https://klikflow.id/api/v2/app-channels/7/messages" \
  -H "Authorization: Bearer KUNCI_API" \
  -H "Idempotency-Key: app-8812-msg-31" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id":"8812","name":"Rina","text":"Saya mau komplain, batik yang datang sobek."}'
```

Jawaban (201):

```
{
  "data": {
    "object": "app_message",
    "app_channel_id": 7,
    "external_user_id": "8812",
    "conversation_id": 48213,
    "message_id": 99150,
    "contact_id": 301,
    "conversation_status": "open",
    "ai_active": false,
    "handoff": true,
    "replies": [
      {
        "message_id": 99151,
        "sender": "ai",
        "type": "text",
        "text": "Mohon maaf kainnya sobek, Kak Rina. Chat ini saya teruskan ke tim kami, sebentar lagi dibalas ya.",
        "media": []
      }
    ]
  }
}
```

`external_user_id` adalah id pengguna di aplikasi Anda: satu pengguna = satu chat di Inbox, dengan ID pengguna aplikasi di chat itu. `name`, `phone`, dan `email` boleh dikosongkan; bila diisi, chat disambungkan ke kontak dengan nomor atau email yang sama, atau kontak baru dibuat. Bila AI menjawab, permintaan butuh beberapa detik, jadi beri batas waktu 60 detik.

- `replies`: balasan AI Agent (`sender: ai`) atau otomasi (`sender: automation`) yang sudah terkirim, berurutan, dengan file sebagai link sementara 24 jam.
- `ai_active: false` berarti AI tidak menjawab chat ini lagi; `handoff: true` berarti chat sudah dioper ke tim.
- Kirim `Idempotency-Key` di setiap pesan: ulangan dengan kunci yang sama tidak menyimpan pesan dua kali.

## Balasan lewat webhook

Semua yang dikirim di chat itu sesudahnya, yaitu balasan tim dari Inbox, file, dan balasan saat chat dioper, dikirim ke aplikasi lewat event `message.sent`:

```
{
  "id": "evt_4Rt7Lm2Qx9Kp1Zs3",
  "type": "message.sent",
  "created": "2026-11-09T10:34:01+07:00",
  "business_id": 7,
  "data": {
    "message_id": 99152,
    "conversation_id": 48213,
    "contact_id": 301,
    "channel": "app",
    "app_channel_id": 7,
    "external_user_id": "8812",
    "sender": "team",
    "sender_name": "Dewi",
    "type": "text",
    "text": "Halo Kak Rina, saya Dewi dari Batik Sekar. Boleh kirim foto jahitannya?",
    "media": [],
    "sent_at": "2026-11-09T10:34:00+07:00"
  }
}
```

- `sender`: `ai`, `automation`, atau `team`; `sender_name` berisi nama anggota tim.
- `media`: file sebagai link sementara yang berlaku 24 jam (`expires_at`). Unduh atau tampilkan sebelum waktunya habis.
- `message.sent` hanya dikirim untuk chat Kanal Aplikasi. Periksa tanda tangannya seperti event lain (panduan Webhook).
- Di Inbox, pesan mendapat tanda "diterima aplikasi" setelah webhook Anda menjawab 2xx. Bila kiriman tetap gagal sampai percobaan terakhir, pesan ditandai gagal dengan alasannya.

## Hindari balasan ganda

Balasan AI dan otomasi ada di `replies` dan juga dikirim lewat `message.sent`. Simpan `message_id` setiap pesan yang sudah ditampilkan di aplikasi, lalu abaikan event dengan `message_id` yang sama. Event bisa tiba dua kali atau tidak berurutan; urutkan dengan `sent_at`.

## Dioper ke tim dan selesai

- Saat AI Agent mengoper chat ke tim (pelanggan minta admin, keluhan, atau alasan lain dari Perilaku), jawaban berisi `handoff: true` dan `ai_active: false`, dan event `conversation.handoff` dikirim dengan `reason`. Tampilkan bahwa tim akan membalas; balasan tim tiba lewat `message.sent`.
- Setelah dioper, pesan pengguna tetap masuk Inbox, tetapi AI tidak menjawabnya sampai tim menyalakan AI lagi di chat itu.
- `conversation.resolved` dikirim saat tim menandai chat selesai.
- `conversation.handoff` dan `conversation.resolved` dikirim untuk semua kanal. Chat Kanal Aplikasi membawa `channel: "app"`, `app_channel_id`, dan `external_user_id`, begitu juga `message.received` dan `message.status` (di `message.status`, `to` berisi `external_user_id`). `GET /api/v2/conversations` dan detail percakapan memakai nama yang sama; saring dengan `channel=app`.

## Paket dan batas

- Butuh fitur Live chat website di paket; setiap Kanal Aplikasi dihitung sebagai satu widget. Kanal yang dijeda, paket tanpa Live Chat, atau widget yang melebihi paket ditolak `app_channel_paused` (403).
- Jawaban AI di Kanal Aplikasi memakai kredit AI seperti balasan AI di chat lain.
- Hanya kunci live: pesan Kanal Aplikasi adalah chat sungguhan, jadi kunci tes ditolak `live_key_required` (403). Untuk mencoba, buat Kanal Aplikasi khusus uji, lalu jeda atau hapus setelah selesai.
- Batas permintaan per menit kunci tetap berlaku (lihat panduan Batas & paket).
