Headless web SDK API methods

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

Company and menus

getTrigger

This method detects the current page's proactive triggers. It returns either the current matched trigger or null.

const trigger = await client.getTrigger()

getCompany

This method retrieves the company information.

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;
  cobrowse_domain?: string;
}

Example usage

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

getAfterHourMessage

This method fetches the message for after hour deflection.

Request parameter:

(lang?: string)

Example:

const message: string = await client.getAfterHourMessage()

getMenus

This method lists all menu items available for the tenant.

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

interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
}

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

This method gets the wait time for the chat channel or the call channel of a menu.

Method signature

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

Return value

Returns a WaitTimeResponse object.

Interfaces

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

Example usage

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

Calls

createCall

This method creates an instant or scheduled call.

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

Example Usage

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

loadCall

This method retrieves the call information for a specified call 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

This method cancels a call.

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

This method is used to get available time slots.

Method signature

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

Return value

Returns an array of strings (time slots).

Example usage

try {
  const slots = await client.getTimeSlots(123)
} catch (error) {
  // handle error
}

Chats

createChat

This method creates a new chat.

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 = client.createChat(123, { lang: 'en' })
} catch (error) {
  // handle error
}

loadChat

This method retrieves the chat information for a given chat ID.

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

This method is used to get the ongoing chat instance.

Method Signature

loadOngoingChat(): Promise<Chat | null>

Return Value

Returns a Chat instance if found, or null if no ongoing chat exists. Cleans storage values if chat is not ongoing.

Example usage

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

resumeChat

This method resumes a dismissed chat.

Method signature

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

Return value

Returns a chat instance.

Example usage

client.resumeChat(1234)

finishChat

This method changes the chat status to finished.

Method signature

finishChat(): Promise<void>

Example usage

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

destroyChat

This method destroys the current ongoing chat.

Method signature

destroyChat(): Promise<void>

Example usage

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

fetchMessages

This method is used to get all the previous messages. If a failure occurs, it will return an empty array. You would use this method after the chat is connected.

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

Example usage

const messages = client.fetchMessages()

sendTextMessage

This method sends a text message.

Method signature

sendTextMessage(rawContent: string): Promise<void>

Example usage

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

sendFileMessage

This method sends a file message.

Method signature

sendFileMessage(file: File): Promise<number>

Return value

Returns the message ID or -1 on failure.

Example usage

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
const id = client.sendFileMessage(file)

sendPreviewMessage

Method signature

sendPreviewMessage(content: string): Promise<void>

Example usage

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

getChatDeflection

This method gets the chat deflection configuration.

Method signature

getChatDeflection(): Promise<ChatDeflectionResponse>

Return value

Returns a ChatDeflectionResponse object.

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

Send current chat transcripts to the specified emails.

Method signature

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

Example usage

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

downloadChatTranscript

Method signature

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Return value

Returns the transcript object.

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

Example usage

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

getPdfStatus

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 = resp.headers['x-transcript-status'];

// otherwise use status on data
const data: PdfStatusResponse = resp.data
console.log(data.status)

getChatSurvey

This method is used to get the chat survey questions.

Method signature

getChatSurvey(): Promise<ChatSurveyResponse>

Return value

Returns a ChatSurveyResponse object.

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()
  console.log(data.questions)
} catch (error) {
  // handle error
}

sendChatSurvey

This method sends a survey to the consumer.

Method signature

sendChatSurvey(answers: SurveyAnswers): void

Interfaces

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

Example Usage

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

sendChatRate

This method sends the end-user feedback for the current chat when the chat is finished.

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

Method signature

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

Interfaces

interface EscalateRequest {
  reason?: string;
  // ...other escalation fields
}

Example usage

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

trackChatEscalation

Method signature

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

Example usage

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

trackChatEndUserEvent

Method signature

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Return Value

Returns void.

Interfaces

interface ChatEndUserEventRequest {
  end_user_name?: string;
  // ...other event fields
}

Example usage

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

getChatHistory

Method signature

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

Return value

Returns a ChatHistoryResponse object.

Interfaces

interface ChatHistoryItem {
  comm_id: number;
  assigned_at: string;
  comm_type: string;
  timezone: string;
  entries: MessageResponse[];

}
interface ChatHistoryResponse {
  chats: ChatHistoryItem[];
  missing_chat_ids: number[];
  pagination: {
    next_page: number;
    per_page: number;
  }
}

Example usage

try {
  const data = client.getChatHistory(page: number)
  console.log(data)
} catch (error) {
  console.log(error)
}

Emails

createEmails

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

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

This method creates a Screen Share code.

Method signature

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

Return value

Returns a Screen Share code string or empty string on failure.

Example usage

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

startCobrowse

Method signature

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

Example usage

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

getMessageAttachment

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
}

Post session virtual agents

updatePostSession

Method signature

updatePostSession(postSessionStatus: PostSessionStatus): Promise<void>

Interfaces

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

Example usage

try {
  await client.updatePostSession(PostSessionStatus.READY)
} 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;
}

Values:

  • post_session_required: post session required after a chat

  • post_session_opt_in_required: is opt-in enabled

  • post_session_transfer_status: a PostSessionStatus enumeration

Miscellaneous

runTrigger

Method signature

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

Example usage

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

getAfterHourMessage

Method signature

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
}