Metode API SDK web tanpa UI

Halaman ini mencantumkan metode API yang tersedia untuk SDK web headless.

Perusahaan dan menu

Metode untuk menangani nilai dan menu perusahaan.

Metode

SDK headless menyediakan berbagai metode yang dapat dipanggil pada instance klien.

Berikut beberapa contohnya:

Perusahaan dan menu

Nama metode	Deskripsi
getCompany	Mengambil informasi perusahaan yang dikonfigurasi.
getMenus	Mencantumkan semua menu yang tersedia untuk tenant tertentu.
getWaitTimes	Mendapatkan waktu tunggu saat ini untuk berbagai saluran di menu.

getCompany

Mengambil informasi perusahaan yang dikonfigurasi untuk instance yang diautentikasi, termasuk nama perusahaan, bahasa yang didukung, dan setelan fitur. Metode ini juga menetapkan ID instance internal (OPTIONS.tenant) sebagai efek samping, sehingga biasanya merupakan panggilan pertama yang dilakukan setelah membuat Klien.

Tanda tangan metode

getCompany(): Promise<CompanyResponse>

Nilai yang ditampilkan

Mengembalikan objek CompanyResponse.

Antarmuka

interface CompanyResponse {
  name: string;
  subdomain: string;
  support_email: string;
  languages: LanguageOption[];
  action_tracking: boolean;
  email_transcripts: boolean;
  message_preview: boolean;
  email_enhancement: boolean;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

Contoh penggunaan

try {
  const company = await client.getCompany()
} catch (error) {
  // handle error
}

getMenus

Metode ini digunakan untuk mencantumkan semua item menu yang tersedia untuk instance. Kolom MenuResponse.direct memberi tahu pemanggil apakah hasilnya berasal dari kunci akses langsung (direct.key: true) atau dari akses langsung tingkat pengguna (direct.user: true) - keduanya memengaruhi cara menu harus ditampilkan.

Tanda tangan metode

getMenus(key?: string, lang?: string): Promise<MenuResponse>

Nilai yang ditampilkan

Mengembalikan objek MenuResponse.

Antarmuka

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
    key_id: number | null;
  };
}
interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
  hidden: boolean;
}

Contoh penggunaan

try {
  const data: MenuResponse = await client.getMenus("direct_menu_key")
  console.log(data.menus)
  console.log(data.direct)
} catch (error) {
  // handle error
}

getWaitTimes

Mengambil perkiraan waktu tunggu (dalam detik) untuk saluran chat dan panggilan suara dari menu tertentu.

Tanda tangan metode

getWaitTimes(menuId: number | string, lang?: string): Promise<WaitTimeResponse | null>

Nilai yang ditampilkan

Menampilkan objek WaitTimeResponse atau null.

Antarmuka

interface WaitTimeResponse {
  chat: number;
  voice_call: number;
}

Contoh penggunaan

try {
  const data = await client.getWaitTimes(123)
} catch (error) {
  // handle error
}

Panggilan

Nama	Deskripsi
createCall	Buat panggilan instan atau terjadwal.
loadCall	Mendapatkan informasi dari ID panggilan tertentu.
cancelCall	Membatalkan panggilan dengan ID panggilan yang diberikan.
getTimeSlots	Mendapatkan slot waktu yang tersedia untuk panggilan terjadwal untuk menu tertentu.
fetchTimeSlotAvailability	Memeriksa apakah slot waktu tersedia untuk menu tertentu.

createCall

Membuat panggilan baru untuk menu yang diberikan. Panggilan ini dapat berupa panggilan instan atau panggilan terjadwal, bergantung pada apakah kolom scheduled_at disediakan. Jenis panggilan (web_instant_call versus web_scheduled_call) ditentukan secara otomatis berdasarkan keberadaan scheduled_at. reschedule_call_id dikirim di tingkat teratas permintaan, terpisah dari isi panggilan. menu_id dalam respons dinormalisasi dari selected_menu.id API.

Tanda tangan metode

createCall(menuId: number | string, data: CallRequest): Promise<CallResponse>

Nilai yang ditampilkan

Mengembalikan objek CallResponse.

Antarmuka

interface CallRequest {
  phone_number: string;
  lang?: string;
  scheduled_at?: string;
  ticket_id?: string;
  email?: string;
  recording_permission?: "recording_permission_not_asked" | "recording_permission_granted" | "recording_permission_denied";
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
  reschedule_call_id?: number;
}

Contoh penggunaan

try {
 const call = await client.createCall(123, { phone_number: '[phone]' })
} catch (error) {
 // handle error
}

loadCall

Metode loadCall mengambil informasi tentang panggilan tertentu, yang diidentifikasi berdasarkan ID-nya.

Tanda tangan metode

loadCall(callId: number | string): Promise<CallResponse>

Nilai yang ditampilkan

Mengembalikan objek CallResponse.

Antarmuka

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

Contoh penggunaan

try {
 const call = await client.loadCall(1234)
} catch (error) {
 // handle error
}

cancelCall

Membatalkan panggilan yang ada berdasarkan ID-nya. Biasanya digunakan untuk membatalkan panggilan terjadwal yang belum dilakukan.

Tanda tangan metode

cancelCall(callId: number | string): Promise<CallResponse>

Nilai yang ditampilkan

Menampilkan objek CallResponse.

Antarmuka

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

Contoh penggunaan

try {
 const response = await client.cancelCall(1234)
} catch (error) {
 // handle error
}

getTimeSlots

Mengambil slot waktu yang tersedia untuk panggilan terjadwal di menu tertentu. Saat dipanggil dengan objek opsi GetTimeSlotsRequest, mendukung penjadwalan ulang panggilan yang ada menggunakan rescheduleCallId. Tanda tangan string lang yang tidak digunakan lagi tetap didukung dan dirutekan ke endpoint yang sama dengan hanya lang yang diisi. Menampilkan array string slot waktu.

Tanda tangan metode

getTimeSlots(menuId: number | string, options?: GetTimeSlotsRequest): Promise<string[]>

Peringatan: Tanda tangan sebelumnya, getTimeSlots(menuId, lang?), tidak digunakan lagi. Bermigrasi ke tanda tangan berbasis opsi baru yang ditampilkan sebelumnya. Tanda tangan lama akan terus berfungsi, tetapi mungkin akan dihapus dalam rilis mendatang.

Nilai yang ditampilkan

Menampilkan array string (slot waktu).

Antarmuka

interface GetTimeSlotsRequest {
 lang?: string;
 rescheduleCallId?: number;          // ID of an existing call being rescheduled
}

Contoh penggunaan

// New options-based signature (recommended)
try {
 const slots = await client.getTimeSlots(123, {
   lang: 'en',
   rescheduleCallId: 98765, // optional: pass when rescheduling an existing call
 })
} catch (error) {
 // handle error
}
// Deprecated signature (still supported)
try {
 const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
 // handle error
}

fetchTimeSlotAvailability

Metode ini memeriksa apakah slot waktu tersedia untuk menu tertentu, tanpa mengambil daftar lengkap slot waktu. Hal ini berguna untuk menampilkan opsi penjadwalan secara bersyarat di UI.

Cakupan

fetchTimeSlotAvailability hanya berlaku untuk janji temu panggilan suara terjadwal (telepon balik). Metode ini tidak menampilkan informasi tentang saluran chat, email, atau panggilan instan. Menu yang disediakan harus dikonfigurasi untuk mendukung panggilan suara terjadwal, dengan jam operasional yang ditentukan dan setidaknya satu agen yang diantrekan untuk menu tersebut.

Kasus penggunaan umum:

• Merender pesan ajakan (CTA) "Jadwalkan Telepon Balik" secara bersyarat hanya jika slot tersedia.

• Membuat cabang ke alur pengalihan (misalnya, email, pesan di luar jam kerja) saat tidak ada slot yang tersedia, tanpa membayar biaya panggilan getTimeSlots penuh.

• Melakukan pre-flight tindakan penjadwalan ulang sebelum memanggil getTimeSlots dengan rescheduleCallId.

Tanda tangan metode

fetchTimeSlotAvailability(menuId: number | string, lang?: string): Promise<boolean>

Nilai yang ditampilkan

Menampilkan true jika slot waktu tersedia, false jika tidak.

Contoh penggunaan

try {
 const isAvailable = await client.fetchTimeSlotAvailability(123, 'en')
 if (isAvailable) {
   // Show scheduling UI
 }
} catch (error) {
 // handle error
}

Chat

Nama	Deskripsi
createChat	Membuat chat baru.
loadChat	Mengambil chat dengan ID chat yang diberikan.
loadOngoingChat	Mencoba memuat chat yang sedang berlangsung.
resumeChat	Melanjutkan chat yang ditutup dengan ID chat yang diberikan.
finishChat	Menetapkan status chat saat ini ke selesai.
destroyChat	Memanggil finishChat dan menghancurkan chat saat ini
fetchMessages	Mengambil pesan sebelumnya - menampilkan [] jika gagal.
sendTextMessage	Mengirim pesan teks.
sendFileMessage	Mengirim pesan file - menampilkan -1 jika upload gagal.
sendPreviewMessage	Mengirim pesan pratinjau.
getChatDeflection	Mendapatkan konfigurasi pengalihan chat.
sendChatTranscripts	Mengirim transkrip chat ke email yang diberikan.
downloadChatTranscript	Mendownload transkrip chat.
getPdfStatus	Mendapatkan status PDF untuk transkrip.
getChatSurvey	Mendapatkan pertanyaan survei chat.
sendChatSurvey	Mengirim masukan pengguna dari survei.
sendChatRate	Mengirim masukan pengguna di chat.
escalateChat	Meneruskan chat dari agen virtual ke agen manusia.
trackChatEscalation	Melacak peristiwa eskalasi chat.
trackChatEndUserEvent	Melacak peristiwa pengguna akhir.
getChatHistory	Mengambil histori chat tertentu.

Check-in chat

Check-in meminta konsumen untuk mengonfirmasi bahwa mereka siap sebelum terhubung ke agen. Bagian ini mendokumentasikan metode SDK web headless untuk menerapkan pengalaman tersebut. Untuk mengetahui apa itu check-in, cara mengaktifkan dan mengonfigurasinya (waktu tunggu, waktu tunggu habis, posisi antrean, perilaku bergabung kembali), dan pelaporan, lihat Check-in untuk Chat.

Nama	Deskripsi
checkIn	Mengirim sinyal ke server untuk mengonfirmasi kehadiran pengguna dalam antrean.
exitCheckIn	Menghapus pengguna dari antrean check-in.
notifyCheckInState	Memberi tahu backend tentang status visibilitas modal check-in.
rejoinChat	Menempatkan pengguna kembali dalam antrean setelah gagal mengonfirmasi check-in.
trackCheckInEvent	Memberi sinyal ke backend saat peristiwa check-in telah dipicu oleh UI.

checkIn

Mengirim sinyal konfirmasi ke server yang menunjukkan bahwa konsumen hadir dan siap terhubung dengan agen selama periode check-in. Mengupdate check_in_status chat secara lokal setelah server mengonfirmasi. Gunakan sebagai respons terhadap peristiwa chat.checkInRequested.

Tanda tangan metode

checkIn(): Promise<CheckInResponse>

Nilai yang ditampilkan

Mengembalikan objek CheckInResponse.

Antarmuka

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Contoh penggunaan

try {
 const response = await client.checkIn()
} catch (error) {
 // handle error
}

exitCheckIn

Memberi sinyal ke server bahwa konsumen telah memilih untuk keluar dari antrean check-in. Mengupdate check_in_status secara lokal. Setelah memanggil metode ini, konsumen tidak akan menerima koneksi agen untuk siklus check-in saat ini.

Tanda tangan metode

exitCheckIn(): Promise<CheckInResponse>

Nilai yang ditampilkan

Mengembalikan objek CheckInResponse.

Antarmuka

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Contoh penggunaan

try {
 const response = await client.exitCheckIn()
} catch (error) {
 // handle error
}

notifyCheckInState

Memberi tahu server tentang status visibilitas modal check-in saat ini - apakah widget diminimalkan atau tab browser tidak aktif. Server menggunakan informasi ini untuk membuat keputusan tentang waktu check-in. Harus dipanggil setiap kali visibilitas widget atau fokus tab berubah saat peristiwa chat.checkInRequested aktif.

Tanda tangan metode

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Antarmuka

interface CheckInVisibilityStateRequest {
 widget_minimized?: boolean;
 tab_inactive?: boolean;
}

Contoh penggunaan

try {
 const visibilityState = {
   widget_minimized: true,
   tab_inactive: false,
 }
 await client.notifyCheckInState(visibilityState)
} catch (error) {
 // handle error
}

rejoinChat

Menempatkan konsumen kembali dalam antrean setelah mereka gagal mengonfirmasi check-in dalam waktu yang ditentukan. Mengupdate check_in_status secara lokal. Gunakan sebagai respons terhadap peristiwa chat.checkInTimedOut jika konsumen masih ingin terhubung.

Tanda tangan metode

rejoinChat(): Promise<CheckInResponse>

Nilai yang ditampilkan: Menampilkan objek CheckInResponse.

Antarmuka

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

Contoh penggunaan

try {
 const response = await client.rejoinChat()
} catch (error) {
 // handle error
}

trackCheckInEvent

Memberi tahu server bahwa modal check-in telah ditampilkan kepada konsumen. Panggil ini sekali, segera setelah menampilkan UI check-in sebagai respons terhadap chat.checkInRequested. Server menggunakannya untuk analisis operasional pada tingkat presentasi check-in. Panggilan ditunggu secara internal dan menampilkan Promise<void> yang dapat menolak, jadi gabungkan dalam try/catch (seperti contoh berikut).

Tanda tangan metode

trackCheckInEvent(): Promise<void>

Contoh penggunaan

try {
 await client.trackCheckInEvent()
} catch (error) {
 // handle error
}

getMessageAttachment

Mengambil lampiran yang memenuhi syarat yang terkait dengan pesan chat tertentu. Hanya mengambil jika pesan dikirim oleh non-pengguna akhir ($userType !== 'end_user') dan merupakan jenis lampiran yang didukung (foto, video, audio, dokumen). Menampilkan null untuk pesan apa pun yang tidak memenuhi kedua kondisi, bukan hanya untuk pesan tanpa media_id. Menyimpan file yang diambil ke cache media lokal chat setelah pengambilan.

Tanda tangan metode

getMessageAttachment(message: MessageResponse): Promise<File | null>

Nilai yang ditampilkan

Menampilkan objek File jika ditemukan, atau null jika tidak berlaku.

Contoh penggunaan

try {
 const file = await client.getMessageAttachment(message)
} catch (error) {
 // handle error
}

createChat

Membuat sesi chat baru untuk menu yang diberikan. Anda dapat menentukan bahasa, pesan salam, ID pemicu, ID tiket, dan data kustom untuk dikirim bersama chat.

Setelah panggilan API awal, metode ini akan melakukan polling ke server hingga provider_channel_id tersedia atau chat dibatalkan atau selesai. Jika saluran penyedia tersedia, metode ini akan memulai koneksi ke penyedia real-time. Koneksi mungkin masih diselesaikan saat promise diselesaikan - dengarkan peristiwa chat.connectedMessages untuk mengetahui kapan koneksi dan pengambilan pesan awal telah selesai.

Tanda tangan metode

createChat(menuId: number | string, data: ChatRequest): Promise<Chat>

Nilai yang ditampilkan

Menampilkan instance Chat.

Peringatan: Metode ini akan langsung menampilkan error jika sudah ada percakapan yang sedang berlangsung. Periksa sesi yang ada sebelum melakukan panggilan.

Antarmuka

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

Contoh penggunaan

try {
 const chat = await client.createChat(123, { lang: 'en' })
} catch (error) {
 // handle error
}

loadChat

Mengambil sesi chat yang ada berdasarkan ID-nya.

Jika chat yang dimuat tidak lagi berlangsung, metode ini akan menghapus ID chat yang disimpan dan nonce cobrowse dari penyimpanan lokal. Hal ini juga dilakukan saat terjadi error, sehingga pemanggil tidak perlu menangani pembersihan penyimpanan secara manual setelah pemuatan gagal.

Tanda tangan metode

loadChat(chatId: number | string): Promise<Chat>

Nilai yang ditampilkan

Menampilkan instance Chat.

Peringatan: Jika terjadi error, metode ini akan menghapus ID sesi chat dan cobrowse yang disimpan dari penyimpanan lokal sebelum ditampilkan kembali. Referensi sesi yang disimpan akan dibatalkan setelah panggilan gagal.

Contoh penggunaan

try {
 const chat = await client.loadChat(1234)
} catch (error) {
 // handle error
}

loadOngoingChat

Mencoba memuat sesi chat yang sedang berlangsung, jika ada. Menampilkan null jika tidak ditemukan chat yang sedang berlangsung.

Tanda tangan metode

loadOngoingChat(): Promise<Chat | null>

Nilai yang ditampilkan

Menampilkan instance Chat jika ditemukan, atau null jika tidak ada chat yang sedang berlangsung. Akan menghapus nilai penyimpanan jika chat tidak sedang berlangsung.

Peringatan: Jika terjadi error, metode ini akan menghapus ID chat yang disimpan dari penyimpanan lokal sebelum menampilkan ulang. Referensi sesi yang disimpan akan dibatalkan setelah panggilan gagal.

Contoh penggunaan

try {
 const chat = await client.loadOngoingChat()
} catch (error) {
 // handle error
}

resumeChat

Melanjutkan sesi chat yang sebelumnya ditutup berdasarkan ID-nya, sehingga konsumen dapat melanjutkan percakapan.

Jika klien sudah memiliki referensi ke chat dengan ID yang sama, metode ini akan melakukan short-circuit: metode ini akan mem-patch status ke queued pada instance yang ada, bukan mengambil instance baru. Jika ID tidak cocok, instance Chat baru akan dibuat dan didaftarkan.

Tanda tangan metode

resumeChat(chatId: number | string): Promise<Chat>

Nilai yang ditampilkan

Menampilkan instance Chat.

Contoh penggunaan

try {
 const chat = await client.resumeChat(1234)
} catch (error) {
 // handle error
}

finishChat

Menetapkan status sesi chat saat ini ke selesai. Tindakan ini akan mengakhiri chat dari sisi konsumen.

Jika chat terhubung ke penyedia real-time dan dalam status berakhir setelah PATCH, metode ini juga akan memutuskan koneksi dari penyedia. Pemanggil tidak perlu memanggil destroyChat jika tujuannya hanya untuk mengakhiri chat dengan baik.

Tanda tangan metode

finishChat(): Promise<void>

Contoh penggunaan

try {
 await client.finishChat()
} catch (error) {
 // handle error
}

destroyChat

Menyelesaikan dan menghancurkan sesi chat saat ini, membersihkan semua status internal. Tindakan ini akan memanggil finishChat secara internal, lalu menghentikan instance chat. Sebelum menyelesaikan chat, metode ini akan membisukannya (menonaktifkan peristiwa real-time yang masuk) untuk menghindari pemrosesan pesan selama penghapusan. Menghapus ID pelacak internal setelah chat dihancurkan.

Tanda tangan metode

destroyChat(): Promise<void>

Contoh penggunaan

try {
 await client.destroyChat()
} catch (error) {
 // handle error
}

fetchMessages

Mengambil histori pesan untuk sesi chat saat ini dari penyedia real-time. Harus dipanggil setelah chat terhubung; jika dipanggil sebelum chat terhubung, metode ini akan menampilkan array kosong, bukan menampilkan error. Secara otomatis mengambil URL dokumen untuk pesan jenis document dan menggabungkannya ke dalam respons. Untuk pesan jenis server_message, mengambil konten pesan agen virtual tugas dan memformatnya secara inline. Menampilkan array kosong saat terjadi kegagalan, bukan menampilkan error.

Tanda tangan metode

fetchMessages(): Promise<MessageResponse[]>

Nilai yang ditampilkan

Menampilkan array MessageResponse. Menampilkan array kosong jika gagal.

Peringatan: Metode ini tidak menampilkan error saat gagal. Menampilkan array kosong ([]) jika pengambilan pesan gagal. Jangan mengandalkan try/catch; periksa nilai yang ditampilkan.

Antarmuka

interface MessageResponse {
  $index: number;
  $sid: string;
  $timestamp: Date;
  $userType: string;
  $userId: number;
  type: string;
  content?: string;
  event?: string;
  file?: File;
  media_id?: number;
  groupMessageId?: number;
  document?: {
    url: string;
  };
  unredacted?: string;
  buttons?: {
    title: string;
  }[];
  message?: { messages: string[], type };
  signature?: string,
  form?: {
    id: number,
    form_type: string,
    name: string,
    title: string,
    subtitle: string,
    external_form_id: string,
    smart_action_id: number,
    image: string
  }

  // allow extra parameters
  [key: string]: unknown;
}

Contoh penggunaan

const messages = await client.fetchMessages()

sendTextMessage

Mengirim pesan teks dalam sesi chat saat ini.

Metode ini membersihkan konten mentah sebelum mengirim dan menampilkan lebih awal (no-op) jika hasilnya kosong. Jika chat berada dalam alur agen virtual tugas (inTask), pesan akan dirutekan melalui endpoint agen virtual tugas, bukan saluran reguler. Jika penyuntingan sisi server diaktifkan, pesan akan dikirim menggunakan endpoint server, bukan melalui penyedia real-time secara langsung.

Tanda tangan metode

sendTextMessage(rawContent: string): Promise<void>

Contoh penggunaan

try {
 await client.sendTextMessage("hello world")
} catch (error) {
 // handle error
}

sendFileMessage

Mengupload file ke sesi chat saat ini melalui proses tiga langkah: mendapatkan URL cloud-storage yang telah ditandatangani dari server, mengupload file langsung ke URL tersebut, lalu mengonfirmasi upload kembali ke server. Rute upload ditentukan secara otomatis dari jenis MIME file: gambar dikirim sebagai pesan foto dan video sebagai pesan video; jenis file lainnya dirutekan berdasarkan jenis MIME-nya. Menampilkan ID pesan jika berhasil, atau -1 jika gagal.

Tanda tangan metode

sendFileMessage(file: File): Promise<number>

Nilai yang ditampilkan

Menampilkan ID pesan atau -1 jika upload gagal. Namun, pengiriman pesan berikutnya masih dapat ditolak (misalnya, ChatEndedError), jadi gabungkan panggilan di try/catch selain memeriksa -1.

Contoh penggunaan

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
try {
  const id = await client.sendFileMessage(file)
  if (id === -1) {
    // handle upload failure
  }
} catch (error) {
  // handle message-send failure
}

sendPreviewMessage

Mengirim pesan pratinjau dalam sesi chat saat ini. Pesan pratinjau biasanya digunakan untuk menunjukkan kepada agen apa yang diketik konsumen sebelum pesan dikirim. Jika redaction_enabled dan agent_incoming_ha_enabled bernilai benar (true) pada status chat, pratinjau akan dikirim melalui endpoint server (POST /chats/{id}/redact_messages), bukan saluran penyedia real-time.

Tanda tangan metode

sendPreviewMessage(content: string): Promise<void>

Contoh penggunaan

try {
 await client.sendPreviewMessage('preview content')
} catch (error) {
 // handle error
}

getChatDeflection

Mengambil konfigurasi pengalihan chat untuk sesi chat saat ini, termasuk apakah pengalihan diaktifkan, batas waktu tunggu, dan opsi pengalihan yang tersedia.

Menampilkan null jika pengalihan tidak diaktifkan untuk chat (kolom enabled respons server bernilai salah). Pemanggil harus melakukan pemeriksaan null sebelum membaca respons.

Tanda tangan metode

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Nilai yang ditampilkan

Menampilkan objek ChatDeflectionResponse atau null jika pengalihan tidak diaktifkan untuk chat.

Antarmuka

interface ChatDeflectionResponse {
 enabled: boolean;
 threshold: number;
 email: boolean;
 keep_waiting: boolean;
 external_deflection_links: {
   enabled: boolean;
   ids: number[];
 };
}

Contoh penggunaan

try {
 const deflection = await client.getChatDeflection()
} catch (error) {
 // handle error
}

sendChatTranscripts

Mengirim transkrip chat saat ini ke alamat email yang ditentukan.

Tanda tangan metode

sendChatTranscripts(emails: string[]): Promise<void>

Contoh penggunaan

try {
 await client.sendChatTranscripts([
   "[e-mail]",
   "[e-mail]",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

Memulai download transkrip chat saat ini sebagai PDF. Menampilkan objek transkrip yang dapat digunakan dengan getPdfStatus untuk melacak progres pembuatan.

Tanda tangan metode

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Nilai yang ditampilkan

Menampilkan objek transkrip.

Antarmuka

interface GenerateTranscriptResponse {
 status: string;
 chat_transcript_id: number;
}

Contoh penggunaan

try {
 const resp = await client.downloadChatTranscript()
} catch (error) {
 // handle error
}

getPdfStatus

Memeriksa status pembuatan PDF transkrip chat yang diminta sebelumnya. Gunakan chat_transcript_id yang ditampilkan oleh downloadChatTranscript untuk melakukan polling penyelesaian.

Tanda tangan metode

getPdfStatus(id: number): Promise<RequestReturn>

Nilai yang ditampilkan

Menampilkan objek status PDF.

Antarmuka

interface RequestReturn {
   //...
   headers,
   data: PdfStatusResponse,
 }


 interface PdfStatusResponse {
   status: string;
   body?: File;
   failed_reason?: string;
 }

Contoh penggunaan

const response = await client.getPdfStatus(pdfId)
// check header for status
const status = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

Mengambil pertanyaan survei pasca-chat yang dikonfigurasi untuk sesi chat saat ini. Survei ditampilkan kepada konsumen setelah chat berakhir.

Tanda tangan metode

getChatSurvey(): Promise<ChatSurveyResponse | null>

Nilai yang ditampilkan

Menampilkan objek ChatSurveyResponse atau null.

Antarmuka

interface QuestionItem {
 id: number;
 type: "csat" | "star" | "free-form" | "scale" | "enumeration";
 display_text: string;
 name?: string;
 is_csat?: boolean;
 position?: number;
 valid_answers?: {
   key: string;
   value: string;
 }[]
}
interface ChatSurveyResponse {
 id?: number;
 lang?: string;
 sign_off_display_text: string;
 questions: QuestionItem[];
}

Contoh penggunaan

try {
 const data = await client.getChatSurvey()
 if (data) {
   console.log(data.questions)
 }
} catch (error) {
 // handle error
}

sendChatSurvey

Mengirimkan jawaban konsumen untuk survei pasca-chat. Setiap jawaban diberi kunci berdasarkan ID pertanyaan.

Tanda tangan metode

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Peringatan: Metode ini akan langsung menampilkan error jika jenis masukan chat bukan 'survey'. Pemanggil harus memeriksa chat.feedbackType === 'survey' sebelum memanggil, atau menangani error.

Antarmuka

interface SurveyAnswers {
 [question_id: string]: number | string;
}

Contoh penggunaan

try {
 await client.sendChatSurvey({
   123: "a",
   231: "b",
 })
} catch (error) {
 // handle error
}

sendChatRate

Mengirimkan rating konsumen dan masukan opsional untuk sesi chat. Digunakan saat jenis masukan pasca-chat adalah rating, bukan survei lengkap.

Tanda tangan metode

sendChatRate(data: RateRequest): Promise<void>

Peringatan: Metode ini akan langsung menampilkan error jika jenis masukan chat bukan 'rate'. Pemanggil harus memeriksa chat.feedbackType === 'rate' sebelum memanggil, atau menangani error.

Antarmuka

interface RateRequest {
 rating: number;
 feedback?: string;
}

Contoh penggunaan

try {
 await client.sendChatRate({
   rating: 5,
   feedback: "Very good service",
 })
} catch (error) {
 // handle error
}

escalateChat

Mengekskalasi chat saat ini dari agen virtual ke agen manusia.

Tanda tangan metode

escalateChat(data?: EscalateRequest): Promise<void>

Antarmuka

interface EscalateRequest {
 force_escalate: boolean;
 menu_id: number;
 lang: string;
}

Contoh penggunaan

try {
 // Escalate to a specific menu in a given language
 await client.escalateChat({
   force_escalate: true,
   menu_id: 123,
   lang: 'en',
 })
} catch (error) {
 // handle error
}
// Or, escalate without arguments to use defaults
try {
 await client.escalateChat()
} catch (error) {
 // handle error
}

trackChatEscalation

Melacak peristiwa eskalasi chat, mencatat ID eskalasi dan saluran tempat peristiwa tersebut dieskalasikan.

Tanda tangan metode

trackChatEscalation(escalationId: number, channel: string): Promise<void>

Contoh penggunaan

try {
 await client.trackChatEscalation(escalationId, channel)
} catch (error) {
 // handle error
}

trackChatEndUserEvent

Melacak peristiwa pengguna akhir kustom selama sesi chat, yang dapat digunakan untuk analisis atau untuk memicu alur kerja backend. Jika objek data tidak menyertakan end_user_name dan nama tersedia di profil pengguna yang diautentikasi, objek tersebut akan diisi secara otomatis sebelum permintaan dikirim.

Tanda tangan metode

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Nilai yang ditampilkan

Menampilkan void.

Antarmuka

interface ChatEndUserEventRequest {
  event: {
    name: string;
    payload: Record<string, string>;
  };
  end_user_name?: string;
}

Contoh penggunaan

try {
 await client.trackChatEndUserEvent({
   event: {
     name: 'add_to_cart',
     payload: {
       product_id: 'sku-1234',
       quantity: '2',
     },
   },
   // end_user_name is auto-populated from the authenticated user
   // profile if omitted
 })
} catch (error) {
 // handle error
}

getChatHistory

Mengambil histori chat konsumen sebelumnya, termasuk konten pesan dan metadata. Hasil diberi nomor halaman. Halaman 1 menampilkan hingga 2 percakapan; halaman berikutnya masing-masing menampilkan 1 percakapan. Penomoran halaman asimetris ini disengaja dan memungkinkan panggilan pertama untuk melakukan pramuat konteks histori yang berdekatan.

Tanda tangan metode

getChatHistory(page?: number): Promise<ChatHistoryResponse | null>

Nilai yang ditampilkan

Menampilkan objek ChatHistoryResponse atau null.

Antarmuka

interface ChatHistoryItem {
 comm_id: number;
 assigned_at: string;
 comm_type: string;
 timezone: string;
 entries: MessageResponse[];
 [key: string]: unknown;
}
interface ChatHistoryResponse {
 chats: ChatHistoryItem[];
 missing_chat_ids: number[];
 pagination: {
   next_page: number;
   per_page: number;
 }
}

Contoh penggunaan

try {
 const data = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

Email

Nama	Deskripsi
createEmail	Mengirim email ke saluran email ID menu tertentu.
getProhibitedFileTypes	Dapatkan jenis file yang dilarang untuk lampiran email.

createEmail

Mengirim pesan email ke saluran email yang terkait dengan menu yang diberikan. Konsumen dapat menyertakan nama, alamat email, isi pesan, dan lampiran file opsional.

Tanda tangan metode

createEmail(menuId: number | string, data: EmailRequest): Promise<EmailResponse>

Nilai yang ditampilkan

Menampilkan objek EmailResponse jika gagal atau berhasil.

Antarmuka

interface EmailRequest {
 name?: string;
 email: string;
 content: string;
 lang?: string;
 files?: File[];
 recaptcha?: string;
}
interface EmailResponse {
 id: number;
 type: string;
 status: string;
 fail_reason: string;
 attachment_count: number;
}

Contoh penggunaan

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "[e-mail]",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

Mengambil daftar jenis file yang tidak diizinkan sebagai lampiran email, seperti yang dikonfigurasi oleh administrator.

Tanda tangan metode

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Nilai yang ditampilkan

Menampilkan array FileTypeItem.

Antarmuka

interface FileTypeItem {
 extension: string;
 description: string;
}

Contoh penggunaan

try {
 const types = await client.getProhibitedFileTypes()
} catch (error) {
 // handle error
}

Berbagi layar

Nama	Deskripsi
createCobrowseCode	Membuat kode berbagi layar.
startCobrowse	Minta sesi berbagi layar.
restoreCobrowseSession	Memulihkan sesi berbagi layar setelah jendela browser dibuka kembali.

createCobrowseCode

Membuat kode sesi cobrowse (berbagi layar) unik yang dapat dibagikan kepada agen untuk memulai sesi. Melakukan inisialisasi klien cobrowse jika belum diinisialisasi. Menggunakan kembali nonce yang ada dari penyimpanan, bukan membuat nonce baru pada setiap panggilan, sehingga kode sesi yang sama dapat diambil di seluruh pemuatan halaman.

Tanda tangan metode

createCobrowseCode(lang?: string, customData?: Record<string, string>): Promise<string>

Nilai yang ditampilkan

Menampilkan string kode cobrowse atau string kosong ('') jika gagal.

Peringatan: Metode ini tidak menampilkan error saat gagal. Jangan mengandalkan try/catch; periksa nilai yang ditampilkan.

Contoh penggunaan

const code = await client.createCobrowseCode()
// 123456

startCobrowse

Meminta memulai sesi cobrowse (berbagi layar) dari sisi pengguna akhir selama chat aktif.

Tanda tangan metode

startCobrowse(from?: string): Promise<void>

Peringatan: Metode ini akan menampilkan error jika chat saat ini tidak dibuat dengan cobrowsable: true. Penelepon dapat memeriksa chat.cobrowsable sebelum menelepon untuk menghindari lemparan.

Contoh penggunaan

try {
 await client.startCobrowse()
} catch (error) {
 // handle error
}

restoreCobrowseSession

Mencoba memulihkan sesi cobrowse yang sebelumnya aktif setelah jendela browser dibuka kembali atau widget dimuat ulang.

Tanda tangan metode

restoreCobrowseSession(): Promise<void>

Nilai yang ditampilkan

Menampilkan Promise<void>. Metode ini adalah no-op (segera ditampilkan tanpa error) jika cobrowse tidak diaktifkan di opsi klien atau jika tidak ada sesi cobrowse sebelumnya di penyimpanan.

Peringatan: Metode ini tidak menampilkan error. Jika terjadi error selama pemulihan, metode ini akan mencatat error secara internal dan menghapus sesi cobrowse yang disimpan, lalu kembali dengan lancar. Penelepon tidak memerlukan try/catch.

Contoh penggunaan

// Safe to call unconditionally - will no-op if cobrowse is not enabled
// or if no previous session exists
await client.restoreCobrowseSession()

Agen virtual setelah sesi

Nama	Deskripsi
updatePostSession	Menetapkan status pasca-sesi chat yang sedang berlangsung.

updatePostSession

Metode ini digunakan untuk memperbarui status agen virtual pasca-sesi untuk chat yang sedang berlangsung.

• Memperbarui status agen virtual pasca-sesi untuk chat yang sedang berlangsung. Gunakan ini untuk menunjukkan kesiapan, progres, atau penyelesaian alur agen virtual pasca-sesi.

• Segera ditampilkan sebagai no-op jika postSessionStatus adalah FINISHED atau WAITING — transisi tersebut ditangani secara internal.

• Memiliki logika percobaan ulang internal khusus untuk status IN_PROGRESS pada respons 400, sehingga pemanggil tidak perlu menerapkan percobaan ulang sendiri untuk kasus tersebut.

Tanda tangan metode

updatePostSession(postSessionStatus: PostSessionStatus, optInSelection?: boolean): Promise<void>

Antarmuka

enum PostSessionStatus {
 READY = 'ready',
 IN_PROGRESS = 'in_progress',
 WAITING = 'waiting',
 FINISHED = 'finished',
}

Contoh penggunaan

try {
 // Without opt-in selection
 await client.updatePostSession(PostSessionStatus.READY)
 // With opt-in selection
 await client.updatePostSession(PostSessionStatus.READY, true)
} catch (error) {
 // handle error (e.g., show a notification to the user)
}

Antarmuka terkait

interface ChatResponse {
 //...
 post_session_required?: boolean;
 post_session_opt_in_required?: boolean;
 post_session_transfer_status?: string;
}

• post_session_required - post session required after a chat.

• post_session_opt_in_required - apakah keikutsertaan diaktifkan.

• post_session_transfer_status - ini adalah salah satu enum PostSessionStatus.

Proses Debug

Nama	Deskripsi
getLogs	Mengambil log debug internal dari SDK.
printLogs	Mencetak log debug internal ke konsol browser.

getLogs

Mengambil log debug internal yang dikumpulkan oleh SDK, termasuk log tingkat bridge dan tingkat root. Berguna untuk memecahkan masalah integrasi.

Tanda tangan metode

getLogs(): Promise<{ bridgeLogs: LogHistoryData[], rootLogs: LogHistoryData[] }>

Nilai yang ditampilkan

Menampilkan objek yang berisi dua array LogHistoryData.

Antarmuka

interface LogHistoryData {
 date: string;
 channel: string;
 level: string;
 args: any[];
}

Catatan: Log jembatan diambil terlebih dahulu secara internal, karena pengambilan itu sendiri menghasilkan entri log root. Oleh karena itu, rootLogs sengaja menangkap log akhir tersebut.

Perincian

Setiap entri LogHistoryData mencatat satu peristiwa log:

• date - Stempel waktu ISO 8601 peristiwa.

• channel - modul SDK yang memunculkannya (misalnya, klien tingkat atas, lapisan chat, lapisan cobrowse, penyedia real-time).

• level - tingkat keparahan log: debug, info, warn, atau error.

• args - argumen mentah yang diambil oleh panggilan log.

Contoh entri:

{
 "date": "2026-05-08T14:02:13.412Z",
 "channel": "Provider",
 "level": "info",
 "args": ["chat connected", { "chatId": 4421 }]
}

Kumpulan saluran dan konten pesan yang tepat dapat berkembang di antara rilis SDK. Perlakukan log sebagai bantuan proses debug, bukan target penguraian yang stabil - jangan membangun logika produksi yang bergantung pada nama channel atau string pesan tertentu.

Cakupan dan penggunaan yang direkomendasikan

getLogs menampilkan data internal SDK yang dimaksudkan untuk membantu mendiagnosis masalah integrasi dengan SDK web headless itu sendiri. Kasus penggunaan utamanya adalah diagnostik dukungan: saat pengguna akhir melaporkan masalah, aplikasi Anda dapat mengambil hasil getLogs dan melampirkannya ke tiket dukungan yang dikirim ke CCAI Platform.

Log yang ditampilkan tidak mencakup:

• Telemetri aplikasi, peristiwa bisnis, atau navigasi pengguna halaman host Anda.

• Kegagalan jaringan yang tidak ditampilkan browser ke SDK (misalnya, CORS, konten campuran, atau error sertifikat).

• Trace permintaan sisi server atau detail backend selain status HTTP yang ditampilkan ke SDK.

getLogs bukan pengganti alat kemampuan observasi Anda sendiri. Sebaiknya gabungkan SDK dengan:

• Pelacak error/RUM sisi browser (Sentry, Datadog Browser RUM, New Relic Browser, atau yang setara).

• Logging sisi server di endpoint autentikasi Anda (callback authenticate yang dipanggil SDK).

• Pemroses tingkat aplikasi di chat.disconnected, chat.timeout, dan chat.ended jika Anda perlu meneruskan sinyal siklus proses chat ke pipeline telemetri Anda sendiri.

Contoh penggunaan

try {
 const { bridgeLogs, rootLogs } = await client.getLogs()
 console.log('Bridge logs:', bridgeLogs)
 console.log('Root logs:', rootLogs)
} catch (error) {
 // handle error
}

printLogs

Mencetak semua log debug internal langsung ke konsol browser. Ini adalah metode praktis yang memanggil getLogs() secara internal dan memformat output.

Tanda tangan metode

printLogs(): Promise<void>

Contoh penggunaan

try {
 await client.printLogs()
} catch (error) {
 // handle error
}

Lain-lain

Nama	Deskripsi
runTrigger	Memeriksa pemicu proaktif untuk mengetahui apakah ada yang harus diaktifkan.
getAfterHourMessage	Dapatkan pesan untuk pengalihan setelah jam kerja.

runTrigger

Melakukan iterasi pada pemicu proaktif yang dikonfigurasi dan memanggil callback yang disediakan untuk pemicu yang kondisinya terpenuhi (kata kunci URL, jumlah kunjungan halaman, waktu tinggal, jenis pengunjung).

Tanda tangan metode

runTrigger(cb: (trigger: TriggerItem) => void): Promise<void>

Antarmuka

interface TriggerItem {
 id: number;
 menu_id: number;
 messages: TriggerMessage[];
 keywords_included?: string[];
 keywords_included_or?: string[][];
 keywords_excluded?: string[];
 keywords_excluded_or?: string[][];
 lang?: string;
 page_visit_count: number;
 stay_time: number;
 visitor_type: string;
}
interface TriggerMessage {
 lang: string;
 text: string;
}

Contoh penggunaan

await client.runTrigger((trigger: TriggerItem) => {
 // code to run for given trigger
})

getAfterHourMessage

Menampilkan pesan pengalihan yang dikonfigurasi untuk ditampilkan saat saluran yang diminta berada di luar jam buka.

Tanda tangan metode

Tanda tangan metodenya adalah:

getAfterHourMessage(lang?: string): Promise<string>

Nilai yang ditampilkan

Menampilkan string yang berisi pesan yang dikonfigurasi.

Contoh penggunaan

try {
 const message: string = await client.getAfterHourMessage()
} catch (error) {
 // handle error
}