Lewati ke konten utama

Business Context dan Task Links

Dua jalur yang menghubungkan percakapan Custelio dengan sistem bisnis eksternal: business context menampilkan data order/invoice/pelanggan di samping percakapan, dan task links mengaitkan percakapan dengan task sistem luar (misalnya task workflow otomatisasi). Halaman ini menjelaskan alur kerja dan batas yang berlaku; kontrak payload ada di OpenAPI runtime, bukan di sini.

Tujuan​

Agent melihat konteks bisnis yang relevan saat menangani percakapan, dan task eksternal dapat dikaitkan/dilepas dari percakapan dengan akurasi tenant yang terjaga — tanpa membiarkan gangguan sistem bisnis memblokir percakapan.

Untuk siapa​

Business operator yang menjalankan alur berbasis task, serta developer/integrator yang menyambungkan Custelio ke sistem bisnis.

Prasyarat​

  • Untuk business context: service eksternal tersedia dan dikonfigurasi lewat environment (BUSINESS_CONTEXT_BASE_URL, BUSINESS_CONTEXT_API_KEY, BUSINESS_CONTEXT_AUTH_TYPE, bawaan api_key). Tanpa konfigurasi, endpoint mengembalikan 501.
  • Untuk task links: API diakses dengan token tenant yang memiliki akses ke percakapan dan task terkait.
  • Pahami konsep tenant dan status fitur; lihat Glosarium.

Business context​

Business context mengambil record bisnis (customer, order, invoice, payment, inventory, shipment, booking, service) dari provider eksternal dan menormalkannya menjadi bentuk ringkas: referensi, status, ringkasan, jumlah, tanggal, dan item.

  1. Pastikan environment business context terisi; tanpa itu semua endpoint menjawab 501 integration not configured — selalu, bukan sesekali.
  2. Ambil konteks percakapan: sediakan conversation_id dan contact_id yang wajib; jenis record diambil dari daftar default dan dapat dipersempit.
  3. Ambil satu record bisnis: gunakan jenis entitas yang didukung dan sertakan conversation_id untuk membatasi ke tenant; jenis entitas tak dikenal ditolak.
  4. Perhatikan degradasi: gangguan provider tidak pernah memblokir percakapan — record yang gagal diambil dilewati, bukan menghentikan respons.

Keamanan: klien memvalidasi URL agar tidak mengarah ke IP privat (anti-SSRF), memakai timeout 10 detik, dan circuit breaker per provider. Provider yang menjawab non-2xx atau error jaringan menghasilkan kegagalan yang dicatat; jangan menganggap data konteks selalu hadir.

Task link memasangkan task eksternal dengan percakapan di dalam satu tenant.

  1. Buat link: kirim task_id dan conversation_id; keduanya wajib. Respons 201 berisi link yang tercatat beserta pembuatnya.
  2. Lihat link per percakapan: daftar task yang terkait percakapan; percakapan tanpa link mengembalikan daftar kosong, bukan error.
  3. Lihat percakapan per task: daftar percakapan yang terkait task eksternal.
  4. Lepas link: hapus pasangan task/percakapan; link yang tidak ada menghasilkan 404.

Semua operasi dibatasi ke akun pemanggil; jangan memakai task link untuk menembus akses lintas tenant.

Tanda berhasil​

Konteks bisnis muncul saat provider terkonfigurasi dan sehat; link task dapat dibuat, didaftar per percakapan maupun per task, dan dilepas; semua respons konsisten dengan tenant pemanggil.

Jika terjadi masalah​

  • 501 business context: konfigurasi environment belum ada; tambahkan BUSINESS_CONTEXT_BASE_URL dan kredensial, lalu mulai ulang service. Jangan membangun alur yang menganggap data konteks pasti tersedia.
  • 400: parameter wajib hilang (contact_id, conversation_id) atau jenis entitas tidak didukung.
  • 404: percakapan bukan milik tenant atau link task tidak ada.
  • 502: provider business context error; periksa service eksternal dan circuit breaker; percakapan tetap berjalan.
  • Task link gagal 500: periksa log dan identitas tenant; jangan mencoba lintas tenant.

Batasan​

Business context configuration-required: tanpa provider, endpoint selalu 501; data direkam apa adanya dari provider eksternal dan bisa kosong saat gangguan. Task links hanya memetakan task ↔ percakapan — task itu sendiri dikelola sistem eksternal, bukan Custelio. Kontrak payload mengikuti OpenAPI runtime dan dapat berubah; halaman ini tidak menduplikasi skema endpoint.

Tugas terkait​