Centro de Ajuda
Chat API

Chat API

Última atualização:

Visão geral da Chat API

A API do widget permite controlar o widget de chat por programação e registar callbacks para eventos de chat.

Procura a 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 de servidor para servidor utilizada para conversar com bots a partir do seu backend ou gerir bots por programação, 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 página é carregada - o script tem de carregar e inicializar primeiro. Deve utilizar window.aichatbotCallback.onSessionActivated como mecanismo de arranque (bootstrap) para aceder à API em segurança.

Utilize a chave pública do widget de Deploy (Implementar) como YOUR_API_KEY, nunca uma chave secreta ck_ ou mk_. Mantenha o ID de fornecedor e o host do script do seu próprio fragmento de Deploy. Coloque a configuração do callback antes dessa tag 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>

O evento onSessionActivated é acionado quando uma sessão fica disponível, incluindo sessões restauradas. Dependendo da implementação e das definições do ecrã de boas-vindas, este momento não coincide necessariamente com o primeiro clique de abertura do widget. Pode ser acionado novamente; registe os callbacks apenas uma vez por objeto de API para evitar handlers duplicados. No seu interior, é garantido que o objeto da API existe e que a sessão está ativa, pelo que pode chamar sendMessage(), updateClientContext() e registar callbacks de eventos com total 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 sido carregado e inicializado.

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

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

Métodos

Método Descrição
showChat() Abre o widget de chat
hideChat() Fecha o widget de chat
toggleChat() Alterna a visibilidade do widget
sendMessage(text) Envia uma mensagem por programação
updateClientContext(data) Atualiza o contexto do utilizador (ver abaixo)
setLanguage(code) Muda o idioma do widget (apenas bots multilíngues, ver abaixo)
getLanguage() Devolve o idioma atualmente em utilização pelo widget
getAvailableLanguages() Devolve a lista de idiomas disponíveis no bot
addCallback(name, fn) Regista um callback de evento

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

Callbacks

Registe os callbacks de eventos dentro do seu handler onSessionActivated (consulte a secção 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 Payload de produto/ligação do cartão composto O utilizador clicou numa ligação de produto; inspecione o payload para o seu tipo de cartão
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; não confirma a entrada de um operador
onCustomFormSubmit {formId, values} O formulário personalizado foi submetido; os dados dos ficheiros carregados não são incluídos neste callback

Os callbacks de formulário reportam uma submissão no lado do navegador, não uma persistência confirmada ou entrega bem-sucedida. Para um processamento confirmado no backend, utilize Webhooks. Os payloads dos callbacks podem conter dados pessoais; não os encaminhe na totalidade para plataformas de analítica ou registos públicos.

Callbacks de eventos legados

O objeto window.aichatbotCallback também suporta onUserMessage e onChatbotMessage como propriedades diretas. Utilize addCallback() para obter listeners modulares sem substituir o objeto global:

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 a implementação por iframe, utilize postMessage para comunicar com o chatbot:

Envio 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);

Receção 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;
    }
});

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 exclusivo do cliente
  • clientName, clientEmail, clientPhone (opcional): Dados do cliente apresentados nas conversas
  • clientSecurityToken (opcional): Um token encaminhado como contexto para a sua integração personalizada. A sua própria API tem de validar a sua autenticidade, expiração e autorização.
  • clientHostContext (opcional): Parâmetros de contexto adicionais acessíveis em ações de API personalizadas

Os IDs e o contexto fornecidos pelo navegador não constituem prova de identidade. Não coloque segredos globais da conta no JavaScript da página e não conceda acesso apenas porque o clientId ou o e-mail fornecido coincide com um registo existente.

Utilização em chamadas de API:

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Parâmetros personalizados de contexto do host prefixados por 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 uma camada de idiomas para alternar, pelo que setLanguage() não tem qualquer efeito 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 em que o visitante está a ler, em vez daquele em que o navegador se encontra 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 do carregamento do script, o que evita que o idioma incorreto pisque brevemente no ecrã:

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

Que idioma tem prioridade. O widget determina o idioma pela seguinte ordem:

  1. O idioma selecionado pelo próprio visitante no menu de idiomas do 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 manual do visitante é guardada para visitas futuras, mas deixa de vigorar assim que o idioma da página for alterado - desta forma, o seletor de idioma da sua página terá sempre prioridade sobre uma opção antiga. Os códigos seguem a norma ISO 639-1 (en, de, pl); um código regional como de-AT recorre a de. Um idioma que o bot não disponibilize é ignorado.

Mudar de idioma não encerra a conversa nem limpa o histórico da transcrição.

Artigos relacionados

Pesquisar em todos os artigosPergunte ao agente