Panduan integrasi API platform chat

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

  • Melakukan 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.

  • Mengirim pesan teks ke chat.

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

  • Akhiri chat setelah percakapan selesai.

Panduan ini ditujukan untuk developer yang membangun layanan backend yang menghubungkan pengalaman chat milik pelanggan ke CCAI Platform. Panduan ini mengasumsikan bahwa Anda dapat membuat kredensial API di CCAI Platform, menghosting endpoint webhook HTTPS, menyimpan secret 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 implementasi menyeluruh 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 percakapan 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 CCAI Platform dari Settings > Developer Settings > API Credentials.

    • Simpan rahasia kredensial dengan aman. Jangan mengeksposnya di kode browser atau 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 CCAI Platform.

    • Konfigurasikan endpoint di setelan developer CCAI Platform.

    • Buat dan simpan rahasia utama dan sekunder webhook.

  • Konfigurasi antrean atau menu

    • Identifikasi antrean atau menu yang dimasuki chat baru.

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

  • Identitas pengguna akhir

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

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

  • Penanganan pembatasan kapasitas

    • CCAI Platform membatasi kapasitas Apps API. Buat percobaan ulang dan backoff ke dalam integrasi Anda, dan hindari mengirimkan burst permintaan untuk satu tenant.

Autentikasi dan keamanan webhook

Integrasi Anda menggunakan dua jalur autentikasi:

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

  • 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 CCAI Platform di bagian Settings > Developer Settings > API Credentials, dan 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 API untuk mengetahui 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 secret sisi server, rotasikan 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. Tolak 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 yang aktif.

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

  7. Terima permintaan jika ada secret aktif yang cocok.

Contoh implementasi 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, tampilkan respons berhasil dengan cepat dan proses peristiwa secara idempoten. Pengiriman webhook dan respons API dapat tiba dalam urutan yang berbeda, jadi bangun integrasi Anda untuk menoleransi penerimaan perubahan status yang sama lebih dari sekali tanpa membuat data duplikat.

Alur integrasi

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

Membuat atau memperbarui pengguna akhir

Sasaran: Pastikan CCAI Platform 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 perlu disimpan

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

Proses selanjutnya

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

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

Membuat chat

Sasaran: Memulai chat CCAI Platform baru untuk pengguna akhir.

Endpoint

Gunakan endpoint berikut untuk memulai chat 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 pemilihan rute agen virtual

Jika agen virtual pemilihan antrean Anda memerlukan konteks dari aplikasi, 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 chat.

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 update pada data chat yang sama, yang dikunci oleh ID chat.

Memproses peristiwa webhook chat

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

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

  • ID Chat.

  • Jenis peristiwa.

  • Stempel waktu peristiwa.

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

  • Data eskalasi atau defleksi jika peristiwa menjelaskan perilaku pemilihan rute.

Perilaku yang direkomendasikan

  • Verifikasi setiap tanda tangan webhook sebelum memproses peristiwa.

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

  • Menampilkan respons 2xx setelah menerima peristiwa.

  • Proses efek samping downstream secara asinkron jika memungkinkan.

Proses selanjutnya

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

Mengirim SMS

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

Endpoint

Gunakan endpoint berikut untuk mengirim pesan teks ke 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 tersebut, 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. Memverifikasi tanda tangan webhook.

  2. Periksa apakah peristiwa tersebut baru.

  3. Identifikasi chat berdasarkan ID chat.

  4. Identifikasi pengirim dan jenis pesan.

  5. Merender pesan di UI chat milik pelanggan.

  6. Pertahankan peristiwa agar pemuatan ulang atau percobaan ulang tidak menghilangkan 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 tidak berurutan, gunakan stempel waktu peristiwa dan lapisan persistensi Anda sendiri untuk menyesuaikan urutan tampilan.

Meningkatkan interaksi dari agen virtual ke agen manusia

Sasaran: Memindahkan chat dari penanganan agen virtual ke antrean manusia saat pengguna akhir memerlukan bantuan agen.

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

Endpoint

Gunakan endpoint berikut untuk mengeskalasi chat dari agen virtual ke agen manusia:

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

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengeskalasi chat:

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

Proses selanjutnya

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

  • Jika antrean tidak dapat menerima chat dan alternatif pengalihan dikonfigurasi, CCAI Platform akan mempertahankan chat dengan agen virtual dan mengirim peristiwa webhook escalation_deflected yang membawa alternatif yang tersedia untuk pengguna akhir. Alternatif tidak pernah muncul dalam respons eskalasi.

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

Mencatat pilihan pengalihan eskalasi

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

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

Endpoint

Gunakan endpoint berikut untuk memperbarui data eskalasi dengan pilihan defleksi:

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 kelebihan kapasitas.

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mencatat pilihan pengalihan:

{
  "deflection_channel": "email"
}

Hanya kirim 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, chat akan berakhir.

Proses selanjutnya

CCAI Platform mencatat pilihan pada eskalasi. Merekam pilihan tidak merutekan chat — integrasi Anda bertindak berdasarkan pilihan, misalnya dengan menutup chat untuk pengalihan email atau mengirim eskalasi baru dengan force_escalate: true untuk pilihan tetap menunggu.

Mengakhiri percakapan

Sasaran: Menutup chat saat percakapan selesai.

Endpoint

Gunakan endpoint berikut untuk mengakhiri chat aktif:

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

Contoh permintaan

Contoh berikut menunjukkan isi permintaan untuk mengakhiri chat:

{
  "ended_by_user_id": 456
}

Proses selanjutnya

  • CCAI Platform mengakhiri chat.

  • Endpoint webhook Anda menerima peristiwa status chat akhir.

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

Jika chat berakhir karena pengguna akhir memilih opsi pengalihan, jangan gunakan endpoint ini sebagai pengganti pencatatan pilihan tersebut. Catat pilihan pada eskalasi terlebih dahulu, atau catat dan tutup chat dalam satu permintaan dengan PATCH /apps/api/v1/chats/{chat_id}, yang menyediakan escalation_id dan deflection_channel bersama status. Percakapan yang berakhir tanpa pilihan yang dicatat akan membuat pilihan tidak tercatat pada eskalasi dan tidak ada dalam pelaporan hasil pengalihan.

Alur lanjutan

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

Mengimpor transkrip pra-chat

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

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

Referensi Apps API menyertakan skema transkrip yang tepat.

Merutekan chat 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. Membuat agen virtual untuk pemilihan antrean.

  2. Menetapkan agen virtual ke antrean entri.

  3. Sertakan konteks saat Anda membuat chat.

  4. Konfigurasikan agen virtual untuk memeriksa konteks dan mengeskalasi chat ke antrean yang benar.

  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 — Meminta URL upload yang telah ditandatangani

Gunakan endpoint berikut untuk meminta URL yang telah ditandatangani 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 — Mengupload file ke URL penyimpanan yang ditampilkan

Sertakan file dan kolom apa pun yang ditampilkan CCAI Platform dalam respons upload yang telah ditandatangani.

Tahap 3 — Menambahkan file yang diupload ke chat

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 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": "Photo of the damaged item",
    "media_id": 789
  }
}

Endpoint menerima type, content, dan media_id sebagai nilai tetap; objek bertingkat yang disediakan di content akan dihapus dan referensi media akan hilang. Gunakan jenis pesan video dan media_id video untuk pesan video. media_id adalah seinduk dari content.

Mengirim data kustom selama chat

Gunakan endpoint berikut saat integrasi Anda perlu melampirkan konteks yang ditentukan pelanggan ke chat 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 chat

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 CCAI Platform untuk mengaitkan chat dengan identitas pengguna akhir yang diperbarui.

Mengumpulkan data CSAT atau rating

Gunakan endpoint rating dan CSAT chat berikut jika 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.