Centro de ayuda
Chat API

Chat API

Última actualización:

Información general sobre Chat API

La API del widget te permite controlar el widget de chat mediante programación y registrar callbacks para eventos de chat.

¿Buscas la API REST? Este artículo cubre la API JavaScript del widget en el navegador (window.aichatbotApi) para páginas donde el widget de ChatLab está integrado. Para la API REST de servidor a servidor utilizada para conversar con bots desde tu backend o gestionar bots mediante programación, consulta los artículos de Bot Talk API y Management API.

Primeros pasos

La API del chatbot no está disponible de inmediato al cargar tu página - el script debe cargarse e inicializarse primero. Debes usar window.aichatbotCallback.onSessionActivated como mecanismo de inicialización para acceder a la API de forma segura.

Usa la clave pública del widget de Deploy (Implementación) como YOUR_API_KEY, nunca una clave secreta de ck_ o mk_. Mantén el ID del proveedor y el host del script de tu propio fragmento de Deploy. Coloca la configuración del callback antes de esa etiqueta de script:

<script>
let registeredChatbot;
window.aichatbotCallback = {
    onSessionActivated() {
        var chatbot = window.aichatbotApi.getChatbotApi('YOUR_API_KEY');

        if (registeredChatbot === chatbot) return;
        registeredChatbot = chatbot;

        chatbot.addCallback('onUserMessage', function(message) {
            console.log('User said:', message);
        });

        chatbot.addCallback('onChatbotMessage', function(message) {
            console.log('Bot replied:', message);
        });

        // Send only when your application intends to start a real chat:
        // chatbot.sendMessage('Hello from the API!');
    }
};
</script>
<script>window.aichatbotApiKey="YOUR_API_KEY";</script>
<script src="https://script.chatlab.com/aichatbot.js" defer></script>

onSessionActivated se activa cuando hay una sesión disponible, incluidas las sesiones restauradas. Según la configuración de la implementación y de la pantalla de bienvenida, esto no es necesariamente al hacer el primer clic para abrir el widget. Puede activarse de nuevo; registra los callbacks una vez por objeto de API para evitar controladores duplicados. Dentro de él, se garantiza que el objeto de API existe y la sesión está activa, por lo que puedes llamar con seguridad a sendMessage(), updateClientContext() y registrar callbacks de eventos.

Importante: No llames a window.aichatbotApi.getChatbotApi() directamente en el script de tu página sin esperar - el objeto de API no existe hasta que el script de ChatLab se haya cargado e inicializado.

Consejo: Si solo necesitas controlar el widget (mostrar/ocultar/alternar) y no necesitas una sesión activa, escucha en su lugar el evento del DOM aichatbotReady:

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
    chatbot.showChat();
});

Métodos

Método Descripción
showChat() Abrir el widget de chat
hideChat() Cerrar el widget de chat
toggleChat() Alternar la visibilidad del widget
sendMessage(text) Enviar un mensaje de forma programática
updateClientContext(data) Actualizar el contexto del usuario (ver más abajo)
setLanguage(code) Cambiar el widget a un idioma (solo bots multilingües, ver más abajo)
getLanguage() Devolver el idioma que el widget está usando actualmente
getAvailableLanguages() Devolver la lista de idiomas que ofrece el bot
addCallback(name, fn) Registrar un callback de evento

Nota: sendMessage y updateClientContext requieren una sesión activa. Usa el patrón de inicialización onSessionActivated mostrado en Primeros pasos.

Callbacks

Registra callbacks de eventos dentro de tu manejador onSessionActivated (consulta Primeros pasos):

chatbot.addCallback('onUserMessage', function(message) {
    console.log('User said:', message);
});

chatbot.addCallback('onChatbotMessage', function(message) {
    console.log('Bot replied:', message);
});

chatbot.addCallback('onProductClick', function(productIdOrLink) {
    console.log('Product clicked:', productIdOrLink);
});

chatbot.addCallback('onLeadCollectionFormSubmit', function(data) {
    console.log('Lead captured:', data.email);
});

chatbot.addCallback('onContactFormSubmit', function(data) {
    console.log('Support request from:', data.email);
});

chatbot.addCallback('onLiveChatFormSubmit', function(data) {
    console.log('Live chat started:', data.name);
});

Callbacks disponibles

Callback Datos Descripción
onSessionActivated - La sesión de chat está lista
onUserMessage string El usuario envió un mensaje
onChatbotMessage string El bot respondió con un mensaje
onProductClick Carga útil de producto/enlace de la tarjeta renderizada El usuario hizo clic en el enlace de un producto; inspecciona la carga útil para tu tipo de tarjeta
onLeadCollectionFormSubmit {email, phone, name} Se envió el formulario de captación de leads
onContactFormSubmit {email, message} Se envió el formulario de contacto/soporte
onLiveChatFormSubmit {name, email} Se envió el formulario de chat en vivo; no confirma que un agente se haya unido
onCustomFormSubmit {formId, values} Se envió un formulario personalizado; los datos de archivos subidos no se incluyen en este callback

Los callbacks de formularios notifican un envío desde el navegador, no una persistencia confirmada ni una entrega correcta. Para un procesamiento confirmado en el backend, usa Webhooks. Las cargas útiles de los callbacks pueden contener datos personales; no las reenvíes por completo a herramientas de analítica ni a registros públicos.

Callbacks de eventos heredados

El objeto window.aichatbotCallback también admite onUserMessage y onChatbotMessage como propiedades directas. Usa addCallback() para listeners modulares sin sustituir el objeto global:

window.aichatbotCallback = {
    onUserMessage(message) { ... },
    onChatbotMessage(message) { ... }
};

Nota: window.aichatbotCallback.onSessionActivated no está obsoleto; es el mecanismo de inicialización recomendado para poner en marcha la Chat API (consulta Primeros pasos).

Implementación mediante iframe

Al usar la implementación mediante iframe, utiliza postMessage para comunicarte con el chatbot:

Envío de comandos

// Give the ChatLab iframe from Deploy this unique id.
const chatbotIframe = document.getElementById('chatlab-frame');
const chatbotOrigin = new URL(chatbotIframe.src, window.location.href).origin;
// Run show/hide/language commands after the iframe loads.
// Wait for onSessionActivated before sendMessage or updateClientContext.

// Show chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, chatbotOrigin);

// Hide chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, chatbotOrigin);

// Send message
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, chatbotOrigin);

// Update client context
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, chatbotOrigin);

// Switch language (multi-language bots only)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, chatbotOrigin);

Recepción de callbacks

window.addEventListener('message', (event) => {
    if (event.origin !== chatbotOrigin || event.source !== chatbotIframe.contentWindow) return;
    if (event.data?.type !== 'aichatbot-callback') return;

    const { apiKey, callback, data } = event.data;

    switch (callback) {
        case 'onSessionActivated':
            console.log('Session ready');
            break;
        case 'onUserMessage':
            console.log('User said:', data);
            break;
        case 'onChatbotMessage':
            console.log('Bot replied:', data);
            break;
        case 'onProductClick':
            console.log('Product clicked:', data);
            break;
        case 'onLeadCollectionFormSubmit':
            console.log('Lead captured:', data);
            break;
        case 'onContactFormSubmit':
            console.log('Contact form:', data);
            break;
        case 'onLiveChatFormSubmit':
            console.log('Live chat started:', data);
            break;
    }
});

Actualizar el contexto del cliente

La función updateClientContext permite actualizar el contexto del cliente durante una sesión activa:

chatbot.updateClientContext({
    clientId: "unique-client-identifier",     // Required
    clientName: "John",                       // Optional
    clientEmail: "john@doe.com",              // Optional
    clientPhone: "555-444-333",               // Optional
    clientSecurityToken: "your-token",        // Optional
    clientHostContext: {                      // Optional
        param1: "value1",
        param2: "value2"
    }
});

Parámetros:

  • clientId (obligatorio): identificador único para el cliente
  • clientName, clientEmail, clientPhone (opcional): datos del cliente que se muestran en las conversaciones
  • clientSecurityToken (opcional): un token reenviado como contexto para tu integración personalizada. Tu propia API debe validar su autenticidad, caducidad y autorización.
  • clientHostContext (opcional): parámetros de contexto adicionales accesibles en acciones de API personalizadas

Los identificadores y el contexto proporcionados por el navegador no son una prueba de identidad. No incluyas secretos para toda la cuenta en el JavaScript de la página y no concedas acceso únicamente porque un clientId o un correo electrónico proporcionados coincidan con un registro.

Uso en llamadas a la API:

Los atributos de contexto se pueden usar en llamadas a funciones de la API configurando el parámetro de la API como tipo "Context" (Contexto):

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Parámetros de contexto del host personalizados con el prefijo client, p. ej., clientparam1, clientparam2

Idioma

Estos métodos funcionan solo en chatbots multilingües. En un bot de un solo idioma, el widget no tiene una capa de idioma que cambiar, por lo que setLanguage() no hace nada y getAvailableLanguages() devuelve únicamente el idioma propio del bot. Activa primero la compatibilidad multilingüe en Settings > Languages (Ajustes > Idiomas) - consulta Chatbots multilingües.

Usa setLanguage() cuando tu página exista en varios idiomas y quieras que el chat se abra en el que el visitante está leyendo, en lugar de aquel en el que esté configurado su navegador:

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);

    chatbot.setLanguage(document.documentElement.lang);  // e.g. "de"

    console.log(chatbot.getLanguage());            // "de"
    console.log(chatbot.getAvailableLanguages());   // ["en", "de", "fr", ...]
});

También puedes declarar el idioma de la página antes de que se cargue el script, lo que evita que se muestre brevemente el idioma incorrecto:

<script>window.aichatbotLanguage = "de";</script>

Qué idioma tiene prioridad. El widget determina el idioma en este orden:

  1. El idioma que el propio visitante haya elegido en el menú de idioma del widget.
  2. El idioma de la página, a partir de setLanguage() o window.aichatbotLanguage.
  3. El idioma del navegador del visitante.
  4. El idioma base del chatbot.

La elección del propio visitante se recuerda para visitas posteriores, pero deja de aplicarse en cuanto cambia el idioma de la página - de modo que tu selector de idioma siempre tiene prioridad sobre una elección desactualizada. Los códigos son ISO 639-1 (en, de, pl); un código regional como de-AT recurre a de. Si el bot no ofrece un idioma, este se ignora.

Cambiar el idioma no finaliza la conversación ni borra la transcripción.

Artículos relacionados

Buscar en todos los artículosPregunta al agente