Panduan integrasi API platform chat

Gunakan panduan ini untuk membuat integrasi chat sisi server dengan Apps API. Pada akhirnya, integrasi Anda akan dapat:

  • Lakukan autentikasi ke Apps API.

  • Membuat atau memperbarui pengguna akhir.

  • Mulai chat untuk pengguna akhir tersebut.

  • Menerima dan memverifikasi peristiwa webhook dari Contact Center AI Platform.

  • Kirim pesan teks ke dalam chat.

  • Tangani cabang opsional seperti impor transkrip pra-chat, perutean agen virtual pemilihan antrean, pembelokan eskalasi, dan lampiran media.

  • Akhiri chat setelah percakapan selesai.

Panduan ini ditujukan bagi developer yang sedang membangun layanan backend yang menghubungkan pengalaman chat milik pelanggan ke Platform CCAI. Panduan ini mengasumsikan Anda dapat membuat kredensial API di Platform CCAI, menghosting endpoint webhook HTTPS, menyimpan rahasia dengan aman, dan membuat permintaan HTTP dari server Anda.

Panduan ini melengkapi endpoint Chat Apps API. Gunakan referensi API untuk skema permintaan dan respons yang lengkap, dan gunakan panduan ini untuk alur penerapan end-to-end yang direkomendasikan.

Terminologi

Definisi berikut berlaku untuk dokumen ini:

  • Pelanggan: Pelanggan CCAI Platform yang menerapkan integrasi chat di software mereka sendiri.

  • Konsumen: Aplikasi sisi server milik pelanggan yang membuat permintaan ke Apps API dan menerima peristiwa webhook CCAI Platform.

  • Pengguna akhir: Orang yang menggunakan software pelanggan untuk memulai atau melanjutkan chat dengan agen atau agen virtual.

  • Chat: Resource percakapan CCAI Platform yang dibuat oleh Apps API.

  • Endpoint webhook: Endpoint HTTPS di aplikasi konsumen yang menerima peristiwa chat dari CCAI Platform.

Sebelum memulai

Sebelum memulai, pastikan Anda memiliki hal-hal berikut:

  • Kredensial Apps API

    • Buat kredensial API di Platform CCAI dari Settings > Developer Settings > API Credentials.

    • Simpan rahasia kredensial dengan aman. Jangan menampilkannya di browser atau kode klien seluler.

  • Detail URL tenant

    • Identifikasi subdomain dan domain CCAI Platform Anda.

    • URL dasar Apps API adalah: https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • Endpoint webhook

    • Menghosting endpoint HTTPS publik yang dapat menerima permintaan POST dari Platform CCAI.

    • Konfigurasi endpoint di setelan developer Platform CCAI.

    • Buat dan simpan secret utama dan sekunder webhook.

  • Konfigurasi antrean atau menu

    • Identifikasi antrean atau menu tempat percakapan baru masuk.

    • Jika Anda menggunakan agen virtual pemilihan antrean, konfigurasikan agen virtual tersebut dan tetapkan ke antrean masuk sebelum membuat percakapan melalui API.

  • Identitas pengguna akhir

    • Tentukan ID stabil mana yang akan digunakan sistem Anda untuk setiap pengguna akhir.

    • Simpan ID pengguna akhir Platform CCAI yang ditampilkan oleh Apps API.

  • Penanganan pembatasan kapasitas

    • CCAI Platform membatasi frekuensi panggilan Apps API. Bangun percobaan ulang dan backoff ke dalam integrasi Anda, dan hindari mengirimkan serangkaian permintaan untuk satu penyewa.

Keamanan webhook dan autentikasi

Integrasi Anda menggunakan dua jalur autentikasi:

  • Autentikasi Apps API untuk permintaan dari server Anda ke Platform CCAI.

  • Verifikasi tanda tangan webhook untuk permintaan dari CCAI Platform ke server Anda.

Mengautentikasi permintaan Apps API

Permintaan menggunakan autentikasi dasar HTTP. Buat token API di Platform CCAI di bagian Settings > Developer Settings > API Credentials, lalu teruskan di kolom password (direkomendasikan). Jika tenant Anda menggunakan jalur autentikasi lama, Anda dapat meneruskan kunci perusahaan sebagai nama pengguna dan rahasia perusahaan sebagai sandi. Lihat referensi Apps APIuntuk penyiapan autentikasi lengkap. Contoh berikut menunjukkan cara mengautentikasi permintaan Apps API menggunakan autentikasi dasar:

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

Simpan kredensial di penyimpanan rahasia sisi server, ganti secara berkala sesuai dengan kebijakan keamanan Anda, dan jangan pernah mengirimkannya di browser atau aplikasi seluler.

Memverifikasi permintaan webhook

CCAI Platform mengirimkan peristiwa chat ke endpoint webhook Anda. Setiap permintaan webhook mencakup:

  • X-Signature

  • X-Signature-Timestamp

Header X-Signature dapat berisi tanda tangan utama, tanda tangan sekunder, atau keduanya:

primary=<primary_signature> secondary=<secondary_signature>

Setiap tanda tangan adalah digest HMAC-SHA256 berenkode Base64. Nilai yang ditandatangani adalah header stempel waktu yang digabungkan dengan isi permintaan JSON mentah:

X-Signature-Timestamp + raw_request_body

Di pengendali webhook Anda:

  1. Baca X-Signature dan X-Signature-Timestamp.

  2. Tolak permintaan jika salah satu header tidak ada.

  3. Menolak stempel waktu yang sudah tidak berlaku untuk mengurangi risiko replay.

  4. Baca isi permintaan mentah sebelum mengurai JSON.

  5. Hitung tanda tangan yang diharapkan menggunakan setiap rahasia webhook aktif.

  6. Bandingkan tanda tangan yang diterima dan tanda tangan yang diharapkan menggunakan perbandingan waktu konstan.

  7. Menerima permintaan jika ada rahasia aktif yang cocok.

Contoh penerapan Ruby berikut menunjukkan cara memverifikasi tanda tangan webhook UJET:

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

Jika verifikasi berhasil, segera tampilkan respons keberhasilan dan proses peristiwa secara idempoten. Pengiriman webhook dan respons API dapat tiba dalam urutan yang berbeda, jadi buat integrasi Anda agar dapat menerima perubahan status yang sama lebih dari sekali tanpa membuat data duplikat.

Alur integrasi

Alur berikut membuat pengguna akhir, memulai chat, menerima peristiwa Platform CCAI, bertukar pesan, dan mengakhiri chat.

Membuat atau memperbarui pengguna akhir

Tujuan: Pastikan Platform CCAI memiliki data pengguna akhir sebelum Anda membuat chat.

Endpoint

Gunakan endpoint berikut untuk membuat atau memperbarui pengguna akhir:

POST /apps/api/v1/end_users

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk membuat atau memperbarui pengguna akhir:

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

Yang harus disimpan

Simpan ID pengguna akhir Platform CCAI dari respons di sistem Anda. Gunakan ID tersebut saat Anda membuat percakapan.

Proses selanjutnya

  • Jika pengguna akhir tidak ada, Platform CCAI akan membuat rekaman baru.

  • Jika pengguna akhir dengan ID yang sama sudah ada, Platform CCAI akan memperbarui data dan menampilkan informasi pengguna akhir yang ada.

Membuat chat

Sasaran: Memulai percakapan CCAI Platform baru untuk pengguna akhir.

Endpoint

Gunakan endpoint berikut untuk memulai percakapan baru:

POST /apps/api/v1/chats

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk membuat chat:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Konteks opsional untuk perutean agen virtual

Jika agen virtual pemilihan antrean Anda memerlukan konteks dari aplikasi Anda, sertakan payload konteks saat Anda membuat chat, seperti yang ditunjukkan dalam contoh berikut:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

Agen virtual dapat menggunakan nilai dari konteks tersebut untuk memutuskan antrean mana yang menerima percakapan.

Proses selanjutnya

  • Apps API menampilkan resource chat.

  • CCAI Platform mengirimkan peristiwa webhook chat_created ke endpoint webhook yang Anda konfigurasi.

  • Respons API dan peristiwa webhook dapat tiba dalam urutan apa pun. Perlakukan keduanya sebagai pembaruan pada rekaman chat yang sama, yang dikunci oleh ID chat.

Memproses peristiwa webhook chat

Sasaran: Menjaga aplikasi konsumen tetap disinkronkan dengan status chat Platform CCAI.

Endpoint webhook Anda menangani siklus proses chat dan peristiwa pesan dari Platform CCAI. Setidaknya, simpan:

  • ID Chat.

  • Jenis peristiwa.

  • Stempel waktu peristiwa.

  • Pengirim pesan, jenis pesan, dan isi pesan saat peristiwa berisi pesan.

  • Data eskalasi atau pengalihan saat peristiwa menjelaskan perilaku perutean.

Perilaku yang direkomendasikan

  • Verifikasi setiap tanda tangan webhook sebelum memproses peristiwa.

  • Simpan ID peristiwa yang diproses atau kunci peristiwa deterministik sehingga percobaan ulang tidak membuat duplikat.

  • Menampilkan respons 2xx setelah menerima acara.

  • Proses efek samping downstream secara asinkron jika memungkinkan.

Proses selanjutnya

Aplikasi Anda memperbarui status chatnya saat CCAI Platform mengirimkan peristiwa seperti pembuatan chat, pesan masuk, pesan agen, perubahan eskalasi, dan penyelesaian chat.

Mengirim SMS

Tujuan: Mengirim pesan pengguna akhir dari aplikasi konsumen ke chat CCAI Platform.

Endpoint

Gunakan endpoint berikut untuk mengirim pesan teks ke dalam chat:

POST /apps/api/v1/chats/{chat_id}/message

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengirim pesan teks:

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

Proses selanjutnya

  • CCAI Platform menerima pesan.

  • Pesan akan muncul dalam percakapan agen atau agen virtual.

  • Endpoint webhook Anda menerima peristiwa pesan untuk pesan, termasuk pesan yang dikirim oleh aplikasi Anda sendiri melalui Apps API.

Menerima dan menampilkan pesan dari CCAI Platform

Sasaran: Menampilkan pesan agen atau agen virtual dalam pengalaman chat milik pelanggan.

Saat endpoint webhook Anda menerima peristiwa pesan:

  1. Verifikasi tanda tangan webhook.

  2. Periksa apakah acara tersebut baru.

  3. Identifikasi chat berdasarkan ID chat.

  4. Identifikasi pengirim dan jenis pesan.

  5. Tampilkan pesan di UI chat milik pelanggan.

  6. Pertahankan peristiwa agar pemuatan ulang atau percobaan ulang tidak menghapus histori percakapan.

Proses selanjutnya

UI chat milik pelanggan menampilkan pesan yang dikirim oleh agen, agen virtual, dan pengguna akhir dalam urutan yang benar. Jika peristiwa tiba tidak berurutan, gunakan stempel waktu peristiwa dan lapisan persistensi Anda sendiri untuk menyelaraskan urutan tampilan.

Melakukan eskalasi dari agen virtual ke agen manusia

Sasaran: Mengalihkan percakapan dari penanganan agen virtual ke antrean agen manusia saat pengguna akhir memerlukan bantuan agen.

Jika integrasi Anda menggunakan agen virtual pemilihan antrean, konfigurasi agen virtual untuk mengarahkan percakapan ke antrean target. Jika server Anda memulai eskalasi secara langsung, gunakan endpoint eskalasi Apps API.

Endpoint

Gunakan endpoint berikut untuk mengeskalasikan percakapan dari agen virtual ke agen manusia:

POST /apps/api/v1/chats/{chat_id}/escalations

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengeskalasikan percakapan:

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

Proses selanjutnya

  • Jika antrean target tersedia, chat akan beralih ke penanganan agen.

  • Jika antrean tidak tersedia karena kondisi di luar jam kerja atau kelebihan kapasitas, Platform CCAI dapat menampilkan atau mengirimkan opsi pengalihan melalui alur chat.

  • Integrasi Anda merender opsi pengalihan yang tersedia kepada pengguna akhir.

Mencatat pilihan pengalihan eskalasi

Tujuan: Memberi tahu CCAI Platform opsi pengalihan mana yang dipilih pengguna akhir.

Saat CCAI Platform menawarkan opsi pengalihan eskalasi, catat pilihan pengguna akhir dengan endpoint update eskalasi.

Endpoint

Gunakan endpoint berikut untuk memperbarui catatan eskalasi dengan pilihan pengalihan:

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Nilai deflection_channel yang didukung:

  • email — pengguna akhir memilih opsi pengalihan email.

  • virtual_agent — pengguna akhir memilih untuk melanjutkan dengan agen virtual.

  • human_agent — pengguna akhir memilih untuk terus menunggu agen manusia. Nilai ini hanya berlaku untuk pengalihan karena kapasitas berlebih.

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk merekam pilihan pengalihan:

{
  "deflection_channel": "email"
}

Kirimkan hanya nilai deflection_channel yang didukung ke endpoint ini. external_link bukan nilai yang valid untuk endpoint pembaruan eskalasi; saat pengguna akhir mengikuti link pengalihan eksternal, percakapan akan berakhir.

Proses selanjutnya

Platform CCAI memperbarui catatan eskalasi dan mengalihkan percakapan sesuai dengan opsi yang dipilih.

Mengakhiri percakapan

Sasaran: Tutup chat setelah percakapan selesai.

Endpoint

Gunakan endpoint berikut untuk mengakhiri percakapan aktif:

PATCH /apps/api/v1/chats/{chat_id}/end

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengakhiri percakapan:

{
  "ended_by_user_id": 456
}

Proses selanjutnya

  • CCAI Platform mengakhiri percakapan.

  • Endpoint webhook Anda menerima peristiwa chat-state akhir.

  • Aplikasi Anda menandai percakapan sebagai selesai dan berhenti menerima pesan baru dari pengguna akhir untuk percakapan tersebut.

Alur lanjutan

Cabang berikut bersifat opsional. Terapkan hanya alur yang berlaku untuk integrasi Anda.

Mengimpor transkrip pra-chat

Gunakan alur ini saat pengguna akhir sudah melakukan percakapan di sistem Anda sebelum Anda membuat percakapan Platform CCAI, seperti percakapan chatbot.

Tambahkan payload transkrip saat Anda membuat chat. Transkrip memberikan konteks kepada agen sehingga pengguna akhir tidak perlu mengulangi informasi.

Referensi Apps API mencakup skema transkrip yang tepat.

Merutekan percakapan dengan agen virtual pemilihan antrean

Gunakan alur ini saat aplikasi Anda mengirim semua chat baru ke antrean entri dan memungkinkan agen virtual memutuskan antrean target akhir.

  1. Buat agen virtual untuk pemilihan antrean.

  2. Tetapkan agen virtual ke antrean masuk.

  3. Sertakan konteks saat Anda membuat percakapan.

  4. Konfigurasi agen virtual untuk memeriksa konteks dan mengalihkan percakapan ke antrean yang tepat.

  5. Menangani opsi pengalihan jika antrean target tidak tersedia.

Mengirim lampiran foto atau video

Gunakan alur ini saat pengguna akhir mengirim media dari UI chat milik pelanggan.

Alur media memiliki empat tahap.

Tahap 1 — Minta URL upload yang telah ditandatangani

Gunakan endpoint berikut untuk meminta URL yang telah ditandatangani sebelumnya untuk mengupload foto atau video:

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

Tahap 2 — Upload file ke URL penyimpanan yang ditampilkan

Sertakan file dan kolom apa pun yang ditampilkan CCAI Platform dalam respons presigned-upload.

Tahap 3 — Menambahkan file yang diupload ke percakapan

Gunakan endpoint berikut untuk menambahkan foto atau video yang diupload ke chat:

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Simpan media_id yang ditampilkan CCAI Platform. Payload pesan chat merujuk ke media berdasarkan ID media.

Tahap 4 — Mengirim media sebagai pesan

Gunakan endpoint berikut untuk mengirim pesan media ke dalam chat:

POST /apps/api/v1/chats/{chat_id}/message

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengirim lampiran foto:

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": {
      "media_id": 789
    }
  }
}

Gunakan jenis pesan video dan video media_id untuk pesan video.

Mengirim data kustom selama percakapan

Gunakan endpoint berikut saat integrasi Anda perlu melampirkan konteks yang ditentukan pelanggan ke percakapan aktif:

POST /apps/api/v1/chats/{chat_id}/custom_data

Referensi Apps API menentukan bentuk payload yang tepat dan perilaku kunci yang dicadangkan.

Memperbarui identitas pengguna akhir selama percakapan

Gunakan endpoint berikut saat identitas pengguna akhir berubah atau diketahui setelah chat dimulai:

POST /apps/api/v1/chats/{chat_id}/end_user

Misalnya, gunakan endpoint ini saat pengguna akhir anonim login selama chat aktif dan integrasi Anda memerlukan Platform CCAI untuk mengaitkan chat dengan identitas pengguna akhir yang diperbarui.

Mengumpulkan data CSAT atau rating

Gunakan endpoint CSAT dan rating chat berikut saat integrasi Anda memiliki pengalaman rating pasca-chat:

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

Untuk mengetahui aturan kelayakan dan payload rating yang tepat, lihat referensi Apps API.