Lewati ke konten utama

Batasan Integrasi dan Kondisi 501

Ringkasan jujur tentang apa yang tidak boleh dianggap tersedia dalam integrasi Custelio. 501 Not Implemented dipakai API sebagai kondisi jujur ketika integrasi belum dikonfigurasi atau memang tidak didukung — bukan error yang boleh disamarkan atau disembunyikan lewat fallback diam-diam. Dokumen ini tidak menduplikasi skema endpoint; OpenAPI runtime adalah sumber kontrak.

Tujuan​

Integrator membedakan endpoint yang aktif, endpoint yang menunggu konfigurasi, dan channel yang tidak didukung — sebelum membangun ketergantungan di atasnya.

Untuk siapa​

Developer/integrator yang menghubungkan Custelio ke sistem lain.

Kondisi yang wajib dipahami​

SSE hanya bila hub terdaftar​

Stream /api/v1/events/stream hanya aktif pada deployment yang menyediakan SSE hub. Jalur tidak boleh dianggap ada hanya karena tercantum di OpenAPI; verifikasi di deployment.

Business context mengembalikan 501 bila tidak dikonfigurasi​

Endpoint business context (/conversations/:id/business-context dan /business-records/:entityType/:recordId) mengembalikan 501 selama klien eksternal belum dikonfigurasi (BUSINESS_CONTEXT_BASE_URL dan kredensial terkait). Tanpa konfigurasi, respons selalu 501; jangan membangun alur yang menganggap data context tersedia.

Outbound webhook mengembalikan 501 tanpa store​

Route subscription/delivery webhook outbound menjawab 501 ketika store outbound webhook tidak dikonfigurasi; event domain juga tidak dipublikasikan. Deployment dev-mode (New()) tanpa store selalu 501. Status configuration-required sampai delivery dibuktikan.

Telegram dan LINE: 501 kondisional​

Webhook Telegram dan LINE hanya aktif bila client masing-masing dikonfigurasi. Tanpa kredensial, webhook menjawab 501 not configured. Ketersediaan per deployment.

TikTok tidak didukung​

TikTok selalu menjawab 501 dengan keterangan tidak didukung: tidak ada general-purpose messaging API. Jangan mengintegrasikan TikTok sebagai channel yang dapat dibalas.

OpenAPI drift terbatas​

OpenAPI adalah referensi terbatas, bukan bukti semua endpoint tersedia. Drift yang diketahui: operasi tercantum yang belum terhubung ke jalur runtime, status implemented/planned yang tidak sinkron dengan kode, skema yang belum terbukti lewat integrasi provider, dan API parity Chatwoot (Dashboard, Application, Platform, Client) yang belum lengkap. Tidak ada klaim parity penuh.

Verifikasi sebelum integrasi​

  1. Uji endpoint yang akan dipakai pada deployment target dengan kredensial nyata; catat status dan request ID.
  2. Periksa status fitur pada UI/runtime, bukan hanya pada PRD atau OpenAPI.
  3. Konfigurasi environment yang diperlukan (provider, store, context) harus ada sebelum mengklaim jalur tersedia.
  4. Perlakukan 501 sebagai keputusan desain: pilih jalur yang tersedia atau hentikan, jangan fallback yang menyembunyikan kegagalan.
  5. Jangan mencatat secret, token, atau PII pada log dan contoh.

Tanda berhasil​

Integrasi hanya bergantung pada jalur yang terverifikasi aktif; 501 dijelaskan sebagai kondisi (belum dikonfigurasi vs tidak didukung); tidak ada klaim delivery/context/realtime tanpa bukti runtime.

Jika terjadi masalah​

  • 501 integration not configured / 501 outbound webhooks not configured: lengkapi environment, restart service, lalu uji ulang.
  • 501 telegram/line not configured: sediakan kredensial channel.
  • 501 tiktok not supported: TikTok memang tidak didukung; gunakan channel lain.
  • 400/401/403/404/409/429: ikuti panduan error pada Referensi API.

Batasan​

Kondisi di atas dapat berubah seiring implementasi; dokumen ini sengaja tidak mengklaim status endpoint tertentu pada deployment Anda. Selalu verifikasi runtime. Delivery WhatsApp dan sebagian kemampuan provider tetap bergantung deployment dan status delivery aktual.

Tugas terkait​