Métodos da API do SDK para Web sem interface gráfica

Nesta página, listamos os métodos de API disponíveis para o SDK da Web sem interface gráfica.

Empresa e cardápios

Métodos para processar valores e menus da empresa.

getTrigger

Esse método detecta os gatilhos proativos da página atual. Ele retorna o gatilho correspondente atual ou null.

const trigger = await client.getTrigger()

getCompany

Esse método recupera as informações da empresa.

Assinatura do método

getCompany(): Promise<CompanyResponse>

Valor de retorno

Retorna um objeto CompanyResponse.

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

Exemplo de uso

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

getMenus

Esse método lista todos os itens de menu disponíveis para o locatário.

Assinatura do método

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

Valor de retorno

Retorna um objeto MenuResponse.

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

Exemplo de uso

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

getWaitTimes

Esse método recebe o tempo de espera do canal de chat ou de chamada de um menu.

Assinatura do método

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

Valor de retorno

Retorna um objeto WaitTimeResponse.

Interfaces

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

Exemplo de uso

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

Chamadas

Métodos para processar chamadas programadas pelo SDK.

createCall

Esse método cria uma chamada instantânea ou programada.

Assinatura do método

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

Valor de retorno

Retorna um objeto CallResponse.

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;
  use_advanced_call_scheduling?: boolean;
}

Exemplo de uso

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

loadCall

Esse método recupera as informações de uma chamada especificada.

Assinatura do método

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

Valor de retorno

Retorna um objeto CallResponse.

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

Exemplo de uso

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

cancelCall

Esse método cancela uma chamada.

Assinatura do método

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

Valor de retorno

Retorna um objeto CallResponse.

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

Exemplo de uso

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

getTimeSlots

Recupera os horários disponíveis para chamadas programadas em um determinado menu.

Quando chamado com um objeto de opções GetTimeSlotsRequest, esse método é compatível com o seguinte:

• Programação avançada de chamadas: useAdvancedCallScheduling: true

• Remarcar uma ligação: rescheduleCallId

A assinatura de string lang descontinuada ainda é compatível e direciona para o mesmo endpoint, com apenas lang preenchido.

Assinatura do método

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

Aviso: a assinatura anterior, getTimeSlots(menuId, lang?), foi descontinuada. O Google recomenda migrar para a nova assinatura baseada em opções, conforme documentado aqui. A assinatura antiga continua funcionando, mas pode ser desativada em uma versão posterior.

Valor de retorno

Retorna uma matriz de strings de intervalos de tempo.

Interfaces

interface GetTimeSlotsRequest {
  lang?: string;
  rescheduleCallId?: number;          // ID of an existing call being rescheduled
  useAdvancedCallScheduling?: boolean; // Enable advanced call scheduling behavior
}

Exemplo de uso

// New options-based signature (recommended)
try {
  const slots = await client.getTimeSlots(123, {
    lang: 'en',
    useAdvancedCallScheduling: true,
  })
} catch (error) {
  // handle error
}

// Deprecated signature (still supported)
try {
  const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
  // handle error
}

fetchTimeSlotAvailability

Esse método verifica se há horários disponíveis para um determinado menu sem buscar a lista completa. É possível usar esse recurso para mostrar condicionalmente opções de programação na UI.

Assinatura do método

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

Valor de retorno

Retorna true se houver horários disponíveis. Caso contrário, false.

Exemplo de uso

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

Chats

Métodos para processar chats com o SDK.

createChat

Esse método cria um novo chat.

Assinatura do método

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

Valor de retorno

Retorna uma instância de Chat.

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

Exemplo de uso

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

loadChat

Esse método recupera as informações de um chat com base em um ID específico.

Assinatura do método

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

Valor de retorno

Retorna uma instância de Chat.

Exemplo de uso

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

loadOngoingChat

Esse método é usado para receber a instância de chat em andamento.

Assinatura do método

loadOngoingChat(): Promise<Chat | null>

Valor de retorno

Retorna uma instância Chat se encontrada ou nula se não houver um chat em andamento. Limpa os valores de armazenamento se o chat não estiver em andamento.

Exemplo de uso

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

resumeChat

Esse método retoma um chat dispensado.

Assinatura do método

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

Valor de retorno

Retorna uma instância de chat.

Exemplo de uso

client.resumeChat(1234)

finishChat

Esse método muda o status do chat para finished.

Assinatura do método

finishChat(): Promise<void>

Exemplo de uso

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

destroyChat

Esse método destrói o chat em andamento.

Assinatura do método

destroyChat(): Promise<void>

Exemplo de uso

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

fetchMessages

Esse método é usado para receber todas as mensagens anteriores. Se ocorrer uma falha, ele vai retornar uma matriz vazia. Você usaria esse método depois que a conversa fosse conectada.

Assinatura do método

fetchMessages(): Promise<MessageResponse[]>

Valor de retorno

Retorna uma matriz de MessageResponse. Retorna uma matriz vazia em caso de falha.

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: string;
  };
  signature: string;
  form?: {
    id: number;
    form_type: string;
    name: string;
    title: string;
    subtitle: string;
    external_form_id: string;
    smart_action_id: number;
    image: string;
  };
}

Exemplo de uso

const messages = client.fetchMessages()

sendTextMessage

Esse método envia uma mensagem de texto.

Assinatura do método

sendTextMessage(rawContent: string): Promise<void>

Exemplo de uso

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

sendFileMessage

Esse método envia uma mensagem de arquivo.

Assinatura do método

sendFileMessage(file: File): Promise<number>

Valor de retorno

Retorna o ID da mensagem ou -1 em caso de falha.

Exemplo de uso

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

sendPreviewMessage

Usado para enviar uma prévia de mensagem ao adaptador do agente. A mensagem de prévia só é mostrada no adaptador do agente se o método startTyping for chamado. A mensagem de prévia só é exibida até que a mensagem final seja enviada ou o método stopTyping seja chamado. Para mais informações, consulte Experiência do agente: prévia da mensagem.

Assinatura do método

sendPreviewMessage(content: string): Promise<void>

Exemplo de uso

client.chat.startTyping();
clearTimeout(stopTimer);
stopTimer = setTimeout(() => {
    if (client.chat) {
        client.chat.stopTyping();
    }
}, 5000);

clearTimeout(previewTimer);
const currentTime = Date.now();

if (currentTime - lastPreviewTime >= 2000) {
    lastPreviewTime = currentTime;
    try {
        const response = await client.sendPreviewMessage("chat message");
    } catch (error) {
        console.error("Error sending preview message:", error);
    }
} else {
    previewTimer = setTimeout(async () => {
        lastPreviewTime = Date.now();
        try {
            const response = await client.sendPreviewMessage("chat message");
        } catch (error) {
            console.error("Error sending debounced preview message:", error);
        }
    }, 1000);
}

startTyping

Assinatura do método

startTyping()

Exemplo de uso

try {
  client.startTyping()
} catch (error) {
  // handle error
}

stopTyping

Assinatura do método

stopTyping()

Exemplo de uso

try {
  client.stopTyping()
} catch (error) {
  // handle error
}

getChatDeflection

Esse método recebe a configuração de redução de chat.

Assinatura do método

getChatDeflection(): Promise<ChatDeflectionResponse>

Valor de retorno

Retorna um objeto ChatDeflectionResponse.

Interfaces

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

Exemplo de uso

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

sendChatTranscripts

Envie as transcrições do chat atual para os e-mails especificados.

Assinatura do método

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

Exemplo de uso

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

downloadChatTranscript

Assinatura do método

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valor de retorno

Retorna o objeto de transcrição.

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

Exemplo de uso

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

getPdfStatus

Assinatura do método

getPdfStatus(id: number): Promise<RequestReturn>

Valor de retorno

Retorna o objeto de status do PDF.

Interfaces

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

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

Exemplo de uso

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

Esse método é usado para receber as perguntas da pesquisa por chat.

Assinatura do método

getChatSurvey(): Promise<ChatSurveyResponse>

Valor de retorno

Retorna um objeto ChatSurveyResponse.

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

Exemplo de uso

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

sendChatSurvey

Esse método envia uma pesquisa ao consumidor.

Assinatura do método

sendChatSurvey(answers: SurveyAnswers): void

Interfaces

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

Exemplo de uso

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

sendChatRate

Esse método envia o feedback do usuário final para o chat atual quando ele é encerrado.

Assinatura do método

sendChatRate(data: RateRequest): Promise<void>

Interfaces

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

Exemplo de uso

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

escalateChat

Assinatura do método

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

Interfaces

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

Exemplo de uso

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

trackChatEscalation

Assinatura do método

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

Exemplo de uso

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

trackChatEndUserEvent

Assinatura do método

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valor de retorno

Retorna void.

Interfaces

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

Exemplo de uso

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

getChatHistory

Assinatura do método

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

Valor de retorno

Retorna um objeto ChatHistoryResponse.

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

Exemplo de uso

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

E-mails

Métodos para lidar com e-mails de suporte.

createEmails

Assinatura do método

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

Valor de retorno

Retorna um objeto EmailResponse em caso de falha ou sucesso.

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

Exemplo de uso

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

Assinatura do método

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Valor de retorno

Retorna uma matriz de FileTypeItem.

Interfaces

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

Exemplo de uso

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

Compartilhamento de tela

Métodos para processar a capacidade de compartilhamento de tela.

createCobrowseCode

Esse método cria um código de compartilhamento de tela.

Assinatura do método

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

Valor de retorno

Retorna uma string de código de compartilhamento de tela ou uma string vazia em caso de falha.

Exemplo de uso

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

startCobrowse

Assinatura do método

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

Exemplo de uso

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

restoreCobrowseSession

Esse método tenta restaurar uma sessão de compartilhamento de tela ativa anteriormente depois que a janela do navegador é reaberta ou o widget é recarregado.

Assinatura do método

restoreCobrowseSession(): Promise<void>

Valor de retorno

Retorna Promise<void>. Esse método não faz nada (retorna imediatamente sem erro) se o compartilhamento de tela não estiver ativado para sua instância ou se não houver uma sessão anterior de compartilhamento de tela no armazenamento.

Observação: esse método não gera um erro. Se ocorrer um erro durante a restauração da sessão de compartilhamento de tela, o método vai registrar o erro internamente, limpar a sessão armazenada e retornar sem problemas. Não é necessário processar erros com try e catch.

Exemplo de uso

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

getMessageAttachment

Assinatura do método

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

Valor de retorno

Retorna um objeto File se encontrado ou nulo se não for aplicável.

Exemplo de uso

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

Agentes virtuais pós-sessão

Métodos para lidar com agentes virtuais pós-sessão.

updatePostSession

Atualiza o status do agente virtual pós-sessão para o chat em andamento. Use isso para indicar prontidão, progresso ou conclusão de um fluxo de agente virtual pós-sessão. Esse método retorna imediatamente como uma operação nula se postSessionStatus for FINISHED ou WAITING, porque essas transições são processadas internamente. Esse método tem uma lógica interna de nova tentativa específica para o status IN_PROGRESS em uma resposta 400. Assim, os chamadores não precisam implementar a própria nova tentativa para esse caso.

Assinatura do método

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

Interfaces

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

Exemplo de uso

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

Interface relacionada

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

• post_session_required: sessão de postagem necessária após um chat.
• post_session_opt_in_required: se a ativação estiver habilitada.
• post_session_transfer_status: uma enumeração PostSessionStatus.

Depuração

Métodos para depurar o SDK.

getLogs

Recupera os registros de depuração internos coletados pelo SDK, incluindo registros no nível da ponte e da raiz. Isso é útil para resolver problemas de integração.

Assinatura do método

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

Valor de retorno

Retorna um objeto que contém duas matrizes de LogHistoryData.

Interfaces

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

Observação: o sistema busca primeiro os registros da ponte, porque a busca produz uma entrada de registro raiz. Como resultado, o rootLogs captura intencionalmente esse registro final.

Exemplo de uso

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

printLogs

Imprime todos os registros de depuração internos diretamente no console do navegador. Esse é um método de conveniência que chama getLogs() internamente e formata a saída.

Assinatura do método

printLogs(): Promise<void>

Exemplo de uso

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

Diversos

Métodos diversos do SDK.

runTrigger

Assinatura do método

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

Exemplo de uso

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

getAfterHourMessage

Assinatura do método

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

Valor de retorno

Retorna uma string que contém uma mensagem configurada.

Exemplo de uso

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