Penanganan error, percobaan ulang, dan pengurutan panggilan di CRM kustom (API generik)

Dokumen ini menjelaskan perilaku fitur CRM kustom (API generik) CCAI Platform saat endpoint CRM Anda menampilkan respons selain HTTP 200 "Success.". Dokumen ini dimaksudkan sebagai referensi perilaku bagi integrator yang mengonfigurasi endpoint akun API dan endpoint data API.

Hubungan dan urutan eksekusi tingkat tinggi

Saat interaksi memicu integrasi CRM kustom, platform akan memanggil endpoint Anda dalam urutan ini:

  1. Operasi tingkat akun (akun API) - kontak

    Contoh:

    • Temukan kontak.

    • Membuat kontak.

    • Memperbarui kontak.

  2. Operasi tingkat data (data API) - tiket atau kasus

    Contoh:

    • Cari tiket.

    • Buat tiket.

    • Memperbarui tiket.

  3. Tindakan setelah sesi (jika dikonfigurasi)

    Contoh:

    • Tambahkan komentar atau catatan.

    • Upload lampiran atau transkrip.

    • Terapkan pembaruan pada penyelesaian.

Langkah-langkah sebelumnya biasanya menghasilkan ID yang dapat digunakan oleh langkah-langkah berikutnya. Misalnya, contact_id dapat diteruskan ke pembuatan tiket saat disertakan dalam template payload endpoint Anda, dan ticket_id diperlukan untuk tindakan pasca-sesi dalam penyiapan API generik standar. Perhatikan bahwa tidak semua endpoint dikonfigurasi untuk mengekstrak ID - lihat Nuansa penting: 2xx + ID tidak ada di endpoint yang mengekstrak ID.

Nuansa penting: 2xx + ID tidak ada di endpoint yang mengekstrak ID

Tidak semua endpoint CRM kustom mengekstrak ID dari respons yang diterimanya. Perilaku ini hanya berlaku untuk endpoint yang dikonfigurasi dengan response_data_location dan (untuk endpoint pembuatan) custom_id_location - biasanya endpoint pencarian (mengekstrak ID data yang ada) dan endpoint pembuatan (mengekstrak ID data yang baru dibuat). Endpoint seperti komentar, lampiran, dan update tidak mengekstrak ID dari responsnya.

Dampak ID yang tidak ada pada endpoint ekstraksi ID

  • Untuk endpoint pencarian: Respons 200 OK tanpa data yang cocok (dan oleh karena itu tidak ada ID yang dapat diekstrak) adalah perilaku "tidak ditemukan" yang normal. Jika instance Anda mengaktifkan skip_account_creation atau skip_record_creation, platform akan sengaja melanjutkan downstream dengan contact_id atau ticket_id null, bukan mencoba pembuatan. Hal ini adalah perilaku yang diharapkan dalam konfigurasi tersebut dan bukan kesalahan konfigurasi.

  • Untuk endpoint pembuatan: Respons 200 OK yang tidak menyertakan ID yang baru dibuat di lokasi yang dikonfigurasi merupakan masalah konfigurasi atau kontrak respons. Permintaan HTTP berhasil, sehingga percobaan ulang tidak akan dipicu - tetapi langkah downstream dapat dilanjutkan dengan data yang tidak ada.

  • Dalam kedua kasus tersebut, kegagalan (jika terjadi kegagalan) muncul sebagai data yang hilang, bukan sebagai error endpoint, yang dapat membingungkan selama proses debug.

Panduan integrator

  • Untuk operasi pembuatan, pastikan untuk menampilkan ID yang diharapkan di lokasi yang dikonfigurasi sebagai bagian dari kontrak keberhasilan Anda, bukan hanya menampilkan 2xx. Anggap ID yang tidak ada sebagai masalah konfigurasi atau kontrak respons yang perlu diselidiki.

  • Untuk operasi pencarian, menampilkan 200 OK tanpa kecocokan dapat diterima. Jika instance Anda sengaja mengandalkan pola "pencarian tanpa pembuatan" (misalnya, skip_account_creation = true), dokumentasikan keputusan tersebut agar endpoint downstream tahu cara menangani ID yang tidak ada dengan baik.

  • Dalam pengujian, pastikan bahwa:

    • Untuk endpoint pembuatan, ID dapat diandalkan dalam respons dan di lokasi yang tepat yang dikonfigurasi di CRM kustom.

    • Untuk endpoint pencarian, perilaku downstream platform cocok dengan konfigurasi flag lewati instance Anda.

Penanganan error: ringkasan

Jika endpoint menampilkan respons tidak berhasil (non-2xx) atau tidak merespons:

  • Platform dapat mencoba ulang permintaan:

    • Sekali, langsung untuk beberapa status.

    • Dalam jangka waktu yang lebih lama untuk kegagalan yang dapat dicoba lagi.

  • Langkah downstream mungkin tertunda saat platform terus mencoba ulang langkah upstream.

  • Beberapa kegagalan diperlakukan sebagai tidak dapat dicoba ulang (misalnya, kegagalan konfigurasi atau validasi).

Aturan percobaan ulang yang mendetail dijelaskan dalam Perilaku percobaan ulang dan backoff. Hubungan antara kegagalan dan panggilan downstream dijelaskan dalam Aturan perantaian dan dependensi.

Aturan perantaian dan dependensi

Perilaku CRM kustom diatur oleh konfigurasi CRM instance Anda - khususnya setelan yang didokumentasikan di Melewati pembuatan akun dan data CRM. Dokumen ini merujuk pada setelan tersebut berdasarkan nama konfigurasi backend-nya (skip_account_creation, skip_account_lookup, skip_record_creation) karena setelan tersebut muncul seperti itu dalam contoh konfigurasi JSON berikut.

Dalam setelan tersebut, platform cenderung melanjutkan rantai jika memungkinkan, misalnya, dengan membuat kontak anonim saat pencarian gagal dan pembuatan akun diaktifkan, daripada selalu "berhenti total".

Dampak kegagalan akun pada operasi data

Langkah data (tiket/kasus) dapat berjalan meskipun langkah akun tidak menghasilkan kontak, tetapi perilaku pastinya bergantung pada konfigurasi instance.

Bergantung pada konfigurasi Anda, platform dapat:

  • Membuat kontak anonim sebagai pengganti dan melanjutkan ke pembuatan tiket.

  • Lanjutkan untuk mencatat langkah-langkah tanpa contact_id saat pencarian akun atau pembuatan akun dikonfigurasi untuk dilewati.

Pengaruhnya bagi endpoint Anda

  • contact_id yang tidak ada saat pembuatan tiket biasanya menunjukkan konfigurasi instance tempat pencarian akun atau pembuatan akun dinonaktifkan.

  • Jika instance Anda memerlukan akun, perlakukan contact_id yang tidak ada sebagai sinyal yang perlu diselidiki, bukan menyisipkan tiket secara diam-diam tanpa kontak.

  • Jika konfigurasi Anda sengaja mengizinkan pembuatan tiket tanpa kontak, pastikan endpoint tiket Anda menangani kasus tersebut secara eksplisit dan dapat diprediksi.

Dampak kegagalan pencatatan pada tindakan setelah sesi

Untuk penyiapan API generik yang mengonfigurasi pencarian tiket, platform tidak akan mengirim panggilan pasca-sesi - seperti call_finished, chat_finished, email_finished, save_call_recording, save_chat_history, update_ticket, dan done_ticket, hingga ticket_id ada.

Jika endpoint pasca-sesi dipanggil tanpa ticket_id, hal ini biasanya menunjukkan salah satu kondisi berikut:

  • Pencarian tiket dinonaktifkan untuk konfigurasi instance, yang tidak umum untuk penyiapan API generik standar.

  • Template payload menghilangkan variabel ticket_id, yang merupakan masalah konfigurasi yang perlu diselidiki.

Pengaruhnya bagi endpoint Anda

  • Perlakukan ticket_id yang tidak ada pada panggilan pasca-sesi sebagai sinyal konfigurasi yang perlu diselidiki, bukan sebagai perilaku yang diharapkan untuk diserap secara diam-diam.

  • Jika konfigurasi Anda sengaja tidak memerlukan pencarian tiket, konfigurasikan endpoint pasca-sesi untuk menangani ticket_id yang tidak ada dengan baik. Misalnya, catat masalah dan no-op, atau tampilkan pesan error yang jelas dan terstruktur dengan baik, bukan error.

Perilaku percobaan ulang dan backoff

Percobaan ulang terjadi dalam tiga lapisan:

  1. Percobaan ulang langsung di tingkat HTTP (upaya kedua yang cepat).

  2. Percobaan ulang tingkat adaptor (pemulihan cepat untuk kegagalan jaringan dan respons sementara tertentu).

  3. Percobaan ulang tingkat perintah (percobaan ulang longtail selama beberapa hari).

Percobaan ulang langsung di tingkat HTTP (percobaan ulang cepat)

Untuk status sementara tertentu, platform melakukan total hingga 2 upaya (1 upaya awal + 1 percobaan ulang langsung). Hal ini biasanya berlaku untuk status error berikut:

  • 408, 413, 429, 500, 502, 503, 504, 521, 522, dan 524.

Percobaan ulang tingkat adaptor (pemulihan jaringan cepat)

Di antara panggilan HTTP dan jadwal tingkat perintah, lapisan percobaan ulang perantara di adaptor CRM (command_runner.js) menangani kegagalan yang tidak menghasilkan respons HTTP sama sekali, atau yang cocok dengan pesan sementara tertentu:

  • Antrean ulang langsung: Dipicu oleh error tingkat TCP/socket - ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN. Ini adalah kegagalan jaringan yang terjadi sebelum respons HTTP diterima.

  • Percobaan ulang dengan penundaan 30 detik: Dipicu saat pesan error adalah "Too Early" (HTTP 425), "Service Unavailable", atau "Unordered Collection".

  • Tidak dapat dicoba lagi pada lapisan ini: Semua hal lainnya akan beralih ke jadwal percobaan ulang tingkat perintah (Lapisan 3).

Alasan pentingnya hal ini bagi integrator

Error ini terjadi saat platform tidak dapat membuat atau mempertahankan koneksi TCP ke endpoint Anda. Artinya, error ini sering kali menunjukkan masalah di server Anda (server nonaktif, menolak koneksi, atau memutuskan koneksi di tengah permintaan), bukan hanya infrastruktur internal. Efek praktisnya adalah beberapa kegagalan jaringan pulih jauh lebih cepat daripada jadwal tingkat perintah 7 hari — sering kali dalam hitungan detik.

Percobaan ulang tingkat perintah (~7 hari, 14 percobaan)

Jika operasi gagal dan dapat dicoba lagi, platform dapat mencoba lagi hingga 14 kali selama sekitar 7 hari, menggunakan jadwal ini:

  10s → 1m → 5m → 30m → 1h → 6h → 6h → 12h → 1d → 1d → 1d → 1d → 1d → 1d

Perilaku percobaan ulang longtail ini dapat berlaku untuk:

  • Operasi akun.

  • Merekam operasi.

  • Operasi pasca-sesi.

Kegagalan yang tidak dapat dicoba lagi

Beberapa kegagalan diperlakukan sebagai tidak dapat dicoba ulang, misalnya:

  • Kegagalan konfigurasi atau validasi (misalnya, endpoint yang diperlukan tidak dikonfigurasi atau salah dikonfigurasi).

  • Kategori error internal tertentu yang terdeteksi oleh platform.

Jika Anda perlu memastikan kegagalan diperlakukan sebagai permanen (tidak ada percobaan ulang), hubungi dukungan atau tim implementasi Anda untuk mengonfirmasi cara yang benar untuk menunjukkan kegagalan yang tidak dapat dicoba ulang dalam penyiapan spesifik Anda.

Waktu tunggu habis dan kegagalan jaringan

Platform ini menangani dua jalur yang berbeda:

  1. Waktu tunggu tingkat aplikasi: Jika waktu tunggu HTTP yang dikonfigurasi terlampaui (permintaan dikirim, tetapi tidak ada respons yang diterima), platform akan memunculkan error internal yang dapat dicoba lagi di tingkat perintah (Lapisan 3). Artinya, permintaan mengikuti jadwal backoff standar (hingga 14 percobaan ulang selama ~7 hari).

  2. Error tingkat TCP/socket: Jika koneksi gagal di tingkat jaringan sebelum respons HTTP diterima (misalnya, ETIMEDOUT, ESOCKETTIMEDOUT, dan ECONNREFUSED), lapisan adaptor (Lapisan 2) akan menangkapnya dan segera mengantrekan ulang perintah. Pemulihan dari kegagalan ini biasanya jauh lebih cepat - sering kali dalam hitungan detik, bukan mengikuti jadwal 7 hari.

Pentingnya perbedaan ini

  • Waktu tunggu aplikasi (server Anda menerima koneksi, tetapi tidak merespons tepat waktu) akan mencoba lagi dengan lebih lambat.

  • Kegagalan tingkat jaringan (server Anda tidak dapat dijangkau sama sekali) akan dicoba ulang dengan jauh lebih cepat.

  • Dalam kedua kasus tersebut, permintaan mungkin telah diproses sebagian, sehingga endpoint harus idempoten — lihat Membangun endpoint yang tangguh (idempotensi dan tips desain).

Matriks perilaku kode status dan waktu tunggu (dengan contoh)

Tabel dan contoh berikut menjelaskan cara CCAI Platform menangani berbagai kode status HTTP, waktu tunggu, dan kegagalan jaringan.

Tabel ringkasan hasil

Baris terkait ID dalam tabel berikut hanya berlaku untuk endpoint yang dikonfigurasi untuk mengekstrak ID dari respons, seperti endpoint pencarian atau pembuatan. Sebagian besar endpoint lainnya tidak melakukan ekstraksi ID respons.

Hasil Contoh Percobaan ulang HTTP langsung? Percobaan ulang longtail (~7 hari)? Dampak downstream
Keberhasilan untuk endpoint ekstraksi ID 2xx + ID yang diharapkan ada di lokasi respons yang dikonfigurasi. Tidak Tidak Downstream melanjutkan dengan ID yang diekstrak.
Pencarian tanpa kecocokan 2xx, tetapi tidak ada data yang ditemukan di lokasi yang dikonfigurasi. Tidak Tidak Perilaku "tidak ditemukan" yang normal. Jika skip_account_creation atau skip_record_creation diaktifkan, downstream akan sengaja dilanjutkan dengan ID null.
Membuat 2xx yang kembali tanpa ID 2xx dari endpoint pembuatan, tetapi ID data baru tidak ada di lokasi yang dikonfigurasi. Tidak Tidak Downstream dapat dilanjutkan dengan data yang tidak lengkap. Perlakukan sebagai masalah konfigurasi atau kontrak respons.
Berhasil dari endpoint yang tidak mengekstrak ID 2xx dari endpoint seperti tindakan catatan, update, atau lampiran yang tidak mengekstrak ID. Tidak Tidak Downstream dilanjutkan sesuai dengan rantai perintah dan konfigurasi instance.
Error sementara 408, 413, 429, 500, 502, 503, 504, 521, 522, dan 524. Ya (total dua kali percobaan) Sering kali ya Langkah downstream mungkin tertunda saat percobaan ulang terjadi.
Error lainnya 400, 401, 403, 404, dan 4xx/5xx lainnya. Tidak Sering kali ya Langkah downstream mungkin tertunda saat percobaan ulang terjadi.
Kegagalan konfigurasi/validasi kesalahan konfigurasi, endpoint yang tidak ada. T/A Tidak Rantai dapat berhenti atau selesai sebagian, bergantung pada konfigurasi.
Kegagalan tingkat jaringan (TCP/socket) ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, dan EAI_AGAIN. T/A Tidak (ditangani oleh adaptor Lapisan 2) Adaptor segera mengantre ulang; pemulihan biasanya cepat (dalam hitungan detik). Langkah downstream mungkin tertunda sebentar.
Waktu tunggu tingkat aplikasi HTTP timeout exceeded (tidak ada respons yang diterima). T/A Sering kali ya (Lapisan 3) Langkah downstream mungkin tertunda saat percobaan ulang tingkat perintah terjadi.

Contoh penggunaan dengan konfigurasi API generik minimal

Penyiapan API generik CRM kustom dasar pengukuran dengan tiga endpoint yang dijalankan oleh rantai: menemukan atau membuat kontak, menemukan atau membuat tiket, dan komentar pasca-sesi. Gunakan ini sebagai titik awal dan sesuaikan dengan spesifikasi CRM Anda.

Setelan tingkat instance

{
  "lookup_method": "genericApi",
  "auth_method": "basic",
  "basic_auth_username": "ccai-integration",
  "basic_auth_password": "<secret>",
  "api_request_timeout": 10,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}",
  "contact_lookup_url": "https://crm.example.com/api/contacts/{ACCOUNT_ID}",
  "skip_account_lookup": false,
  "skip_account_creation": false,
  "skip_record_creation": false
}

Bentuk respons

Bentuk respons CRM Anda bersifat spesifik per pelanggan. response_data_location adalah jalur bergaya lodash yang menjangkau objek yang relevan di dalam isi respons yang diuraikan. Tidak ada persyaratan untuk menggabungkan respons dalam kolom data tingkat atas - contoh berikut menunjukkan bentuk datar yang realistis secara default.

Misalnya, CRM yang menyusun bertingkat resource di bawah data.contact akan menetapkan response_data_location: "data.contact" dan isi respons { "contact": { "id": "c_99812" } }; konfigurasi lainnya tidak berubah.

Endpoint 1 - contact_find_endpoint

Mencari kontak berdasarkan nomor telepon atau email.

{
  "request_url": "https://crm.example.com/api/contacts/search?phone={PHONE_NUMBER}&email={EMAIL}",
  "request_method": "GET",
  "request_parameters": {},
  "response_data_location": "data"
}

Berhasil: Kontak ditemukan

200 OK
Content-Type: application/json
{ "id": "c_42018", "first_name": "Jane", "last_name": "Doe" }

Kontak tidak ditemukan

404 Not Found

Platform memperlakukan 404 sebagai "tidak ditemukan" (bukan error). Jika skip_account_creation salah, alur akan berlanjut ke contact_create_endpoint.

Pola alternatif tidak ditemukan: juga valid

200 OK
{}

Beberapa CRM menampilkan 200 OK dengan data kosong, bukan 404, jika tidak ada data yang cocok. Platform menangani keduanya secara setara - keduanya memicu langkah berikutnya (pembuatan, jika diaktifkan).

Kegagalan sementara

503 Service Unavailable
}

Memicu percobaan ulang HTTP langsung Lapisan 1 (total 2 upaya). Jika masih gagal, akan beralih ke percobaan ulang tingkat perintah Lapisan 3.

Endpoint 2 - contact_create_endpoint

Membuat kontak. Kolom custom_id_location memberi tahu platform tempat menemukan ID kontak baru di dalam respons.

{
  "request_url": "https://crm.example.com/api/contacts",
  "request_method": "POST",
  "request_parameters": {
    "first_name": "{FIRST_NAME}",
    "last_name": "{LAST_NAME}",
    "email": "{EMAIL}",
    "phone": "{PHONE_NUMBER}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

Pembuatan berhasil

201 Created
{ "id": "c_99812", "first_name": "John", "last_name": "Doe" }

2xx, tetapi ID tidak ada di lokasi yang dikonfigurasi

200 OK
{}

Endpoint menampilkan 200 OK tanpa id di lokasi yang dikonfigurasi. Platform akan mencatat peringatan dan meneruskan contact_id null ke downstream (tidak ada pengecualian yang ditampilkan, tidak ada percobaan ulang). Anggap ini sebagai indikasi konfigurasi yang buruk — response_data_location dan custom_id_location harus menghasilkan ID yang andal untuk setiap 2xx yang ditampilkan endpoint Anda dari jalur ini.

Endpoint 3 - case_create_endpoint

Membuat tiket. contact_id dari langkah sebelumnya tersedia sebagai {ACCOUNT_ID}.

{
  "request_url": "https://crm.example.com/api/cases",
  "request_method": "POST",
  "request_parameters": {
    "subject": "{TICKET_SUBJECT}",
    "description": "{TICKET_DESCRIPTION}",
    "contact_id": "{ACCOUNT_ID}",
    "channel": "{CHANNEL}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

Pembuatan berhasil

201 Created
{ "id": "case_77103", "status": "new" }

Dengan response_data_location: "data", platform akan me-resolve jalur ke isi respons yang diurai. Kemudian, ekstensi akan membaca kolom di custom_id_location: "id" → ticket_id = "case_77103", yang mengalir ke pasca-sesi.

Endpoint 4 - case_comment_endpoint

Endpoint ini menambahkan komentar ringkasan sesi ke tiket setelah panggilan atau chat berakhir. Variabel RECORD_ID membawa ticket_id yang dihasilkan oleh langkah 3.

{
  "request_url": "https://crm.example.com/api/cases/{RECORD_ID}/comments",
  "request_method": "POST",
  "request_parameters": {
    "body": "{COMMENT_BODY}",
    "agent_email": "{AGENT_EMAIL}",
    "channel": "{CHANNEL}",
    "duration": "{CALL_DURATION}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  }
}

Untuk instance API generik dengan case_lookup_url yang dikonfigurasi, platform tidak akan mengirim endpoint ini hingga langkah pembuatan tiket berhasil diselesaikan - jadi tidak adanya RECORD_ID di sini berarti masalah konfigurasi, bukan status sementara.

Variasi: pembuatan akun dinonaktifkan

Contoh ini sangat mirip dengan contoh sebelumnya yang diberikan untuk konfigurasi API generik minimal, kecuali di sini instance Anda tidak mengizinkan pembuatan kontak di CRM. Meskipun pencarian akun berjalan, pembuatan akun tidak berjalan.

Perubahan setelan instance

{
  "skip_account_creation": true,
  "skip_account_lookup": false
}

Perubahan setelan instance mencakup perilaku berikut:

  • Langkah akun hanya memanggil contact_find_endpoint. Jika tidak ada kontak yang ditemukan, contact_create_endpoint tidak akan dipanggil.

  • Langkah perekaman menerima contact_id null. Platform melanjutkan ke pembuatan tiket tanpa contact_id - {ACCOUNT_ID} di-resolve menjadi kosong, dan kolom contact_id dihapus sepenuhnya dari payload case_create_endpoint Anda.

  • Artinya, endpoint pembuatan tiket Anda harus dapat membuat tiket tanpa contact_id dalam konfigurasi ini. Jika CRM Anda memerlukan kontak terkait untuk setiap tiket, konfigurasi ini tidak kompatibel.

Pola defensif di case_create_endpoint

Tanpa contact_id, CRM Anda memiliki lebih sedikit konteks tentang penelepon daripada biasanya. Anda dapat menggunakan helper =DEFAULT_VALUE untuk mengambil informasi identitas pribadi apa pun yang tersedia di permintaan dan meneruskannya sebagai sinyal penggantian:

"request_parameters": {
  "subject": "{TICKET_SUBJECT}",
  "contact_id": "{ACCOUNT_ID}",
  "contact_origin": "=DEFAULT_VALUE(\"{EMAIL}\", \"{PHONE_NUMBER}\", \"anonymous\")"
}

Helper =DEFAULT_VALUE memilih nilai pertama yang tidak kosong, sehingga CRM Anda menerima email atau nomor telepon jika tersedia, dan string literal "anonymous" hanya jika keduanya tidak ada - berguna untuk menandai tiket yang tidak memiliki info kontak identifikasi yang dilampirkan.

Variasi: alur tiket khusus pencarian (tanpa pembuatan data)

Operasi akun berjalan normal, tetapi pembuatan tiket dinonaktifkan. Integrasi ini hanya melampirkan komentar ke tiket yang sudah ada yang ditampilkan oleh pencarian.

Perubahan setelan instance

{
  "skip_record_creation": true,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}"
}

Perubahan ini mencakup perilaku berikut:

  • Langkah pencatatan memanggil case_find_endpoint dan menggunakan tiket yang ditampilkan. Jika tidak ada tiket yang ditemukan, rantai akan berhenti di langkah pencatatan - case_create_endpoint tidak dipanggil.

  • Endpoint pasca-sesi (case_comment_endpoint, case_update_endpoint, dan sejenisnya) hanya dikirim saat tiket berhasil dicari. Pelindung ready? di sisi Rails memastikan perintah ini tetap berada dalam antrean (dan pada akhirnya akan habis masa berlakunya) jika tidak ada ticket_id yang terwujud.

  • Implikasi praktis: dalam konfigurasi ini, endpoint pasca-sesi Anda hanya akan menerima sesi yang terkait dengan tiket yang diketahui. Anda tidak perlu menangani cabang "missing ticket_id".

Platform ini mengekspos SESSION_TYPE dan SESSION_ID sebagai variabel template. Cara paling rapi untuk menerapkan pola kunci komposit adalah dengan memasukkannya langsung ke setiap isi permintaan yang relevan - endpoint Anda kemudian memiliki kunci kanonis untuk digunakan, tanpa logika tambahan di pihak Anda:

"request_parameters": {
  "...your fields...": "...",
  "ccai_session_key": "{SESSION_TYPE}-{SESSION_ID}"
}

Untuk panggilan yang sama, setiap percobaan ulang dari setiap endpoint dalam rantai (akun > data > pasca-sesi) akan menghasilkan ccai_session_key yang sama. Gunakan ID ini sebagai anchor penghapusan duplikat dalam logika pembuatan atau upsert CRM Anda — misalnya, upsert pada (ccai_session_key, endpoint_kind) akan menyerap percobaan ulang dengan aman tanpa menghasilkan data duplikat.

Membangun endpoint yang tangguh (idempotensi dan tips desain)

Karena permintaan dapat diulang (percobaan ulang langsung + percobaan ulang selama beberapa hari), endpoint Anda harus idempoten:

  • Gunakan ID interaksi gabungan yang stabil sebagai kunci idempotensi Anda:

    • Gabungkan jenis sesi dengan ID sesi, misalnya, call-12345 atau chat-12345.

    • Jangan hanya mengandalkan call_id atau chat_id. ID suara dan chat dapat tumpang-tindih karena setiap urutan dapat dimulai dari 1.

  • Jika Anda menerima permintaan yang tampaknya merupakan duplikat:

    • Periksa payload untuk menentukan apakah payload tersebut benar-benar duplikat. Beberapa endpoint bersama, seperti endpoint komentar atau catatan, dapat digunakan oleh beberapa jenis perintah.

    • Untuk operasi pembuatan, permintaan duplikat tidak boleh terjadi dalam kondisi normal yang berhasil, tetapi dapat terjadi jika CRM memproses permintaan, lalu menampilkan error atau waktu habis sebelum platform menerima respons yang berhasil.

    • Saat permintaan pembuatan duplikat dikonfirmasi, tampilkan ID data yang dibuat sebelumnya, bukan data lain.

  • Tangani ID yang tidak ada secara eksplisit:

    • contact_id yang tidak ada pada pembuatan tiket biasanya menunjukkan konfigurasi yang menonaktifkan pencarian akun atau pembuatan akun. Jika instance Anda memerlukan akun, selidiki hal tersebut, bukan membuat tiket secara diam-diam tanpa kontak.

    • ticket_id yang tidak ada pada panggilan pasca-sesi tidak diharapkan untuk penyiapan API generik standar yang mengonfigurasi pencarian tiket. Periksa konfigurasi pencarian tiket dan template payload sebelum memperlakukan permintaan sebagai no-op normal.

  • Untuk update, sebaiknya tetapkan kolom ke nilai tertentu, bukan meningkatkan penghitung, sehingga panggilan berulang aman.

Pemecahan masalah dan kemampuan observasi

Saat Anda men-debug integrasi CRM kustom, perhatikan pola berikut:

  • Panggilan berulang ke endpoint yang sama:

    • Bandingkan stempel waktu dengan jadwal percobaan ulang di Percobaan ulang tingkat perintah (~7 hari, 14 percobaan).

    • Korelasikan peristiwa menggunakan ID sesi gabungan, seperti jenis sesi + ID sesi panggilan atau chat.

    • Log yang diekspor CCAI Platform dapat membantu menampilkan ID sesi panggilan atau chat bersama peristiwa API untuk keterlacakan.

    • Periksa apakah endpoint Anda secara konsisten menampilkan error yang dapat dicoba lagi (misalnya, 500), bukan kegagalan konfigurasi yang tidak dapat dicoba lagi.

  • Percobaan ulang yang "tidak akan berhenti":

    • Periksa respons error yang ditampilkan endpoint Anda.

    • Jika Anda menginginkan kegagalan permanen, hubungi dukungan untuk mendapatkan panduan tentang cara menunjukkan error yang tidak dapat dicoba lagi untuk konfigurasi Anda.

  • Endpoint tidak pernah dipanggil:

    • Verifikasi bahwa:

      • Langkah upstream (akun/data) berhasil diselesaikan dan menghasilkan ID yang diperlukan.

      • Endpoint dikonfigurasi dan diaktifkan dengan benar di setelan CRM kustom Anda.

    • Endpoint yang salah dikonfigurasi atau dinonaktifkan, atau kegagalan sebelumnya dalam rantai, dapat mencegah langkah-langkah tertentu berjalan.

  • Menghubungkan log:

    • Catat permintaan dan respons lengkap di pihak Anda, termasuk ID interaksi (call_id / chat_id).

    • Gunakan ID tersebut untuk menghubungkan log CRM Anda dengan perilaku platform dari waktu ke waktu (terutama selama percobaan ulang).