Centro de Ajuda
Chat API

Chat API

Última atualização:

Visão geral da Chat API

Esta funcionalidade está disponível apenas em planos selecionados. Permite controlar o widget de chat programaticamente e registar callbacks para eventos de chat.

À procura da API REST? Este artigo aborda a API JavaScript do widget no navegador (window.aichatbotApi) para páginas onde o widget do ChatLab está incorporado. Para a API REST servidor a servidor utilizada para conversar com bots a partir do seu backend ou gerir bots programaticamente, consulte os artigos sobre a Bot Talk API e a Management API.

Primeiros passos

A API do chatbot não fica disponível imediatamente quando a sua página carrega - o script tem de carregar e inicializar primeiro. Deve utilizar window.aichatbotCallback.onSessionActivated como mecanismo de arranque para aceder à API com segurança.

Coloque isto antes da tag de script do ChatLab:

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

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

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

        chatbot.sendMessage('Hello from the API!');
    }
};
</script>
<script>window.aichatbotApiKey="YOUR_API_KEY";</script>
<script src="https://script.chatlab.com/aichatbot.js" defer></script>

O evento onSessionActivated é acionado quando a sessão de chat é criada (ou seja, quando o utilizador abre o widget). Dentro dele, a existência do objeto da API é garantida e a sessão está ativa, pelo que pode chamar sendMessage(), updateClientContext() e registar callbacks de eventos em segurança.

Importante: Não chame window.aichatbotApi.getChatbotApi() diretamente no script da sua página sem aguardar - o objeto da API não existe até que o script do ChatLab tenha carregado e inicializado.

Dica: Se apenas precisa de controlar o widget (mostrar/ocultar/alternar) e não precisa de uma sessão ativa, intercete antes o evento do DOM aichatbotReady:

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

Métodos

Método Descrição
showChat() Abrir o widget de chat
hideChat() Fechar o widget de chat
toggleChat() Alternar a visibilidade do widget
sendMessage(text) Enviar uma mensagem programaticamente
updateClientContext(data) Atualizar o contexto do utilizador (ver abaixo)
setLanguage(code) Mudar o widget para um idioma (apenas bots multilíngues, ver abaixo)
getLanguage() Devolver o idioma que o widget está a utilizar atualmente
getAvailableLanguages() Devolver a lista de idiomas disponíveis no bot
addCallback(name, fn) Registar um callback de evento

Nota: Os métodos sendMessage e updateClientContext requerem uma sessão ativa. Utilize o padrão de inicialização onSessionActivated apresentado em Primeiros passos.

Callbacks

Registe callbacks de eventos dentro do seu manipulador onSessionActivated (consulte Primeiros passos):

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 disponíveis

Callback Dados Descrição
onSessionActivated - A sessão de chat está pronta
onUserMessage string O utilizador enviou uma mensagem
onChatbotMessage string O bot respondeu com uma mensagem
onProductClick string (ID do produto ou link) O utilizador clicou num produto (requer Offer Cards ativado)
onLeadCollectionFormSubmit {email, phone, name} O formulário de recolha de leads foi submetido
onContactFormSubmit {email, message} O formulário de contacto/suporte foi submetido
onLiveChatFormSubmit {name, email} O formulário de Live Chat foi submetido

Callbacks de eventos legados (descontinuados)

O objeto window.aichatbotCallback também suporta onUserMessage e onChatbotMessage como propriedades diretas. Este formato está descontinuado - utilize addCallback() para aceder a todos os tipos de callback:

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

Nota: O método window.aichatbotCallback.onSessionActivated não está descontinuado - é o mecanismo de arranque recomendado para inicializar a Chat API (consulte Primeiros passos).

Implementação em Iframe

Ao utilizar uma implementação em iframe, utilize postMessage para comunicar com o chatbot:

Enviar comandos

const chatbotIframe = document.querySelector('iframe');

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

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

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

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

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

Receber callbacks

window.addEventListener('message', (event) => {
    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;
    }
});

Atualizar o contexto do cliente

A função updateClientContext permite atualizar o contexto do cliente durante uma sessão ativa:

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 (obrigatório): Identificador único para o cliente
  • clientName, clientEmail, clientPhone (opcional): Dados do cliente apresentados nas conversas
  • clientSecurityToken (opcional): Token de segurança para autorização na API
  • clientHostContext (opcional): Parâmetros de contexto adicionais acessíveis em ações personalizadas da API

Utilização em chamadas de API:

Os atributos de contexto podem ser utilizados em chamadas de funções da API configurando o parâmetro da API com o tipo "Context":

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Parâmetros personalizados de contexto do anfitrião com o prefixo client, por exemplo, clientparam1, clientparam2

Idioma

Estes métodos funcionam apenas em chatbots multilíngues. Num bot de idioma único, o widget não tem camada de idioma para alternar, pelo que setLanguage() não faz nada e getAvailableLanguages() devolve apenas o idioma do próprio bot. Ative primeiro o suporte multilíngue em Settings > Languages (Definições > Idiomas) - consulte Chatbots multilíngues.

Utilize setLanguage() quando a sua página existir em vários idiomas e pretender que o chat abra no idioma que o visitante está a ler, em vez daquele em que o navegador está configurado:

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", ...]
});

Também pode declarar o idioma da página antes de o script carregar, o que evita que o idioma incorreto pisque brevemente no ecrã:

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

Que idioma prevalece. O widget determina o idioma por esta ordem:

  1. Um idioma escolhido diretamente pelo visitante no menu de idiomas do próprio widget.
  2. O idioma da página, proveniente de setLanguage() ou window.aichatbotLanguage.
  3. O idioma do navegador do visitante.
  4. O idioma base do chatbot.

A escolha do próprio visitante é memorizada para visitas futuras, mas deixa de ser aplicada assim que o idioma da página é alterado - desta forma, o seu seletor de idiomas prevalece sempre sobre uma escolha desatualizada. Os códigos seguem a norma ISO 639-1 (en, de, pl); um código regional como de-AT reverte para de. Um idioma que o bot não disponibilize é ignorado.

Mudar o idioma não encerra a conversa nem limpa a transcrição.

Artigos relacionados

Pesquisar em todos os artigosPergunte ao agente