Saluran Kustom #

Hubungkan platform perpesanan atau alat komunikasi apa pun ke platform menggunakan saluran kustom. Ini memungkinkan Anda membawa pesan dari platform seperti widget obrolan langsung situs web, sistem email, CRM, atau layanan lainnya ke dalam kotak masuk Anda — dan meresponsnya dengan Agen AI Anda.

Apa Itu Saluran Kustom? #

Saluran kustom memperluas platform di luar platform perpesanan bawaannya (WhatsApp, SMS, Instagram, Messenger). Dengan saluran kustom, Anda dapat:

• Menerima pesan dari platform eksternal apa pun ke dalam kotak masuk terpadu platform.
• Mengirim balasan dari aplikasi kembali ke platform eksternal Anda secara otomatis.
• Menggunakan Agen AI untuk merespons pesan dari sumber mana pun.
• Melacak semua percakapan bersama saluran Anda lainnya dalam satu kotak masuk.

Ini ideal bagi bisnis yang menggunakan alat komunikasi khusus, memiliki platform yang dibuat khusus, atau ingin mengumpulkan semua pesan pelanggan di satu tempat.

Cara Kerjanya #

Saluran kustom bekerja dengan mengirimkan pesan bolak-balik antara platform eksternal Anda dan platform menggunakan webhook (pesan otomatis yang dikirim antar sistem melalui internet). Berikut adalah alurnya:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Pesan masuk: Platform eksternal Anda mengirimkan pesan ke alamat web (URL). Anggap saja ini sebagai platform Anda yang “mengeposkan” pesan ke kotak surat platform.
2. Pemrosesan: Platform membuat atau memperbarui kontak, menyimpan pesan, dan meminta Agen AI untuk membuat respons (jika aktif).
3. Pesan keluar: Saat platform mengirim balasan (baik dari AI atau diketik oleh Anda), platform mengirim pesan tersebut ke URL di sistem Anda, tempat sistem Anda dapat mengirimkannya ke pengguna akhir. Balasan juga dapat membawa file: item yang dikirim Agen AI dari pustaka medianya, lampiran atau catatan suara dari kotak masuk, atau file yang dikirim melalui API yang tiba sebagai tautan unduhan di samping teks.

Menyiapkan Pesan Masuk (Platform Anda ke Aplikasi) #

Untuk mengirim pesan dari platform eksternal Anda ke dalam aplikasi, platform Anda perlu mengirim data ke URL berikut. Pengembang Anda akan mengenalinya sebagai permintaan POST standar (cara umum bagi satu sistem untuk mengirim data ke sistem lain melalui internet).

Tempat Mengirim Pesan #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Ganti YOUR_API_KEY dengan kunci API Anda (kode pribadi yang membuktikan kepada platform bahwa platform Anda diizinkan untuk mengirim pesan). Temukan atau buat kuncinya di bawah Pengaturan → Integrasi → Kunci API.

Kunci berlingkup (scoped key) juga dapat digunakan, selama kunci tersebut tidak bersifat read-only dan areanya mencakup Messages. Pesan akan masuk ke akun tempat kunci tersebut berada, jadi gunakan kunci dari akun (atau sub-akun) yang kotak masuknya harus menerima pesan tersebut.

Format Pesan #

Kirim data pesan dalam format berikut (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

Apa arti setiap bagian:

• messageSid - ID unik untuk pesan spesifik ini (sistem Anda yang membuatnya). Digunakan untuk mencegah pesan yang sama diproses dua kali.
• fromId - Siapa yang mengirim pesan (bisa berupa ID pengguna, email, atau nomor telepon dari sistem Anda).
• toId - Pengidentifikasi bisnis Anda (bisa berupa label apa pun yang Anda pilih).
• body - Teks pesan yang sebenarnya.
• channel - Label yang Anda pilih untuk mengidentifikasi dari mana pesan tersebut berasal (misalnya, “website-chat”, “email”). Ini menjadi nama saluran yang ditampilkan untuk kontak tersebut di kotak masuk dan dalam notifikasi.

Referensi Bidang Lengkap #

Reaksi Emoji #

Jika platform Anda mendukung reaksi emoji (misalnya, jempol ke atas pada sebuah pesan), kirimkan sebagai reaksi alih-alih sebagai pesan teks: atur messageType ke "reaction" dan masukkan hanya emoji tersebut di customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

Asisten kemudian akan memperlakukannya sebagaimana mestinya:

• Reaksi terhadap pertanyaan yang diajukan asisten (misalnya “Apakah hari Kamis bisa?”) dianggap sebagai jawaban, dan asisten akan membalas.
• Reaksi terhadap pesan penutup (misalnya “Sampai jumpa!”) akan mengakhiri percakapan dengan tenang. Tidak ada balasan yang dikirim.

Jika platform Anda mengubah reaksi menjadi teks seperti “Bereaksi dengan: 👍”, asisten akan melihatnya sebagai pesan teks biasa dan memutuskan sendiri apakah perlu membalas atau tidak. Mengirimkan tipe reaksi akan menghindari hal tersebut.

Apa yang Anda Dapatkan #

Permintaan yang berhasil akan mengembalikan:

{
  "success": true,
  "messageId": "1234567890"
}

Jika terjadi kesalahan, Anda akan mendapatkan pesan error yang menjelaskan masalahnya:

{
  "error": "Message body cannot be empty"
}

Kode Status #

Jika Anda mengatur customData.status, satu-satunya nilai yang diterima adalah "received" — jangan sertakan sama sekali untuk menggunakan nilai default alih-alih mengirimkan nilai lain, atau Anda akan mendapatkan 400.

Mengirim Lampiran Media (Gambar, Video, File) #

Bagian ini membahas file yang masuk ke dalam (dari platform Anda ke aplikasi). Untuk file yang keluar bersama balasan, lihat Balasan Dengan File.

Anda dapat menyertakan lampiran file (gambar, video, audio, dokumen) bersama pesan Anda. Ada dua cara untuk melakukannya:

Opsi 1: Tautan ke File #

Jika file sudah dihosting secara online, berikan URL (alamat web) tempat platform dapat mengunduhnya:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Opsi 2: Sematkan File Secara Langsung (Base64) #

Jika file tidak dihosting secara online, Anda dapat menyematkannya langsung ke dalam pesan sebagai teks yang disandikan (format base64). Hal ini umum dilakukan dalam integrasi teknis di mana sistem Anda membuat file secara langsung (on the fly). Platform akan secara otomatis mendekode dan menyimpan file tersebut:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Menyiapkan Pesan Keluar (platform ke Platform Anda) #

Saat platform mengirim balasan pada saluran kustom (baik dari AI atau diketik oleh Anda), platform secara otomatis mengirim balasan tersebut ke URL di sistem Anda agar sistem Anda dapat mengirimkannya ke pengguna akhir.

Atur URL webhook terlebih dahulu. Anda harus menyimpan URL webhook saluran kustom sebelum balasan apa pun dapat dikirimkan. Jika tidak ada URL yang disimpan, balasan tetap dibuat dan disimpan, tetapi tidak pernah dikirim keluar — dan statusnya tidak akan menunjukkan “Gagal”, sehingga tidak ada apa pun di kotak masuk Anda yang menandai masalah tersebut. Selalu konfigurasikan URL webhook sebelum mulai digunakan.

Beri Tahu Aplikasi Ke Mana Harus Mengirim Balasan #

1. Di bilah sisi kiri, klik Pengaturan di dekat bagian bawah.
2. Di bilah sisi kiri Pengaturan, di bawah Saluran, klik Saluran.
3. Temukan kartu Saluran kustom di bagian paling bawah halaman (setelah Android SMS Gateway, iMessage, widget obrolan situs web, Akun Twilio, dan Kepatuhan regulasi).
4. Masukkan URL Webhook — URL di platform Anda tempat AI harus mengirim pesan keluar (pengembang Anda menyiapkan ini untuk menerima dan memproses balasan). URL tersebut harus berupa URL HTTPS publik — alamat http:// dan host non-publik akan ditolak.
5. Klik Simpan.

Apa yang Dikirim Platform ke Platform Anda #

Ketika platform mengirimkan balasan, platform Anda akan menerima data berikut:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": null,
  "mediaContentType": null,
  "mediaFileName": null,
  "isVoiceNote": false
}

Apa Arti Setiap Bidang #

Platform Anda menerima data ini dan menggunakannya untuk mengirimkan balasan ke pengguna akhir melalui sistem Anda sendiri.

Balasan Dengan File #

Balasan membawa file jika:

• Agen AI mengirim item dari pustaka medianya (brosur, daftar harga, foto),
• seseorang melampirkan file atau merekam catatan suara di kotak masuk,
• pesan dikirim melalui API dengan mediaUrl dan mediaContentType.

File tiba dalam panggilan webhook yang sama dengan teks, di empat bidang media… di atas. Balasan yang hanya berisi teks akan mengatur semuanya ke null (dan isVoiceNote ke false), sehingga penerima yang hanya membaca body akan tetap berfungsi tanpa perubahan.

{
  "contactId": "abc123",
  "messageId": "msg-789",
  "userId": "your-user-id",
  "body": "Here is our pricing breakdown.",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": "https://storage.googleapis.com/.../Pricing.pdf?X-Goog-Signature=...",
  "mediaContentType": "application/pdf",
  "mediaFileName": "Pricing.pdf",
  "isVoiceNote": false
}

Ambil mediaUrl dengan GET biasa (tanpa login, tanpa header tambahan) dan teruskan file tersebut ke pengguna akhir melalui saluran Anda sendiri. Kirim body sebagai keterangan atau sebagai pesan teks terpisah, mana pun yang didukung oleh saluran Anda.

Bagaimana Platform Melacak Pengiriman #

Setelah mengirim balasan ke platform Anda, platform akan memperbarui status pesan:

• Terkirim - Platform Anda menerima pesan dengan sukses.
• Gagal - Platform Anda mengembalikan kesalahan atau tidak dapat dijangkau. Platform menyimpan detail kesalahan bersama pesan tersebut sehingga Anda dapat melakukan pemecahan masalah.

Mengirim Pesan dari Sistem Anda ke Aplikasi #

Selain menerima pesan, Anda juga dapat mengirim pesan keluar melalui saluran kustom langsung dari sistem Anda sendiri. Ini berguna saat Anda ingin memulai percakapan atau mengirim pesan proaktif.

Persyaratan paket. Mengirim dan menyinkronkan pesan melalui API memerlukan paket yang mencakup akses API dan setidaknya satu saluran pesan. Jika Anda menerima kesalahan 403 “permission denied / feature not enabled”, paket Anda saat ini tidak menyertakannya — tingkatkan paket Anda atau hubungi dukungan.

Tempat Mengirim #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Format Pesan #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Bidang yang Diperlukan #

Bidang opsional (campaignId, firstName, lastName, email) berfungsi sama seperti pada pesan masuk — bidang tersebut membantu platform membuat atau memperbarui catatan kontak.

Apa yang Anda Dapatkan #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Merekam Pesan yang Dikirim dari Sistem Lain #

Terkadang Anda telah mengirim pesan ke kontak dari alat yang berbeda (misalnya, alur kerja di platform lain), dan Anda hanya ingin platform mengetahuinya agar AI memiliki konteks lengkap. Ini berbeda dengan pengiriman: platform mencatat pesan tersebut tetapi tidak mengirimkannya kembali ke kontak.

Tempat Mengirim #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Sertakan customData.fromId (ID kontak di platform Anda) dan customData.body (teks pesan yang sudah dikirim).

Cara Kerjanya #

• Pesan dicatat, tidak dikirim ulang. Platform menyimpannya dalam percakapan hanya untuk konteks.
• AI dijeda pada kontak tersebut secara default. Ini mencegah bot membalas di atas pesan yang sudah ditangani manusia. Untuk menjaga bot tetap aktif, teruskan customData.pauseAi: false.
• Kontak baru dapat dibuat secara otomatis. Sertakan customData.customChannel dan kontak akan dibuat jika belum ada.
• Duplikat diabaikan. Jika Anda menggunakan kembali messageSid yang sama, platform mengenali bahwa pesan telah dicatat dan tidak melakukan perubahan apa pun.

Persyaratan paket. Seperti halnya mengirim, merekam pesan melalui API memerlukan paket yang mencakup akses API dan setidaknya satu saluran pesan. Kesalahan 403 “permission denied / feature not enabled” berarti paket Anda saat ini tidak menyertakan fitur tersebut.

Contoh Dunia Nyata #

Obrolan Langsung Situs Web #

Hubungkan widget obrolan langsung di situs web Anda ke platform agar Agen AI Anda dapat menjawab pertanyaan pengunjung:

1. Pengunjung mengetik pesan di widget obrolan situs web Anda.
2. Widget obrolan Anda mengirimkan pesan tersebut ke platform.
3. Agen AI menghasilkan respons.
4. Respons dikirim kembali ke widget obrolan Anda, yang kemudian menampilkannya kepada pengunjung.

Mengapa ini berguna: Pengunjung situs web Anda mendapatkan jawaban instan berbasis AI atas pertanyaan mereka tanpa Anda perlu online.

Email #

Arahkan percakapan email melalui platform agar Agen AI Anda dapat membalas email:

1. Siapkan sistem yang meneruskan email masuk ke platform (menggunakan alamat pengirim email sebagai fromId, subjek dan isi email sebagai body, dan "email" sebagai channel).
2. Agen AI membaca email tersebut dan membuat balasan.
3. Balasan dikirim kembali ke sistem email Anda, yang kemudian mengirimkannya sebagai respons email biasa.

Mengapa ini berguna: Pertanyaan umum melalui email (harga, jam operasional, ketersediaan) dijawab secara instan oleh Agen AI Anda.

Jika sistem email Anda mendukung IMAP/SMTP atau OAuth, saluran Email bawaan mungkin lebih sederhana daripada integrasi kustom.

Integrasi CRM #

Hubungkan sistem CRM (manajemen hubungan pelanggan) Anda yang sudah ada ke platform:

1. Saat prospek mengirim pesan melalui CRM Anda, teruskan pesan tersebut ke platform.
2. Agen AI merespons dan melacak percakapan tersebut.
3. Respons AI dikirim kembali ke CRM Anda untuk dikirimkan.
4. Riwayat percakapan lengkap tersedia baik di platform maupun di CRM Anda.

Mengapa ini berguna: Tim penjualan Anda mendapatkan respons yang dibantu AI untuk prospek tanpa harus meninggalkan CRM mereka.

Sistem Tiket Dukungan #

Gunakan platform ini sebagai penanggap pertama berbasis AI untuk dukungan pelanggan:

1. Sistem tiket Anda meneruskan tiket dukungan baru ke platform.
2. Agen AI mengirimkan respons awal (misalnya, mengakui tiket dan mengajukan pertanyaan klarifikasi).
3. Respons dilampirkan pada tiket di sistem dukungan Anda.
4. Tim dukungan Anda dapat meninjau apa yang dikatakan AI dan mengambil alih jika diperlukan.

Mengapa ini berguna: Pelanggan mendapatkan pengakuan dan bantuan awal secara instan, bahkan di luar jam kerja.

Pemecahan Masalah #

Pesan Tidak Diterima oleh platform #

• Pastikan kunci API Anda benar dan aktif (periksa Pengaturan → Integrasi → Kunci API).
• Pastikan Anda mengirim permintaan POST (bukan GET). Pengembang Anda akan mengetahui perbedaannya.
• Periksa apakah kolom customData.body tidak kosong atau hanya berisi spasi.
• Pastikan kolom customData.fromId disertakan.
• Baca pesan respons untuk detail kesalahan spesifik.

Balasan Tidak Sampai ke Platform Anda #

• Pastikan Anda telah memasukkan URL platform Anda di kartu Saluran kustom pada halaman Saluran. Jika tidak ada URL yang disimpan, balasan akan dibuat dan disimpan tetapi tidak pernah dikirim — dan balasan tersebut tidak akan ditandai sebagai “Gagal,” jadi periksa hal ini terlebih dahulu.
• Pastikan URL dapat diakses secara publik (tidak di balik login atau firewall) dan mengembalikan respons sukses.
• Hanya balasan (pesan keluar) yang dikirim ke URL Anda — pesan masuk tidak memicu hal ini.
• Periksa detail kesalahan pada pesan di kotak masuk Anda.
• Balasan dengan file tiba dalam panggilan yang sama, dengan tautan unduhan di mediaUrl. Jika penerima Anda hanya meneruskan body, file tersebut akan terabaikan di sisi Anda — baca juga bidang media… (lihat Balasan Dengan File).
• Tautan mediaUrl kedaluwarsa setelah satu jam. Unduh saat webhook tiba, jangan nanti dari antrean.

Kontak Tidak Dibuat #

• Pastikan nilai fromId konsisten untuk pengguna yang sama di semua pesan mereka. Platform menggunakan nilai ini untuk mengidentifikasi kontak — jika nilai ini berubah di antara pesan, platform akan membuat kontak baru setiap saat.
• Sertakan firstName, lastName, dan email dalam pesan pertama dari kontak baru untuk membuat catatan kontak yang lengkap.

Lampiran Media Tidak Berfungsi #

• Untuk tautan file (URL), pastikan file dapat diakses secara publik (tidak diperlukan login untuk mengaksesnya).
• Selalu sertakan mediaContentType saat Anda menyertakan mediaUrl.
• Untuk file yang disematkan (base64), verifikasi formatnya adalah data:MIME_TYPE;base64,ENCODED_DATA.
• Pastikan jenis file yang Anda tentukan sesuai dengan konten file yang sebenarnya.

Praktik Terbaik #

• Gunakan nilai fromId yang konsisten. Setiap pengguna di platform Anda harus selalu memiliki fromId yang sama. Ini memastikan platform mengelompokkan semua pesan mereka ke dalam satu percakapan alih-alih membuat kontak duplikat.
• Pilih nama channel yang jelas. Pilih sesuatu yang deskriptif seperti "website-chat", "email", atau "zendesk" agar Anda dapat dengan mudah mengetahui dari mana pesan berasal saat melihat kotak masuk Anda.
• Sertakan detail kontak (firstName, lastName, email) dalam pesan pertama dari kontak baru. Ini akan langsung membuat catatan kontak yang lengkap dan berguna.
• Bangun logika percobaan ulang (retry logic). Minta platform Anda mencoba mengirim ulang pesan jika platform tidak merespons pada percobaan pertama (gangguan jaringan bisa terjadi).
• Gunakan nilai messageSid yang unik untuk setiap pesan. Ini mencegah pesan yang sama diproses dua kali jika sistem Anda mengirimkannya lebih dari sekali.
• Gunakan campaignId untuk mengarahkan pesan ke Agen AI yang berbeda jika Anda memiliki beberapa kasus penggunaan (misalnya, pertanyaan penjualan vs. pertanyaan dukungan).
• Uji sebelum diluncurkan. Kirim pesan uji coba di kedua arah dan pastikan kontak, percakapan, dan respons AI semuanya berfungsi dengan benar sebelum diluncurkan ke pengguna nyata.