Métodos de la API del SDK web sin interfaz gráfica

En esta página, se enumeran los métodos de API disponibles para el SDK web sin encabezado.

Empresa y menús

Son métodos para controlar los valores y los menús de la empresa.

getTrigger

Este método detecta los activadores proactivos de la página actual. Devuelve el activador coincidente actual o null.

const trigger = await client.getTrigger()

getCompany

Este método recupera la información de la empresa.

Firma del método

getCompany(): Promise<CompanyResponse>

Valor que se devuelve

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

Ejemplo de uso

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

getMenus

Este método enumera todos los elementos de menú disponibles para el arrendatario.

Firma del método

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

Valor que se devuelve

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

Ejemplo 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

Este método obtiene el tiempo de espera del canal de chat o el canal de llamadas de un menú.

Firma del método

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

Valor que se devuelve

Muestra un objeto WaitTimeResponse.

Interfaces

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

Ejemplo de uso

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

Llamadas

Son métodos para controlar las llamadas programadas a través del SDK.

createCall

Este método crea una llamada instantánea o programada.

Firma del método

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

Valor que se devuelve

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

Ejemplo de uso

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

loadCall

Este método recupera la información de la llamada para un ID de llamada especificado.

Firma del método

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

Valor que se devuelve

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

Ejemplo de uso

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

cancelCall

Este método cancela una llamada.

Firma del método

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

Valor que se devuelve

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

Ejemplo de uso

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

getTimeSlots

Recupera los horarios disponibles para las llamadas programadas en un menú determinado.

Cuando se llama con un objeto de opciones GetTimeSlotsRequest, este método admite lo siguiente:

• Programación de llamadas avanzada: useAdvancedCallScheduling: true

• Cómo reprogramar una llamada existente: rescheduleCallId

Aún se admite la firma de cadena lang obsoleta y se enruta al mismo extremo, con solo lang propagado.

Firma del método

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

Advertencia: La firma anterior, getTimeSlots(menuId, lang?), dejó de estar disponible. Google recomienda migrar a la nueva firma basada en opciones, como se documenta aquí. La firma anterior sigue funcionando, pero es posible que se desactive en una versión posterior.

Valor que se devuelve

Devuelve un array de cadenas de ranuras de tiempo.

Interfaces

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

Ejemplo 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

Este método verifica si hay horarios disponibles para un menú determinado sin recuperar la lista completa de horarios. Puedes usarlo para mostrar de forma condicional las opciones de programación desde la IU.

Firma del método

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

Valor que se devuelve

Devuelve true si hay intervalos disponibles. En caso contrario, false.

Ejemplo de uso

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

Chats

Son métodos para controlar chats con el SDK.

createChat

Este método crea un chat nuevo.

Firma del método

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

Valor que se muestra

Devuelve una instancia 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>;
  };
}

Ejemplo de uso

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

loadChat

Este método recupera la información de un chat para un ID de chat determinado.

Firma del método

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

Valor que se devuelve

Devuelve una instancia de Chat.

Ejemplo de uso

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

loadOngoingChat

Este método se usa para obtener la instancia de chat en curso.

Firma del método

loadOngoingChat(): Promise<Chat | null>

Valor que se muestra

Devuelve una instancia de Chat si se encuentra o un valor nulo si no existe un chat en curso. Limpia los valores de almacenamiento si el chat no está en curso.

Ejemplo de uso

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

resumeChat

Este método reanuda un chat descartado.

Firma del método

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

Valor que se devuelve

Devuelve una instancia de chat.

Ejemplo de uso

client.resumeChat(1234)

finishChat

Este método cambia el estado del chat a finished.

Firma del método

finishChat(): Promise<void>

Ejemplo de uso

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

destroyChat

Este método destruye el chat en curso actual.

Firma del método

destroyChat(): Promise<void>

Ejemplo de uso

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

fetchMessages

Este método se usa para obtener todos los mensajes anteriores. Si se produce un error, se devolverá un array vacío. Usarías este método después de que se conecte el chat.

Firma del método

fetchMessages(): Promise<MessageResponse[]>

Valor que se muestra

Devuelve un array de MessageResponse. Devuelve un array vacío si falla.

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

Ejemplo de uso

const messages = client.fetchMessages()

sendTextMessage

Este método envía un mensaje de texto.

Firma del método

sendTextMessage(rawContent: string): Promise<void>

Ejemplo de uso

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

sendFileMessage

Este método envía un mensaje de archivo.

Firma del método

sendFileMessage(file: File): Promise<number>

Valor que se devuelve

Devuelve el ID del mensaje o -1 en caso de error.

Ejemplo de uso

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

sendPreviewMessage

Se usa para enviar una vista previa del mensaje al adaptador del agente. El mensaje de vista previa solo se muestra en el adaptador del agente si se llama al método startTyping. El mensaje de vista previa solo se muestra hasta que se envía el mensaje final o se llama al método stopTyping. Para obtener más información, consulta Experiencia del agente: Vista previa del mensaje.

Firma del método

sendPreviewMessage(content: string): Promise<void>

Ejemplo 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

Firma del método

startTyping()

Ejemplo de uso

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

stopTyping

Firma del método

stopTyping()

Ejemplo de uso

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

getChatDeflection

Este método obtiene la configuración de desvío del chat.

Firma del método

getChatDeflection(): Promise<ChatDeflectionResponse>

Valor que se devuelve

Muestra un objeto ChatDeflectionResponse.

Interfaces

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

Ejemplo de uso

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

sendChatTranscripts

Envía las transcripciones de chat actuales a los correos electrónicos especificados.

Firma del método

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

Ejemplo de uso

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

downloadChatTranscript

Firma del método

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valor que se devuelve

Devuelve el objeto de transcripción.

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

Ejemplo de uso

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

getPdfStatus

Firma del método

getPdfStatus(id: number): Promise<RequestReturn>

Valor que se devuelve

Devuelve el objeto de estado del PDF.

Interfaces

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

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

Ejemplo 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

Este método se usa para obtener las preguntas de la encuesta de chat.

Firma del método

getChatSurvey(): Promise<ChatSurveyResponse>

Valor que se devuelve

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

Ejemplo de uso

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

sendChatSurvey

Este método envía una encuesta al consumidor.

Firma del método

sendChatSurvey(answers: SurveyAnswers): void

Interfaces

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

Ejemplo de uso

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

sendChatRate

Este método envía los comentarios del usuario final sobre el chat actual cuando este finaliza.

Firma del método

sendChatRate(data: RateRequest): Promise<void>

Interfaces

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

Ejemplo de uso

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

escalateChat

Firma del método

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

Interfaces

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

Ejemplo de uso

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

trackChatEscalation

Firma del método

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

Ejemplo de uso

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

trackChatEndUserEvent

Firma del método

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valor que se muestra

Devuelve un valor nulo.

Interfaces

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

Ejemplo de uso

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

getChatHistory

Firma del método

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

Valor que se devuelve

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

Ejemplo de uso

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

Correos electrónicos

Son métodos para controlar los correos electrónicos de asistencia.

createEmails

Firma del método

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

Valor que se devuelve

Devuelve un objeto EmailResponse en caso de error o éxito.

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

Ejemplo 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

Firma del método

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Valor que se devuelve

Devuelve un array de FileTypeItem.

Interfaces

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

Ejemplo de uso

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

Compartir la pantalla

Son los métodos para controlar la capacidad de compartir pantalla.

createCobrowseCode

Este método crea un código de Screen Share.

Firma del método

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

Valor que se devuelve

Devuelve una cadena de código de Compartir pantalla o una cadena vacía si falla.

Ejemplo de uso

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

startCobrowse

Firma del método

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

Ejemplo de uso

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

restoreCobrowseSession

Este método intenta restablecer una sesión de Compartir pantalla que estaba activa anteriormente después de que se vuelve a abrir la ventana del navegador o se vuelve a cargar el widget.

Firma del método

restoreCobrowseSession(): Promise<void>

Valor que se devuelve

Muestra Promise<void>. Este método no realiza ninguna operación (muestra un resultado de inmediato sin errores) si la función de Compartir pantalla no está habilitada para tu instancia o si no existe ninguna sesión anterior de Compartir pantalla en el almacenamiento.

Nota: Este método no arroja un error. Si se produce un error durante el restablecimiento de la sesión de uso compartido de pantalla, el método registra el error de forma interna, borra la sesión de uso compartido de pantalla almacenada y, luego, muestra un resultado limpio. No es necesario que controles los errores con try y catch.

Ejemplo de uso

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

getMessageAttachment

Firma del método

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

Valor que se devuelve

Devuelve un objeto File si se encuentra o un valor nulo si no es aplicable.

Ejemplo de uso

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

Agentes virtuales posteriores a la sesión

Son métodos para controlar agentes virtuales posteriores a la sesión.

updatePostSession

Actualiza el estado del agente virtual posterior a la sesión para el chat en curso. Úsalo para indicar la disponibilidad, el progreso o la finalización de un flujo del agente virtual posterior a la sesión. Este método muestra inmediatamente un no-op si postSessionStatus es FINISHED o WAITING porque esas transiciones se controlan de forma interna. Este método tiene una lógica de reintento interna específicamente para el estado IN_PROGRESS en una respuesta 400, por lo que los llamadores no necesitan implementar su propio reintento para ese caso.

Firma del método

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

Interfaces

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

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

Interfaz relacionada

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

• post_session_required: Se requiere una sesión posterior después de un chat.
• post_session_opt_in_required: Si se habilitó la opción de participación.
• post_session_transfer_status: Es una enumeración de PostSessionStatus.

Depuración

Son métodos para depurar el SDK.

getLogs

Recupera los registros de depuración internos recopilados por el SDK, incluidos los registros a nivel de puente y a nivel raíz. Esto es útil para solucionar problemas de integración.

Firma del método

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

Valor que se devuelve

Devuelve un objeto que contiene dos arrays de LogHistoryData.

Interfaces

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

Nota: El sistema recupera primero los registros de puente, ya que la recuperación produce una entrada de registro raíz. Como resultado, rootLogs captura intencionalmente ese registro final.

Ejemplo 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 los registros de depuración internos directamente en la consola del navegador. Este es un método de conveniencia que llama a getLogs() de forma interna y formatea el resultado.

Firma del método

printLogs(): Promise<void>

Ejemplo de uso

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

Varios

Varios métodos del SDK.

runTrigger

Firma del método

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

Ejemplo de uso

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

getAfterHourMessage

Firma del método

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

Valor que se devuelve

Devuelve una cadena que contiene un mensaje configurado.

Ejemplo de uso

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