Menu dokumentasiKanal Aplikasi
Dokumentasi APIEnglish

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.

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).

Kirim WhatsApp dari sistem Anda lewat API Klik Flow.

Mulai dengan paket Free. Ajak tim setelah ruang kerja siap.