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

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

Empresa y menús

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

Métodos

El SDK sin interfaz gráfica proporciona varios métodos a los que se puede llamar en la instancia del cliente.

Estos son algunos ejemplos:

Empresa y menús

Nombre del método	Descripción
getCompany	Recupera la información configurada de la empresa.
getMenus	Enumera todos los menús disponibles para el usuario determinado.
getWaitTimes	Obtén los tiempos de espera actuales para varios canales en un menú.

getCompany

Recupera la información configurada de la empresa para la instancia autenticada, incluidos el nombre de la empresa, los idiomas admitidos y la configuración de las funciones. Este método también establece el identificador de instancia interno (OPTIONS.tenant) como un efecto secundario, por lo que suele ser la primera llamada que se realiza después de construir un cliente.

Firma del método

getCompany(): Promise<CompanyResponse>

Valor que se muestra

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;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

Ejemplo de uso

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

getMenus

Este método se usa para enumerar todos los elementos de menú disponibles para la instancia. El campo MenuResponse.direct indica a los emisores si el resultado provino de una clave de acceso directo (direct.key: true) o de un acceso directo a nivel del usuario (direct.user: true). Ambos afectan la forma en que se deben presentar los menús.

Firma del método

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

Valor que se muestra

Muestra un objeto MenuResponse.

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

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

Recupera el tiempo de espera estimado (en segundos) para los canales de chat y llamada de voz de un menú determinado.

Firma del método

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

Valor que se muestra

Devuelve un objeto WaitTimeResponse o null.

Interfaces

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

Ejemplo de uso

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

Llamadas

Nombre	Descripción
createCall	Crea una llamada instantánea o programada.
loadCall	Obtén información de un ID de llamada determinado.
cancelCall	Cancela la llamada con el ID de llamada proporcionado.
getTimeSlots	Obtiene los horarios disponibles para las llamadas programadas de un menú determinado.
fetchTimeSlotAvailability	Verifica si hay horarios disponibles para un menú determinado.

createCall

Crea una llamada nueva para el menú determinado. Puede ser una llamada instantánea o programada, según si se proporciona el campo scheduled_at. El tipo de llamada (web_instant_call en comparación con web_scheduled_call) se determina automáticamente según la presencia de scheduled_at. reschedule_call_id se envía en el nivel superior de la solicitud, separado del cuerpo de la llamada. El menu_id en la respuesta se normaliza a partir del selected_menu.id de la API.

Firma del método

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

Valor que se muestra

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

Ejemplo de uso

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

loadCall

El método loadCall recupera información sobre una llamada específica, identificada por su ID.

Firma del método

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

Valor que se muestra

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

Cancela una llamada existente por su ID. Por lo general, se usa para cancelar una llamada programada que aún no se realizó.

Firma del método

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

Valor que se muestra

Devuelve 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, admite reprogramar una llamada existente con rescheduleCallId. La firma de cadena lang obsoleta sigue siendo compatible y se enruta al mismo extremo con solo lang propagado. Devuelve un array de cadenas de intervalos de tiempo.

Firma del método

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

Advertencia: La firma anterior getTimeSlots(menuId, lang?) dejó de estar disponible. Migra a la nueva firma basada en opciones que se mostró anteriormente. La firma anterior seguirá funcionando, pero es posible que se quite en una versión futura.

Valor que se muestra

Devuelve un array de cadenas (horarios).

Interfaces

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

Ejemplo de uso

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

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

Alcance

fetchTimeSlotAvailability solo se aplica a las citas de llamadas de voz programadas (devolución de llamada). No devuelve información sobre los canales de chat, correo electrónico o llamada instantánea. El menú proporcionado debe estar configurado para admitir llamadas de voz programadas, con un horario de atención definido y al menos un agente en cola para ese menú.

Casos de uso típicos:

• Renderizar de forma condicional un llamado a la acción "Programar una devolución de llamada" solo cuando haya horarios disponibles

• Ramificar a un flujo de desvío (p.ej., correo electrónico, mensaje fuera del horario de atención) cuando no hay horarios disponibles, sin pagar el costo de una llamada completa de getTimeSlots.

• Realizar una verificación previa de una acción de reprogramación antes de llamar a getTimeSlots con un rescheduleCallId

Firma del método

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

Valor que se muestra

Devuelve true si hay horarios disponibles; de lo contrario, devuelve false.

Ejemplo de uso

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

Chats

Nombre	Descripción
createChat	Crea un chat nuevo.
loadChat	Recupera el chat con el ID de chat proporcionado.
loadOngoingChat	Intenta cargar un chat en curso.
resumeChat	Reanuda un chat descartado con el ID de chat proporcionado.
finishChat	Establece el estado del chat actual como finalizado.
destroyChat	Llama a finishChat y destruye el chat actual.
fetchMessages	Recupera los mensajes anteriores y devuelve [] en caso de error.
sendTextMessage	Envía un mensaje de texto.
sendFileMessage	Envía un mensaje de archivo y devuelve -1 si se produce un error de carga.
sendPreviewMessage	Envía un mensaje de vista previa.
getChatDeflection	Obtiene la configuración de desvío de chat.
sendChatTranscripts	Envía la transcripción del chat a los correos electrónicos proporcionados.
downloadChatTranscript	Descarga la transcripción del chat.
getPdfStatus	Obtiene el estado del PDF de una transcripción.
getChatSurvey	Obtiene las preguntas de la encuesta del chat.
sendChatSurvey	Envía los comentarios de los usuarios de la encuesta.
sendChatRate	Envía comentarios de los usuarios sobre el chat.
escalateChat	Deriva un chat de un agente virtual a un agente humano.
trackChatEscalation	Hace un seguimiento del evento de derivación del chat.
trackChatEndUserEvent	Realiza un seguimiento de un evento de usuario final.
getChatHistory	Recupera los historiales de un chat determinado.

Verificación de chat

La función de registro le pide al consumidor que confirme que está listo antes de conectarse con un agente. En esta sección, se documentan los métodos del SDK web sin interfaz gráfica para implementar esa experiencia. Para saber qué es la confirmación de asistencia, cómo se habilita y configura (tiempo de espera, tiempo de espera, posición en la fila, comportamiento para volver a unirse) y los informes, consulta Confirmación de asistencia para Chat.

Nombre	Descripción
checkIn	Envía una señal al servidor para confirmar la presencia del usuario en la fila.
exitCheckIn	Quita al usuario de la fila de registro.
notifyCheckInState	Notifica al backend el estado de visibilidad del modal de confirmación de asistencia.
rejoinChat	Vuelve a colocar al usuario en la fila después de que no se confirma el registro.
trackCheckInEvent	Indica al backend cuándo la IU activó los eventos de registro.

checkIn

Envía un indicador de confirmación al servidor para indicar que el consumidor está presente y listo para conectarse con un agente durante el período de registro. Actualiza el check_in_status del chat de forma local después de que el servidor lo confirma. Se usa en respuesta al evento chat.checkInRequested.

Firma del método

checkIn(): Promise<CheckInResponse>

Valor que se muestra

Muestra un objeto CheckInResponse.

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

Ejemplo de uso

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

exitCheckIn

Indica al servidor que el consumidor decidió abandonar la fila de registro. Actualiza check_in_status de forma local. Después de llamar a este método, el consumidor no recibirá una conexión de agente para el ciclo de registro actual.

Firma del método

exitCheckIn(): Promise<CheckInResponse>

Valor que se muestra

Muestra un objeto CheckInResponse.

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

Ejemplo de uso

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

notifyCheckInState

Informa al servidor sobre el estado de visibilidad actual del modal de registro, es decir, si el widget está minimizado o la pestaña del navegador está inactiva. El servidor usa esta información para tomar decisiones sobre el momento de la verificación. Se debe llamar cada vez que cambie la visibilidad del widget o el enfoque de la pestaña mientras el evento chat.checkInRequested esté activo.

Firma del método

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

Interfaces

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

Ejemplo de uso

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

rejoinChat

Vuelve a colocar al consumidor en la fila después de que no confirmó un registro dentro del tiempo asignado. Actualiza check_in_status de forma local. Úsala en respuesta al evento chat.checkInTimedOut si el consumidor aún quiere conectarse.

Firma del método

rejoinChat(): Promise<CheckInResponse>

Valor de retorno: Devuelve un objeto CheckInResponse.

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

Ejemplo de uso

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

trackCheckInEvent

Notifica al servidor que se mostró la ventana modal de registro al consumidor. Llama a esta función una vez, inmediatamente después de presentar la IU de registro en respuesta a chat.checkInRequested. El servidor lo usa para realizar análisis operativos sobre las tasas de presentación de confirmaciones de llegada. La llamada se espera de forma interna y devuelve un objeto Promise<void> que puede rechazar, por lo que debes unirlo en try/catch (como se hace en el siguiente ejemplo).

Firma del método

trackCheckInEvent(): Promise<void>

Ejemplo de uso

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

getMessageAttachment

Recupera un archivo adjunto apto asociado con un mensaje de chat específico. Solo recupera si el mensaje lo envió un usuario que no es final ($userType !== 'end_user') y es de un tipo de archivo adjunto compatible (foto, video, audio, documento). Muestra null para cualquier mensaje que no cumpla con ambas condiciones, no solo para los mensajes sin un media_id. Guarda el archivo recuperado en la caché de contenido multimedia local del chat después de la recuperación.

Firma del método

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

Valor que se muestra

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

Ejemplo de uso

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

createChat

Crea una nueva sesión de chat para el menú determinado. De manera opcional, puedes especificar el idioma, un mensaje de saludo, un ID de activador, un ID de ticket y datos personalizados para enviar con el chat.

Después de la llamada a la API inicial, el método sondea el servidor hasta que un provider_channel_id esté disponible o el chat se cancele o finalice. Si un canal de proveedor está disponible, el método inicia la conexión con el proveedor en tiempo real. Es posible que la conexión aún se esté completando cuando se resuelva la promesa. Escucha el evento chat.connectedMessages para saber cuándo se completaron la conexión y la recuperación inicial de mensajes.

Firma del método

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

Valor que se muestra

Devuelve una instancia de Chat.

Advertencia: Este método arroja un error de inmediato si ya hay un chat en curso. Verifica si hay una sesión existente antes de llamar.

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

loadChat

Recupera una sesión de chat existente por su ID.

Si el chat cargado ya no está en curso, el método borra el ID de chat almacenado y el nonce de navegación conjunta del almacenamiento local. También lo hace en caso de error, por lo que los emisores no necesitan controlar la limpieza del almacenamiento de forma manual después de una carga con errores.

Firma del método

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

Valor que se muestra

Devuelve una instancia de Chat.

Advertencia: En caso de error, este método borra los IDs de sesión de chat y navegación conjunta almacenados en el almacenamiento local antes de volver a lanzar la excepción. Cualquier referencia de sesión almacenada se invalida después de una llamada fallida.

Ejemplo de uso

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

loadOngoingChat

Intenta cargar la sesión de chat en curso actual, si existe. Devuelve null si no se encuentra ningún 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 hay un chat en curso. Se limpiarán los valores de almacenamiento si el chat no está en curso.

Advertencia: En caso de error, este método borra el ID de chat almacenado del almacenamiento local antes de volver a arrojarlo. Cualquier referencia de sesión almacenada se invalida después de una llamada fallida.

Ejemplo de uso

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

resumeChat

Reanuda una sesión de chat descartada anteriormente por su ID, lo que permite que el consumidor continúe la conversación.

Si el cliente ya tiene una referencia a un chat con el mismo ID, el método se interrumpe: aplica un parche al estado para que sea queued en la instancia existente en lugar de recuperar una nueva. Si los IDs no coinciden, se crea y registra una nueva instancia de Chat.

Firma del método

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

Valor que se muestra

Devuelve una instancia de Chat.

Ejemplo de uso

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

finishChat

Establece el estado de la sesión de chat actual como finalizada. Esto finaliza el chat desde el lado del consumidor.

Si el chat está conectado al proveedor en tiempo real y en un estado finalizado después de PATCH, el método también se desconecta del proveedor. Los emisores no necesitan llamar a destroyChat si el único objetivo es finalizar el chat de forma correcta.

Firma del método

finishChat(): Promise<void>

Ejemplo de uso

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

destroyChat

Finaliza y destruye la sesión de chat actual, lo que limpia todo el estado interno. Esto llama a finishChat de forma interna y, luego, desglosa la instancia de chat. Antes de finalizar el chat, el método lo silencia (suprime los eventos entrantes en tiempo real) para evitar que se procesen mensajes durante el cierre. Borra el ID de seguimiento interno después de que se destruye el chat.

Firma del método

destroyChat(): Promise<void>

Ejemplo de uso

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

fetchMessages

Recupera el historial de mensajes de la sesión de chat actual del proveedor en tiempo real. Se debe llamar después de que se conecte el chat. Si se llama antes de que se conecte el chat, devuelve un array vacío en lugar de arrojar un error. Recupera automáticamente las URLs de los documentos para cualquier mensaje de tipo document y las combina en la respuesta. Para los mensajes de tipo server_message, recupera el contenido del mensaje del agente virtual de la tarea y lo formatea intercalado. Devuelve un array vacío en caso de error en lugar de arrojarlo.

Firma del método

fetchMessages(): Promise<MessageResponse[]>

Valor que se muestra

Devuelve un array de MessageResponse. Muestra un array vacío en caso de error.

Advertencia: Este método no arroja un error en caso de falla. Devuelve un array vacío ([]) si falla la recuperación de mensajes. No dependas de try/catch; en su lugar, verifica el valor que se muestra.

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

Ejemplo de uso

const messages = await client.fetchMessages()

sendTextMessage

Envía un mensaje de texto en la sesión de chat actual.

El método limpia el contenido sin procesar antes de enviarlo y devuelve un resultado anticipado (sin operación) si el resultado está vacío. Si el chat se encuentra en un flujo de agente virtual de tareas (inTask), el mensaje se enruta a través del extremo del agente virtual de tareas en lugar del canal normal. Si la ocultación del servidor está habilitada, el mensaje se envía con un extremo del servidor en lugar de hacerlo directamente a través del proveedor en tiempo real.

Firma del método

sendTextMessage(rawContent: string): Promise<void>

Ejemplo de uso

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

sendFileMessage

Sube un archivo a la sesión de chat actual a través de un proceso de tres pasos: obtener una URL de almacenamiento en la nube firmada previamente del servidor, subir el archivo directamente a esa URL y, luego, confirmar la carga de vuelta al servidor. La ruta de carga se determina automáticamente a partir del tipo de MIME del archivo: las imágenes se envían como mensajes con foto y los videos como mensajes de video; otros tipos de archivos se enrutan según su tipo de MIME. Muestra el ID del mensaje si se realiza correctamente o -1 si falla.

Firma del método

sendFileMessage(file: File): Promise<number>

Valor que se muestra

Devuelve el ID del mensaje o -1 si la carga falló. Sin embargo, el envío de mensajes posterior aún puede rechazarse (por ejemplo, ChatEndedError), por lo que debes unir la llamada en try/catch, además de verificar -1.

Ejemplo de uso

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

Envía un mensaje de vista previa en la sesión de chat actual. Los mensajes de vista previa se suelen usar para mostrarle al agente lo que el consumidor está escribiendo antes de que se envíe el mensaje. Si tanto redaction_enabled como agent_incoming_ha_enabled son verdaderos en el estado del chat, la vista previa se envía a través de un extremo del servidor (POST /chats/{id}/redact_messages) en lugar del canal del proveedor en tiempo real.

Firma del método

sendPreviewMessage(content: string): Promise<void>

Ejemplo de uso

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

getChatDeflection

Recupera la configuración de desvío de chat para la sesión de chat actual, incluido si el desvío está habilitado, el umbral de tiempo de espera y las opciones de desvío disponibles.

Devuelve null si el desvío no está habilitado para el chat (el campo enabled de la respuesta del servidor es falso). Los emisores deben realizar una verificación de nulos antes de leer la respuesta.

Firma del método

getChatDeflection(): Promise<ChatDeflectionResponse | null>

Valor que se muestra

Devuelve un objeto ChatDeflectionResponse o null si el desvío no está habilitado para el chat.

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 la transcripción del chat actual a las direcciones de correo electrónico especificadas.

Firma del método

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

Ejemplo de uso

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

downloadChatTranscript

Inicia la descarga de la transcripción del chat actual como un archivo PDF. Devuelve un objeto de transcripción que se puede usar con getPdfStatus para hacer un seguimiento del progreso de la generación.

Firma del método

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

Valor que se muestra

Devuelve el objeto de transcripción.

Interfaces

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

Ejemplo de uso

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

getPdfStatus

Verifica el estado de generación de un PDF de transcripción de chat solicitado anteriormente. Usa la chat_transcript_id que muestra downloadChatTranscript para sondear la finalización.

Firma del método

getPdfStatus(id: number): Promise<RequestReturn>

Valor que se muestra

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 = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

Recupera las preguntas de la encuesta posterior al chat configuradas para la sesión de chat actual. La encuesta se presenta a los consumidores después de que finaliza un chat.

Firma del método

getChatSurvey(): Promise<ChatSurveyResponse | null>

Valor que se muestra

Devuelve un objeto ChatSurveyResponse o un valor nulo.

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

sendChatSurvey

Envía las respuestas del consumidor a la encuesta posterior al chat. Cada respuesta se identifica con el ID de la pregunta.

Firma del método

sendChatSurvey(answers: SurveyAnswers): Promise<void>

Advertencia: Este método arroja un error de inmediato si el tipo de comentarios del chat no es 'survey'. Los emisores deben verificar chat.feedbackType === 'survey' antes de llamar o controlar el error.

Interfaces

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

Ejemplo de uso

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

sendChatRate

Envía la calificación del consumidor y los comentarios opcionales de la sesión de chat. Se usa cuando el tipo de comentarios posterior al chat es una calificación en lugar de una encuesta completa.

Firma del método

sendChatRate(data: RateRequest): Promise<void>

Advertencia: Este método arroja un error de inmediato si el tipo de comentarios del chat no es 'rate'. Los emisores deben verificar chat.feedbackType === 'rate' antes de llamar o controlar el error.

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

Deriva el chat actual de un agente virtual a un agente humano.

Firma del método

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

Interfaces

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

Ejemplo de uso

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

Realiza un seguimiento de un evento de derivación de chat y registra el ID de derivación y el canal al que se derivó.

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

Realiza un seguimiento de un evento personalizado del usuario final durante la sesión de chat, que se puede usar para analizar o activar flujos de trabajo de backend. Si el objeto data no incluye end_user_name y hay un nombre disponible en el perfil de usuario autenticado, se propaga automáticamente antes de que se envíe la solicitud.

Firma del método

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

Valor que se muestra

No devuelve nada.

Interfaces

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

Ejemplo de uso

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

Recupera el historial de chat anterior del consumidor, incluido el contenido y los metadatos de los mensajes. Los resultados se paginan. La página 1 devuelve hasta 2 chats; las páginas posteriores devuelven 1 chat cada una. Esta paginación asimétrica es intencional y permite que la primera llamada cargue previamente el contexto del historial adyacente.

Firma del método

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

Valor que se muestra

Devuelve un objeto ChatHistoryResponse o 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;
 }
}

Ejemplo de uso

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

Correos electrónicos

Nombre	Descripción
createEmail	Envía un correo electrónico al canal de correo electrónico de un ID de menú determinado.
getProhibitedFileTypes	Obtén los tipos de archivos prohibidos para los archivos adjuntos de correo electrónico.

createEmail

Envía un mensaje de correo electrónico al canal de correo electrónico asociado con el menú determinado. El consumidor puede incluir un nombre, una dirección de correo electrónico, el cuerpo del mensaje y archivos adjuntos opcionales.

Firma del método

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

Valor que se muestra

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

Recupera la lista de tipos de archivos que no se permiten como archivos adjuntos de correo electrónico, según lo configurado por el administrador.

Firma del método

getProhibitedFileTypes(): Promise<FileTypeItem[]>

Valor que se muestra

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 pantalla

Nombre	Descripción
createCobrowseCode	Genera un código de navegación conjunta.
startCobrowse	Solicita una sesión de navegación conjunta.
restoreCobrowseSession	Restablece una sesión de navegación conjunta después de que se vuelve a abrir la ventana del navegador.

createCobrowseCode

Genera un código de sesión de navegación conjunta (compartir pantalla) único que se puede compartir con un agente para iniciar una sesión. Inicializa el cliente de navegación conjunta si aún no se inicializó. Reutiliza cualquier nonce existente del almacenamiento en lugar de generar uno nuevo en cada llamada, de modo que se pueda recuperar el mismo código de sesión en todas las cargas de página.

Firma del método

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

Valor que se muestra

Devuelve una cadena de código de navegación conjunta o una cadena vacía ('') en caso de error.

Advertencia: Este método no arroja un error en caso de falla. No dependas de try/catch; en su lugar, verifica el valor que se muestra.

Ejemplo de uso

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

startCobrowse

Solicita el inicio de una sesión de navegación conjunta (compartir pantalla) desde el lado del usuario final durante un chat activo.

Firma del método

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

Advertencia: Este método arroja un error si el chat actual no se creó con cobrowsable: true. Los llamadores pueden verificar chat.cobrowsable antes de llamar para evitar la excepción.

Ejemplo de uso

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

restoreCobrowseSession

Intenta restablecer una sesión de navegación conjunta que estaba activa antes de que se volviera a abrir la ventana del navegador o se volviera a cargar el widget.

Firma del método

restoreCobrowseSession(): Promise<void>

Valor que se muestra

Muestra Promise<void>. Este método no realiza ninguna operación (se muestra de inmediato sin error) si la navegación conjunta no está habilitada en las opciones del cliente o si no existe una sesión de navegación conjunta anterior en el almacenamiento.

Advertencia: Este método no arroja excepciones. Si se produce un error durante la restauración, el método registra el error de forma interna, borra la sesión de navegación conjunta almacenada y, luego, se muestra de forma limpia. Los emisores no necesitan try/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()

Agente virtual posterior a la sesión

Nombre	Descripción
updatePostSession	Establece el estado posterior a la sesión del chat en curso.

updatePostSession

Este método se usa para actualizar el estado del agente virtual posterior a la sesión para el chat en curso.

• Actualiza el estado del agente virtual posterior a la sesión para el chat en curso. Usa esto para indicar la preparación, el progreso o la finalización de un flujo de agente virtual posterior a la sesión.

• Se muestra de inmediato como una operación no-op si postSessionStatus es FINISHED o WAITING, ya que esas transiciones se controlan de forma interna.

• Tiene una lógica de reintento interna específica para el estado IN_PROGRESS en una respuesta 400, por lo que los emisores 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: Es la sesión posterior que se requiere después de un chat.

• post_session_opt_in_required: Indica si está habilitada la aceptación.

• post_session_transfer_status: Es uno de los valores de PostSessionStatus.

Depuración

Nombre	Descripción
getLogs	Recupera los registros de depuración internos del SDK.
printLogs	Imprime los registros de depuración internos en la consola del navegador.

getLogs

Recupera los registros de depuración internos que recopila el SDK, incluidos los registros a nivel de puente y de raíz. Es útil para solucionar problemas de integración.

Firma del método

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

Valor que se muestra

Devuelve un objeto que contiene dos arrays de LogHistoryData.

Interfaces

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

Nota: Los registros de puente se recuperan primero de forma interna, ya que la recuperación en sí produce una entrada de registro raíz. Como resultado, rootLogs captura de forma intencional ese registro final.

Nivel de detalle

Cada entrada LogHistoryData captura un solo evento de registro:

• date: Es la marca de tiempo ISO 8601 del evento.

• channel: Es el módulo del SDK que lo emitió (p.ej., cliente de nivel superior, capa de chat, capa de navegación conjunta o proveedor en tiempo real).

• level: Gravedad del registro: debug, info, warn o error.

• args: Son los argumentos sin procesar que captura la llamada de registro.

Entrada de ejemplo:

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

El conjunto exacto de canales y el contenido de los mensajes pueden evolucionar entre las versiones del SDK. Trata los registros como una ayuda para la depuración, no como un objetivo de análisis estable; no compiles una lógica de producción que dependa de nombres de canales o cadenas de mensajes específicos.

Alcance y uso recomendado

getLogs devuelve registros internos del SDK destinados a ayudar a diagnosticar problemas de integración con el SDK web sin interfaz gráfica. Su caso de uso principal es el diagnóstico de asistencia: cuando un usuario final informa un problema, tu aplicación puede capturar el resultado de getLogs y adjuntarlo al ticket de asistencia enviado a CCAI Platform.

Los registros que se devuelven no incluyen lo siguiente:

• La telemetría de la aplicación, los eventos empresariales o la navegación del usuario de tu página de host.

• Fallas de red que el navegador no muestra al SDK (p. ej., CORS, contenido mixto o errores de certificado)

• Seguimientos de solicitudes del servidor o detalles del backend más allá del estado HTTP que se devuelve al SDK

getLogs no reemplaza tus propias herramientas de observabilidad. Te recomendamos vincular el SDK con lo siguiente:

• Un rastreador de errores o RUM del lado del navegador (Sentry, Datadog Browser RUM, New Relic Browser o equivalente)

• Registro del servidor en tu extremo de autenticación (la devolución de llamada authenticate que llama el SDK)

• Objetos de escucha a nivel de la aplicación en chat.disconnected, chat.timeout y chat.ended si necesitas reenviar indicadores del ciclo de vida del chat a tu propia canalización de telemetría.

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 da formato al resultado.

Firma del método

printLogs(): Promise<void>

Ejemplo de uso

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

Varios

Nombre	Descripción
runTrigger	Verifica los activadores proactivos para ver si hay alguno que deba activarse.
getAfterHourMessage	Obtén el mensaje para el desvío fuera de horario.

runTrigger

Itera sobre los activadores proactivos configurados y, luego, invoca la devolución de llamada proporcionada para aquellos cuyas condiciones se cumplan (palabras clave de URL, recuento de visitas a la página, tiempo de permanencia y tipo de visitante).

Firma del método

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

Ejemplo de uso

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

getAfterHourMessage

Devuelve el mensaje de desvío configurado para mostrarlo cuando el canal solicitado está fuera del horario de atención.

Firma del método

La firma del método es la siguiente:

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

Valor que se muestra

Devuelve una cadena que contiene un mensaje configurado.

Ejemplo de uso

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