API JavaScript de chat ao vivo
Use a API JavaScript do onWebChat para personalizar seu widget de chat e automatizar fluxos. Você pode passar dados do visitante, definir o idioma do widget, maximizar ou ocultar o widget e mais.
Por exemplo, você pode enviar os detalhes do visitante para o chat, definir o idioma por página ou abrir o widget de forma programática quando um usuário clica em um botão.
Adicione seu código da API logo abaixo do script do widget de chat, como mostrado à direita.
<script type='text/javascript'>
/* Cole aqui o código de instalação do widget do onWebChat que você encontra no painel. */
</script>
<script type='text/javascript'>
/* Adicione abaixo suas chamadas à API JavaScript, por exemplo onWebChat.set() ou onWebChat.get() */
</script>
Definir informação do visitante
Você pode definir os dados do visitante antes ou durante uma sessão de chat. Por exemplo, definir o nome ajuda sua equipe a identificar contatos na lista de visitantes.
Use as seguintes chamadas da API para definir o nome, o e-mail, o telefone e as notas do visitante:
onWebChat.set("name","Sarah Chen");
onWebChat.set("email","sarah.chen@example.com");
onWebChat.set("phone","+1 555 010 0142");
onWebChat.set("notes","Returning visitor, requested an Enterprise trial");
Obter informações do visitante
Você pode ler o nome, o e-mail, o telefone e as notas do visitante sempre que esses valores tenham sido fornecidos por esta API JavaScript, coletados no formulário pré-chat ou atualizados pelos agentes no painel.
Chame estas funções depois que o widget estiver completamente carregado. Exemplo:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });
onWebChat.get("name");
onWebChat.get("email");
onWebChat.get("phone");
onWebChat.get("notes");
Definir o idioma do widget
Você pode definir o idioma do widget com o código de qualquer idioma ativado no seu painel.
Por exemplo, "pt" para português, "en" para inglês e "es" para espanhol. Se o código informado não estiver ativado, o widget usa seu idioma padrão. Sem esta chamada, o widget usa o idioma do navegador do visitante, se você tiver ativado essa opção. Você pode gerenciar os idiomas ativados e o idioma padrão em Configurações > Widget > Idiomas.
Códigos de idioma disponíveis:
onWebChat.set("language","es");
Definir a aparência do widget
Você pode controlar a visibilidade e o estado de abertura do widget:
Use o parâmetro max com 0 para minimizar ou 1 para maximizar o widget.
Para ocultar completamente o widget, use o parâmetro show com o valor 0. Use 1 para exibi-lo novamente.
onWebChat.set("max",1);
onWebChat.set("show",0);
Definir tamanho do widget
Em uma página específica, você pode mostrar o widget em qualquer um dos três tamanhos de Configurações > Widget > Configurações do widget, sem alterar o tamanho salvo na sua conta.
Use o parâmetro size com o valor "standard" (o tamanho Pequeno no painel), "large" ou "xlarge" (Extra grande). É útil em páginas com pouco espaço livre ou em uma landing page em que você quer um widget maior.
Importante: coloque esta chamada logo abaixo do script do widget, antes de o widget carregar. O widget é criado uma única vez, no carregamento, por isso um tamanho definido depois é ignorado.
onWebChat.set("size","standard");
onWebChat.set("size","large");
onWebChat.set("size","xlarge");
Alterar textos do widget
Você pode substituir os textos do widget em uma página específica, por exemplo uma saudação diferente na página de preços. Os novos textos são usados apenas nessa página e não são salvos no seu painel.
Use o parâmetro texts com um objeto com os campos que você quer alterar, como max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg ou prechat_msg.
Um texto informado como string é usado em todos os idiomas do widget. Para alterar apenas um idioma, passe um objeto com os códigos de idioma, como no segundo exemplo.
Você pode chamá-la abaixo do script do widget, antes de ele carregar, ou a qualquer momento depois: o widget é redesenhado com os novos textos.
onWebChat.set("texts",{
max_title: "Need help?",
max_subtitle: "We usually reply in a minute"
});
onWebChat.set("texts",{
min_online: { en: "Chat with us", es: "Chatea con nosotros" }
});
Definir as cores do widget
Em uma página específica, você pode dar ao cabeçalho do widget uma cor enquanto o chat está online e outra enquanto está offline. Use os parâmetros onlineColor e offlineColor com qualquer cor CSS, como "#2e7d32".
As cores são usadas apenas nessa página e não alteram a cor salva em Configurações > Widget > Configurações do widget. Você pode defini-las antes de o widget carregar ou a qualquer momento depois. A cor offline também é usada no botão Enviar do formulário offline.
onWebChat.set("onlineColor","#2e7d32");
onWebChat.set("offlineColor","#757575");
Definir informações da página
Você pode substituir o URL e o título da página atual que são enviados ao painel do onWebChat:
Use o parâmetro pageUrl para definir um URL personalizado. É especialmente útil em aplicativos de página única (SPA) ou com roteamento personalizado, em que o URL do navegador não muda.
Use o parâmetro pageTitle para definir um título personalizado que os agentes verão no lugar do título da página do navegador.
onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");
onWebChat.set("pageTitle","Checkout: shipping details");
Obter o status do widget
Retorna "online" ou "offline" conforme a disponibilidade atual do seu chat.
Chame esta função depois que o widget carregar. Exemplo:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });
onWebChat.get("status");
Obter status da conexão
Retorna true se o widget de chat tiver uma conexão socket ativa com o servidor, e false caso contrário.
onWebChat.get("isConnected");
Obter status aberto/fechado do widget
Retorna true se o widget de chat está maximizado (aberto) no momento, ou false se está minimizado (fechado).
onWebChat.get("isMaximized");
Obter ID do diálogo
Retorna o ID do diálogo ativo atual, ou 0 se não houver uma sessão de chat ativa. É o mesmo ID que chat_id nos payloads dos webhooks, por isso é útil para integrações que precisam vincular uma sessão de chat a um CRM ou sistema de tickets.
onWebChat.get("dialogId");
Enviar mensagem
Você pode enviar de forma programática uma mensagem de chat em nome do visitante. É útil para criar fluxos de ajuda contextuais, por exemplo enviar automaticamente “Preciso de ajuda com meu pedido” quando um visitante clica em um botão específico.
A mensagem aparece no chat exatamente como se o visitante a tivesse digitado, e a janela de chat é aberta. O widget precisa estar totalmente carregado e conectado antes de você poder enviar uma mensagem. Para evitar abusos, o widget envia dessa forma no máximo 3 mensagens por segundo, 8 por minuto e 30 por hora.
onWebChat.set("sendMessage","I need help with my order");
Definir departamento
Você pode pré-selecionar um departamento para o visitante com base no contexto da página atual. Por exemplo, você pode encaminhar automaticamente os visitantes da página de preços para o departamento “Vendas” e os da página de ajuda para “Suporte”.
Você pode passar o nome do departamento (como string) ou o ID do departamento (como número). Se usar o nome, ele precisa corresponder exatamente a um dos departamentos configurados no seu painel.
Você encontra o ID do departamento no seu painel: acesse Configurações > Equipe > Departamentos e clique em um departamento. O ID é exibido ao lado do nome do departamento.
Você não precisa ativar a opção de departamentos no formulário pré-chat: definir o departamento com a API JavaScript funciona por si só.
Se nenhum agente do departamento selecionado estiver online, a mensagem é entregue a todos os agentes conectados. Se o chatbot de IA estiver ativado, ele não responde enquanto houver um agente do departamento online e responde ao visitante quando não houver nenhum.
Para mais informações sobre departamentos, consulte nosso guia de departamentos.
onWebChat.set("department","Sales");
onWebChat.set("department",1333);
Funções de callback
Você pode executar funções de callback quando ocorrem eventos específicos do chat:
onClick é executado quando o visitante clica no widget de chat.
onMaximize é executado quando o widget é maximizado (aberto).
onMinimize é executado quando o widget é minimizado (fechado).
onTrigger é executado quando um trigger de interação ou de intenção de saída é ativado, mesmo que o widget esteja oculto com show definido como 0.
onStartWriting é executado quando o visitante começa a digitar uma mensagem (uma vez por sessão do navegador).
onNewMessage é executado quando uma nova mensagem é enviada ou recebida. O callback recebe dois argumentos: o texto da mensagem e o remetente ("visitor", "agent" ou "bot").
onEndChat é executado quando a sessão de chat termina. O callback recebe um argumento que indica quem a encerrou ("visitor", "agent" ou "bot").
onChatStatusChange é executado quando o status do widget de chat muda. O callback recebe um argumento com o novo status ("online" ou "offline").
onWebChatLoaded é executado assim que o widget de chat termina de carregar.
onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });
onWebChat.set("onMaximize",function(){ alert('chat maximized'); });
onWebChat.set("onMinimize",function(){ alert('chat minimized'); });
onWebChat.set("onTrigger",function(){ alert('trigger activated'); });
onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });
onWebChat.set("onNewMessage",function(msg, by){
console.log('new message by ' + by + ': ' + msg);
});
onWebChat.set("onEndChat",function(endedBy){
console.log('chat ended by ' + endedBy);
});
onWebChat.set("onChatStatusChange",function(status){
console.log('agents are now ' + status);
});
onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });