Headless web SDK API methods

This page lists the API methods available for the headless web SDK.

Company and menus

Methods for handling company values and menus.

Methods

The headless SDK provides various methods that can be called on the client instance.

Here are some examples:

Company and menus

getCompany

Retrieves the configured company information for the authenticated instance, including the company name, supported languages, and feature settings. This method also sets the internal instance identifier (OPTIONS.tenant) as a side effect, which is why it is typically the first call made after constructing a Client.

Method signature

getCompany(): Promise<CompanyResponse>

Return value

Returns a CompanyResponse object.

Interfaces

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;
}

Example usage

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

getMenus

This method is used to list all the menu items available for the instance. The MenuResponse.direct field tells callers whether the result came from a direct-access key (direct.key: true) or from user-level direct access (direct.user: true) - both affect how the menus should be presented.

Method signature

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

Return value

Returns a MenuResponse object.

Interfaces

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;
}

Example usage

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

getWaitTimes

Retrieves the estimated waiting time (in seconds) for the chat and voice call channels of a given menu.

Method signature

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

Return value

Returns either a WaitTimeResponse object or null.

Interfaces

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

Example usage

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

Calls

createCall

Creates a new call for the given menu. This can be an instant call or a scheduled call, depending on whether the scheduled_at field is provided. The call type (web_instant_call versus web_scheduled_call) is determined automatically based on the presence of scheduled_at. reschedule_call_id is sent at the top level of the request, separate from the call body. The menu_id in the response is normalized from the API's selected_menu.id.

Method signature

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

Return value

Returns a CallResponse object.

Interfaces

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;
}

Example usage

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

loadCall

The loadCall method retrieves information about a specific call, identified by its ID.

Method signature

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

Return value

Returns a CallResponse object.

Interfaces

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;
 }[];
}

Example usage

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

cancelCall

Cancels an existing call by its ID. Typically used to cancel a scheduled call that hasn't yet been placed.

Method signature

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

Return value

Returns a CallResponse object.

Interfaces

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;
 }[];
}

Example usage

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

getTimeSlots

Retrieves available time slots for scheduled calls on a given menu. When called with a GetTimeSlotsRequest options object, supports rescheduling an existing call using rescheduleCallId. The deprecated lang string signature remains supported and routes to the same endpoint with only lang populated. Returns an array of time slot strings.

Method signature

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

Return value

Returns an array of strings (time slots).

Interfaces

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

Example usage

// 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

This method checks whether time slots are available for a given menu, without fetching the full list of time slots. It is useful for conditionally showing scheduling options in the UI.

Scope

fetchTimeSlotAvailability applies only to scheduled voice call (callback) appointments. It doesn't return information about chat, email, or instant-call channels. The supplied menu must be configured to support scheduled voice calls, with operation hours defined and at least one agent queued for that menu.

Typical use cases:

• Conditionally rendering a "Schedule a Callback" call-to-action only when slots are available.

• Branching to a deflection flow (e.g., email, after-hours message) when no slots are available, without paying the cost of a full getTimeSlots call.

• Pre-flighting a reschedule action before calling getTimeSlots with a rescheduleCallId.

Method signature

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

Return value

Returns true if time slots are available, false otherwise.

Example usage

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

Chats

Chat check-in

Check-in asks a consumer to confirm they're ready before connecting to an agent. This section documents the headless web SDK methods for implementing that experience. For what check-in is, how it's enabled and configured (wait-time, timeout, queue position, rejoin behavior), and reporting, see Check-in for Chat.

checkIn

Sends a confirmation signal to the server indicating the consumer is present and ready to connect with an agent during the check-in window. Updates the chat's check_in_status locally after the server acknowledges. Use in response to the chat.checkInRequested event.

Method signature

checkIn(): Promise<CheckInResponse>

Return value

Returns a CheckInResponse object.

Interfaces

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',
}

Example usage

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

exitCheckIn

Signals to the server that the consumer has chosen to leave the check-in queue. Updates check_in_status locally. After calling this method, the consumer won't receive an agent connection for the current check-in cycle.

Method signature

exitCheckIn(): Promise<CheckInResponse>

Return value

Returns a CheckInResponse object.

Interfaces

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',
}

Example usage

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

notifyCheckInState

Informs the server of the check-in modal's current visibility state - whether the widget is minimized or the browser tab is inactive. The server uses this to make decisions about check-in timing. Should be called whenever the widget's visibility or tab focus changes while the chat.checkInRequested event is active.

Method signature

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Interfaces

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

Example usage

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

rejoinChat

Places the consumer back in the queue after they failed to confirm a check-in within the allotted time. Updates check_in_status locally. Use in response to the chat.checkInTimedOut event if the consumer still wants to connect.

Method signature

rejoinChat(): Promise<CheckInResponse>

Return value: Returns a CheckInResponse object.

Interfaces

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',
}

Example usage

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

trackCheckInEvent

Notifies the server that the check-in modal has been displayed to the consumer. Call this once, immediately after presenting the check-in UI in response to chat.checkInRequested. The server uses it for operational analytics on check-in presentation rates. The call is awaited internally and returns a Promise<void> that can reject, so wrap it in try/catch (as the following example does).

Method signature

trackCheckInEvent(): Promise<void>

Example usage

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

getMessageAttachment

Fetches an eligible attachment associated with a specific chat message. Only fetches if the message was sent by a non-end-user ($userType !== 'end_user') and is of a supported attachment type (photo, video, audio, document). Returns null for any message that doesn't meet both conditions, not only for messages without a media_id. Saves the fetched file to the chat's local media cache after retrieval.

Method signature

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

Return value

Returns a File object if found, or null if not applicable.

Example usage

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

createChat

Creates a new chat session for the given menu. You can optionally specify the language, a greeting message, a trigger ID, a ticket ID, and custom data to send with the chat.

After the initial API call, the method polls the server until a provider_channel_id becomes available or the chat is canceled or finished. If a provider channel becomes available, the method initiates the connection to the real-time provider. The connection may still be completing when the promise resolves - listen for the chat.connectedMessages event to know when the connection and initial message retrieval have completed.

Method signature

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

Return value

Returns a Chat instance.

Interfaces

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

Example usage

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

loadChat

Retrieves an existing chat session by its ID.

If the loaded chat is no longer ongoing, the method clears the stored chat ID and cobrowse nonce from local storage. It also does this on error, so callers don't need to handle storage cleanup manually after a failed load.

Method signature

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

Return value

Returns a Chat instance.

Example usage

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

loadOngoingChat

Attempts to load the current ongoing chat session, if one exists. Returns null if no ongoing chat is found.

Method signature

loadOngoingChat(): Promise<Chat | null>

Return value

Returns a Chat instance if found, or null if no ongoing chat exists. Will clean storage values if chat isn't ongoing.

Example usage

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

resumeChat

Resumes a previously dismissed chat session by its ID, allowing the consumer to continue the conversation.

If the client already holds a reference to a chat with the same ID, the method short-circuits: it patches the status to queued on the existing instance rather than fetching a new one. If the IDs don't match, a new Chat instance is created and registered.

Method signature

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

Return value

Returns a Chat instance.

Example usage

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

finishChat

Sets the current chat session's status to finished. This ends the chat from the consumer's side.

If the chat is both connected to the real-time provider and in an ended state after the PATCH, the method also disconnects from the provider. Callers don't need to call destroyChat if only ending the chat gracefully is the goal.

Method signature

finishChat(): Promise<void>

Example usage

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

destroyChat

Finishes and destroys the current chat session, cleaning up all internal state. This calls finishChat internally, then tears down the chat instance. Before finishing the chat, the method mutes it (suppresses incoming real-time events) to avoid processing messages during teardown. Clears the internal tracker ID after the chat is destroyed.

Method signature

destroyChat(): Promise<void>

Example usage

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

fetchMessages

Retrieves the message history for the current chat session from the real-time provider. Should be called after the chat is connected; if called before the chat connects it returns an empty array rather than throwing. Automatically fetches document URLs for any document-type messages and merges them into the response. For server_message-type messages, fetches task virtual agent message content and formats it inline. Returns an empty array on failure rather than throwing.

Method signature

fetchMessages(): Promise<MessageResponse[]>

Return value

Returns an array of MessageResponse. Returns empty array on failure.

Interfaces

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;
}

Example usage

const messages = await client.fetchMessages()

sendTextMessage

Sends a text message in the current chat session.

The method sanitizes the raw content before sending and returns early (no-op) if the result is empty. If the chat is in a task virtual agent flow (inTask), the message is routed through the task virtual agent endpoint instead of the regular channel. If server-side redaction is enabled, the message is sent using a server endpoint rather than through the real-time provider directly.

Method signature

sendTextMessage(rawContent: string): Promise<void>

Example usage

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

sendFileMessage

Uploads a file to the current chat session through a three-step process: obtaining a presigned cloud-storage URL from the server, uploading the file directly to that URL, then confirming the upload back to the server. The upload route is determined automatically from the file's MIME type: images are sent as photo messages and videos as video messages; other file types are routed based on their MIME type. Returns the message ID on success, or -1 on failure.

Method signature

sendFileMessage(file: File): Promise<number>

Return value

Returns the message ID or -1 if the upload failed. However, the subsequent message-send can still reject (for example, ChatEndedError), so wrap the call in try/catch in addition to checking for -1.

Example usage

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

Sends a preview message in the current chat session. Preview messages are typically used to show the agent what the consumer is typing before the message is submitted. If both redaction_enabled and agent_incoming_ha_enabled are true on the chat state, the preview is sent through a server endpoint (POST /chats/{id}/redact_messages) rather than the real-time provider channel.

Method signature

sendPreviewMessage(content: string): Promise<void>

Example usage

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

getChatDeflection

Retrieves the chat deflection configuration for the current chat session, including whether deflection is enabled, the wait time threshold, and the available deflection options.

Returns null if deflection isn't enabled for the chat (the server response's enabled field is falsy). Callers should null-check before reading the response.

Method signature

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Return value

Returns either a ChatDeflectionResponse object or null if deflection isn't enabled for the chat.

Interfaces

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

Example usage

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

sendChatTranscripts

Sends the current chat transcript to the specified email addresses.

Method signature

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

Example usage

try {
 await client.sendChatTranscripts([
   "name1@example.com",
   "name2@example.com",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

Initiates a download of the current chat transcript as a PDF. Returns a transcript object that can be used with getPdfStatus to track the generation progress.

Method signature

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Return value

Returns the transcript object.

Interfaces

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

Example usage

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

getPdfStatus

Checks the generation status of a previously requested chat transcript PDF. Use the chat_transcript_id returned by downloadChatTranscript to poll for completion.

Method signature

getPdfStatus(id: number): Promise<RequestReturn>

Return value

Returns the PDF status object.

Interfaces

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


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

Example usage

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

Retrieves the post-chat survey questions configured for the current chat session. The survey is presented to consumers after a chat ends.

Method signature

getChatSurvey(): Promise<ChatSurveyResponse | null>

Return value

Returns either a ChatSurveyResponse object or null.

Interfaces

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[];
}

Example usage

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

sendChatSurvey

Submits the consumer's answers to the post-chat survey. Each answer is keyed by the question ID.

Method signature

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Interfaces

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

Example usage

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

sendChatRate

Submits the consumer's rating and optional feedback for the chat session. Used when the post-chat feedback type is a rating rather than a full survey.

Method signature

sendChatRate(data: RateRequest): Promise<void>

Interfaces

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

Example usage

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

escalateChat

Escalates the current chat from a virtual agent to a human agent.

Method signature

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

Interfaces

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

Example usage

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

Tracks a chat escalation event, recording the escalation ID and the channel it was escalated to.

Method signature

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

Example usage

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

trackChatEndUserEvent

Tracks a custom end-user event during the chat session, which can be used for analytics or to trigger backend workflows. If the data object doesn't include end_user_name and a name is available on the authenticated user profile, it is populated automatically before the request is sent.

Method signature

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Return value

Returns void.

Interfaces

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

Example usage

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

Retrieves the consumer's past chat history, including message content and metadata. Results are paginated. Page 1 returns up to 2 chats; subsequent pages return 1 chat each. This asymmetric pagination is intentional and allows the first call to pre-load adjacent history context.

Method signature

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

Return value

Returns either a ChatHistoryResponse object or null.

Interfaces

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;
 }
}

Example usage

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

Emails

createEmail

Sends an email message to the email channel associated with the given menu. The consumer can include a name, email address, message body, and optional file attachments.

Method signature

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

Return value

Returns an EmailResponse object on failure or success.

Interfaces

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;
}

Example usage

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "name@example.com",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

Retrieves the list of file types that aren't allowed as email attachments, as configured by the administrator.

Method signature

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Return value

Returns an array of FileTypeItem.

Interfaces

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

Example usage

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

Screen share

createCobrowseCode

Generates a unique cobrowse (screen share) session code that can be shared with an agent to initiate a session. Initializes the cobrowse client if it hasn't been initialized yet. Reuses any existing nonce from storage rather than generating a new one on each call, so the same session code can be retrieved across page loads.

Method signature

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

Return value

Returns a cobrowse code string or empty string ('') on failure.

Example usage

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

startCobrowse

Requests the start of a cobrowse (screen share) session from the end-user's side during an active chat.

Method signature

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

Example usage

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

restoreCobrowseSession

Attempts to restore a previously active cobrowse session after the browser window is reopened or the widget is reloaded.

Method signature

restoreCobrowseSession(): Promise<void>

Return value

Returns Promise<void>. This method is a no-op (returns immediately without error) if cobrowse isn't enabled in the client options or if no previous cobrowse session exists in storage.

Example usage

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

Post session virtual agent

updatePostSession

This method is used to update the post-session virtual agent status for the ongoing chat.

• Updates the post-session virtual agent status for the ongoing chat. Use this to signal readiness, progress, or completion of a post-session virtual agent flow.

• Returns immediately as a no-op if postSessionStatus is FINISHED or WAITING — those transitions are handled internally.

• Has internal retry logic specifically for the IN_PROGRESS status on a 400 response, so callers don't need to implement their own retry for that case.

Method signature

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

Interfaces

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

Example usage

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)
}

Related interface

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 - is opt in enabled.

• post_session_transfer_status - this is one of the PostSessionStatus enums.

Debugging

getLogs

Retrieves the internal debug logs collected by the SDK, including both bridge-level and root-level logs. Useful for troubleshooting integration issues.

Method signature

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

Return value

Returns an object containing two arrays of LogHistoryData.

Interfaces

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

Granularity

Each LogHistoryData entry captures a single log event:

• date - ISO 8601 timestamp of the event.

• channel - the SDK module that emitted it (e.g., top-level client, chat layer, cobrowse layer, real-time provider).

• level - log severity: debug, info, warn, or error.

• args - the raw arguments captured by the log call.

Example entry:

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

The exact set of channels and message contents may evolve between SDK releases. Treat the logs as a debugging aid, not a stable parsing target - don't build production logic that depends on specific channel names or message strings.

Scope and recommended use

getLogs returns SDK-internal records intended to help diagnose integration issues with the headless web SDK itself. Its primary use case is support diagnostics: when an end user reports an issue, your application can capture the result of getLogs and attach it to the support ticket sent to CCAI Platform.

The returned logs do not include:

• Your host page's application telemetry, business events, or user navigation.

• Network failures the browser doesn't surface to the SDK (e.g., CORS, mixed-content, or certificate errors).

• Server-side request traces or backend details beyond the HTTP status returned to the SDK.

getLogs is not a replacement for your own observability tooling. We recommend pairing the SDK with:

• A browser-side error/RUM tracker (Sentry, Datadog Browser RUM, New Relic Browser, or equivalent).

• Server-side logging on your authentication endpoint (the authenticate callback the SDK calls).

• Application-level listeners on chat.disconnected, chat.timeout, and chat.ended if you need to forward chat lifecycle signals to your own telemetry pipeline.

Example usage

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

printLogs

Prints all internal debug logs directly to the browser console. This is a convenience method that calls getLogs() internally and formats the output.

Method signature

printLogs(): Promise<void>

Example usage

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

Miscellaneous

runTrigger

Iterates over configured proactive triggers and invokes the supplied callback for any whose conditions are met (URL keywords, page-visit count, stay time, visitor type).

Method signature

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

Interfaces

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;
}

Example usage

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

getAfterHourMessage

Returns the configured deflection message to display when the requested channel is outside operating hours.

Method signature

The method signature is:

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

Return value

Returns a string containing a configured message.

Example usage

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