Widget de chat web

O que é

O widget de chat web é mais um canal da MINDO (assim como WhatsApp, Instagram ou ManyChat): um balão de chat que você incorpora no seu site com um <script> e que conecta seus visitantes à sua caixa de entrada da MINDO. As mensagens que escreverem chegam na mesma Caixa de entrada onde você já atende o WhatsApp, e sua equipe (ou seu agente de IA) responde de lá — a resposta chega ao visitante em tempo real, sem que ele precise recarregar a página. Ele suporta dois tipos de visitante:

Anônimo — não exige nada do seu backend. O widget gera um identificador de visitante próprio (guardado no localStorage do navegador) para reconhecê-lo entre as mensagens.
Identificado — se o visitante já está logado no seu site, seu backend pode assinar a identidade dele para que a MINDO o reconheça. Isso une, sob um mesmo contato, todos os chats que esse usuário abrir em dispositivos diferentes, e deixa a conversa disponível quando ele voltar.

Antes de começar

Tenha à mão o seguinte:

Acesso a Configurações → Canais na MINDO com perfil de administrador.
Acesso ao código do seu site (para colar um <script>).
Se for identificar usuários logados: acesso ao backend do seu site, para assinar a identidade. A assinatura é calculada sempre no servidor, nunca no navegador.

Passo a passo

Criar o canal Web

Na MINDO, vá em Configurações → Canais e procure a seção Widget de chat web. Clique em + Adicionar canal Web.

Seção de canais Web na MINDO — Seção Widget de chat web em Configurações → Canais

Preencha:

Nome da sessão — identifica o canal dentro da MINDO e, além disso, é o título que o visitante vê no cabeçalho do chat (por exemplo, “Chat da loja”).
Cor primária — a cor do cabeçalho do painel, dos balões do visitante e do botão Enviar.
Mensagem de boas-vindas — a primeira mensagem que o visitante vê enquanto não houver conversa. Não é salva como mensagem nem aciona o agente.
Agente (opcional) — se você quiser que um agente de IA responda automaticamente neste canal.

Formulário para criar um canal Web — Formulário de criação de um canal Web

O agente não responde no widget só por existir na empresa: ele precisa estar atribuído aqui. Com Sem agente, as mensagens aguardam resposta humana na Caixa de entrada, como em qualquer outro canal.

Uma empresa pode ter vários canais Web ao mesmo tempo —um por marca, por site ou por país—. Cada um tem seu token, sua cor e seu agente, e as conversas de um nunca se misturam com as do outro.

Copiar o snippet

Ao criar o canal, a MINDO mostra o snippet pronto para copiar:

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="SEU_TOKEN_DE_CANAL"
  async
></script>

Você também vai ver um Secret HMAC — só precisa dele se for identificar visitantes logados (Passo 4). Guarde-o em um lugar seguro; ele nunca deve ficar exposto no HTML do seu site.

Snippet de incorporação e Secret HMAC do canal — Snippet e Secret HMAC do canal recém-criado

O token do snippet é público: ele viaja no HTML do seu site e é esperado que fique visível. O Secret não: é exibido mascarado e só os usuários com perfil ADMIN da empresa podem vê-lo (para um MEMBER ou VIEWER a API devolve o campo vazio).

Colar o snippet no seu site

Cole o <script> antes do fechamento de </body> nas páginas onde você quer que o chat apareça. Não é preciso build step nem dependência — é um script vanilla, autocontido.Ao carregar a página você verá um balão de chat no canto inferior direito. Ao clicar, abre um painel com o chat (é um <iframe> para a MINDO, então seu site não precisa implementar nenhuma interface de chat).

Painel do widget aberto sobre um site de exemplo

Se o balão não aparecer, verifique o console do navegador: o erro mais comum é um data-mindo-token vazio ou incorreto.

O balão flutuante é sempre azul. A cor primária que você configurou se aplica dentro do painel (cabeçalho, balões do visitante, botão Enviar), não ao balão. É o comportamento esperado, não um erro de configuração.

A partir daqui, cada mensagem do visitante cria um chat na sua Caixa de entrada com canal Web, e sua equipe atende com o mesmo compositor de sempre. O chat do widget traz um dado que nenhum outro canal tem: o indicador “Está na página”, que informa se o visitante ainda está com o seu site aberto neste momento.

Chat Web na Caixa de entrada da MINDO com indicador de presença — Chat do widget na Caixa de entrada, com o indicador de presença

(Opcional) Identificar visitantes logados

Se o seu site tem usuários logados e você quer que a MINDO os reconheça (em vez de tratá-los como anônimos), seu backend assina um JWT e o passa no atributo data-mindo-identity.O JWT é assinado com o algoritmo HS256 usando o Secret HMAC do canal, e seu payload aceita estes campos:

Campo	Obrigatório	O que é
`sub`	Sim	O identificador único do seu usuário — o que você usa internamente.
`exp`	Sim	Vencimento (timestamp Unix, em segundos).
`name`	Não	Nome do usuário, para que o contato não fique como “Visitante”.
`email`	Não	E-mail do usuário.
`phone`	Não	Telefone em formato internacional. É o que permite unificar este contato com o do WhatsApp.

O exp não pode estar a mais de 7 dias. Um JWT com vencimento mais distante é considerado inválido e o visitante fica anônimo. É um limite deliberado: se roubarem o token de alguém, sete dias é o máximo que esse roubo serve. Um TTL de 24 a 72 horas é o habitual.

const jwt = require("jsonwebtoken");

function assinarIdentidade(usuario, secretDoCanal, ttlSegundos = 60 * 60 * 24) {
  return jwt.sign(
    {
      sub: String(usuario.id),
      name: usuario.nome,
      email: usuario.email,
      phone: usuario.telefone,
      exp: Math.floor(Date.now() / 1000) + ttlSegundos,
    },
    secretDoCanal,
    { algorithm: "HS256" }
  );
}

import time
import jwt  # pip install pyjwt

def assinar_identidade(usuario, secret_do_canal, ttl_segundos=60 * 60 * 24):
    payload = {
        "sub": str(usuario.id),
        "name": usuario.nome,
        "email": usuario.email,
        "phone": usuario.telefone,
        "exp": int(time.time()) + ttl_segundos,
    }
    return jwt.encode(payload, secret_do_canal, algorithm="HS256")

Renderize o token no <script> a partir de um template do lado do servidor:

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="SEU_TOKEN_DE_CANAL"
  data-mindo-identity="{{ identityToken }}"
  async
></script>

O Secret HMAC é um segredo de servidor. Nunca o inclua em HTML, JavaScript do cliente, nem em um repositório público — ele só deve existir no seu backend, do mesmo modo que você guardaria qualquer outra API key.

Com a identidade assinada, o chat deixa de mostrar “Visitante ####” e passa a ser a pessoa real, com telefone e e-mail já preenchidos na ficha do contato:

Chat do widget com o contato identificado na Caixa de entrada — O mesmo chat, já identificado como o contato real

A assinatura é opcional por design: se faltar, estiver vencida ou for inválida, o visitante simplesmente fica anônimo — o chat nunca é bloqueado por um erro de assinatura. Isso permite testar sem risco de deixar o widget fora do ar.A contrapartida é que um JWT mal montado falha em silêncio. Se o contato continuar aparecendo como “Visitante ####”, verifique nesta ordem: que o secret seja o do mesmo canal que o token, que o exp esteja em segundos (não milissegundos) e a menos de 7 dias, que a claim se chame sub, e que o algoritmo seja HS256.

Método anterior: os três atributos com assinatura HMAC

Antes do JWT, a identidade era passada com três atributos separados. Continua funcionando e não é preciso migrar: se você usar os dois esquemas ao mesmo tempo, o JWT ganha, e se o JWT estiver quebrado ele cai para este.

Atributo	O que é
`data-mindo-user`	O identificador único do seu usuário (`userId`).
`data-mindo-expires`	Timestamp Unix (segundos) até quando a assinatura é válida.
`data-mindo-signature`	`HMAC_SHA256(secret, "{userId}:{expires}")` em hexadecimal.

const crypto = require("crypto");

function assinarVisitante(userId, secretDoCanal, ttlSegundos = 60 * 60 * 24) {
  const expires = Math.floor(Date.now() / 1000) + ttlSegundos;
  const signature = crypto
    .createHmac("sha256", secretDoCanal)
    .update(`${userId}:${expires}`)
    .digest("hex");
  return { userId, expires, signature };
}

import hmac
import hashlib
import time

def assinar_visitante(user_id, secret_do_canal, ttl_segundos=60 * 60 * 24):
    expires = int(time.time()) + ttl_segundos
    mensagem = f"{user_id}:{expires}".encode("utf-8")
    signature = hmac.new(
        secret_do_canal.encode("utf-8"), mensagem, hashlib.sha256
    ).hexdigest()
    return {"userId": user_id, "expires": expires, "signature": signature}

<script
  src="https://app.mindosoftware.com/widget.js"
  data-mindo-token="SEU_TOKEN_DE_CANAL"
  data-mindo-user="{{ userId }}"
  data-mindo-signature="{{ signature }}"
  data-mindo-expires="{{ expires }}"
  async
></script>

Por que o JWT é melhor se você está começando: este esquema assina a string userId:expires usando : como separador, então não permite acrescentar o nome ou o e-mail sem ficar ambíguo. O JWT assina os dados exatos e permite enviar name, email e phone — que é o que faz o contato ter nome real e se unificar com o chat de WhatsApp dele.

(Opcional) Identificar o visitante depois que ele fez login

Se o seu site é uma SPA, ou o visitante abre o chat antes de fazer login, não é preciso recarregar a página para que a MINDO o reconheça. O widget expõe um objeto window.Mindo:

// Depois que seu usuário faz login, com o JWT que seu backend assinou:
window.Mindo.setUser(identityToken);

// Ao sair:
window.Mindo.clearUser();

O script carrega com async, então pode ser que window.Mindo ainda não exista quando o seu código rodar. Para isso existe uma fila de comandos: enfileire as chamadas e o widget as processa ao terminar de carregar.

window.Mindo = window.Mindo || { q: [] };
(window.Mindo.q = window.Mindo.q || []).push(["setUser", identityToken]);

Você também pode fazer isso sem escrever código de integração: se a sua página guardar o JWT no localStorage sob a chave mindo_identity, o widget o pega sozinho. Serve para o caso do login em uma aba nova ou com um redirect de OAuth, porque o widget escuta as mudanças dessa chave. O mesmo valor pode ser difundido por um BroadcastChannel chamado mindo-identity.

Além de setUser e clearUser, window.Mindo expõe open(), close() e toggle() para controlar o painel a partir da sua própria interface (por exemplo, um botão “Precisa de ajuda?”), e on(evento, callback) / off(evento, callback) para escutar open, close, unread, identity, identity:cleared, auth:login e auth:register.

(Opcional) Convidar a fazer login pelo chat

O widget pode mostrar ao visitante anônimo um bloco com botões de Entrar e Criar conta que apontam para as páginas do seu site. Ele desaparece sozinho quando o visitante fica identificado.

Widget com botões de entrar e criar conta — Botões de login e cadastro dentro do painel do widget

Configura-se em Configurações → Canais → Widget de chat web, editando o canal: ative Botões de login e preencha as URLs, os textos dos botões e a mensagem que fica acima deles.

Configuração dos botões de login e cadastro do widget — Seção Botões de login ao editar o canal

Campo	O que é
URL de login	Para onde mandar o visitante que já tem conta.
URL de cadastro	Para onde mandá-lo se ainda não tiver.
Textos dos botões	Opcionais. Por padrão, “Entrar” e “Criar conta”.
Mensagem acima dos botões	A frase que explica por que vale a pena fazer login.

Basta uma das duas URLs: o botão que não tiver URL não é exibido.Também dá para fazer por API, com um usuário ADMIN da empresa:

curl -X PATCH https://api.mindosoftware.com/web-widget/channels/<ID_DO_CANAL>/ \
  -H "Authorization: Bearer <TOKEN_DE_UM_ADMIN>" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "enabled": true,
      "loginUrl": "https://seusite.com/login",
      "registerUrl": "https://seusite.com/cadastro",
      "loginLabel": "Entrar",
      "registerLabel": "Criar conta",
      "prompt": "Faça login para ver seus pedidos e retomar a conversa de qualquer dispositivo."
    }
  }'

Ao clicar, o widget abre a URL em uma aba nova. Se você preferir controlar a navegação (por exemplo, abrir o seu próprio modal de login), intercepte: devolver false no handler cancela a abertura.

window.Mindo.on("auth:login", ({ url }) => {
  abrirMeuModalDeLogin();
  return false;
});

As URLs devem ser https://. Uma http:// é rejeitada ao salvar, e se tiver sido carregada na mão pelo admin o botão simplesmente não é renderizado.

Envie o bloco no campo auth, não dentro de config. Um config explícito substitui o salvo (exceto prechat e auth), então um {"config": {"auth": {...}}} apaga a sua cor e a mensagem de boas-vindas. O campo auth plano é salvo sozinho, sem mexer no resto.

O que acontece depois?

Cada mensagem que um visitante escreve cria (ou continua) um chat na sua Caixa de entrada da MINDO, com Canal: Web.
Se você identificou o visitante e essa mesma pessoa escreve de outro dispositivo com o mesmo sub, a MINDO unifica o histórico sob um único contato.
Se o JWT inclui phone e esse telefone já existe como contato de WhatsApp, a MINDO os unifica: fica um contato com suas duas conversas (a do widget e a do WhatsApp), em vez de duas pessoas diferentes.
Se você tem um agente de IA atribuído ao canal, ele pode responder automaticamente; se não, o chat aguarda resposta humana como qualquer outro canal.

Perguntas frequentes

Preciso instalar algo no meu site além do script?

Não. O <script> é autocontido: cria seu próprio balão e seu próprio painel de chat (um iframe). Não exige CSS, dependências nem build step.

Posso ter o widget em várias páginas do meu site?

O que acontece se o visitante recarregar a página no meio da conversa?

Não perde nada: o widget recupera a conversa automaticamente ao recarregar e a mostra assim que ele abre o painel, sem precisar escrever de novo.

O visitante percebe se respondermos com o chat fechado?

Enquanto ele estiver com a sua página aberta, sim: o balão mostra um contador com as mensagens que chegaram com o painel fechado, e ele se limpa quando o visitante abre.

Balão do widget com o contador de não lidas — Contador de mensagens não lidas sobre o balão

Se ele fechou a aba, hoje não há aviso: na próxima vez que voltar ao seu site vai encontrar a resposta ao abrir o chat, mas nenhuma notificação chega até lá. Por isso vale pedir telefone ou e-mail pelo JWT (phone / email): com esses dados você pode retomar a conversa por outro canal.

O visitante pode mandar fotos ou áudios?

Não. O compositor do widget é somente texto, com limite de 4.000 caracteres por mensagem. Do lado do operador é possível enviar arquivos, e o visitante os recebe no painel.

Há limites de uso nos endpoints públicos?

Sim, limites anti-abuso por IP, bem acima do uso de uma pessoa real: 30 por minuto para enviar mensagens, 20 por minuto para a contagem de não lidas e 10 por minuto para abrir sessão com identidade assinada.

O que acontece se eu não configurar a identificação?

Nada quebra: todos os visitantes ficam anônimos, cada um com seu próprio chat. Você pode adicionar a identificação mais adiante sem mudar nada do que já instalou.

Preciso migrar do método de três atributos para o JWT?

Não. O esquema anterior continua suportado e não tem data de encerramento. Migre só se quiser enviar o nome, o e-mail ou o telefone do usuário — coisas que o formato antigo não permite.

Posso restringir em quais sites meu token pode ser usado?

Sim. O canal tem uma lista de origens permitidas (allowed_origins): com a lista vazia —o valor padrão— não há restrição; com origens cadastradas, o header Origin da página tem que coincidir exatamente com alguma delas ou a API responde 403.Ainda não está exposta no formulário de Configurações: carrega-se por API (PATCH /web-widget/channels/<id>/ com allowed_origins) ou pelo admin. Se você ativar, inclua todos os domínios e subdomínios de onde o seu site é servido: um que falte deixa o chat sem funcionar nessas páginas.

Posso pedir telefone ou e-mail ao visitante antes que ele escreva?

Hoje não ative. A configuração existe no backend (config.prechat, com níveis off / optional / required para phone e email) mas o widget ainda não mostra esse formulário, então nunca envia esses dados.

Com phone ou email em required, a primeira mensagem de um visitante novo recebe 422 {"error": "Faltan campos obligatorios"} e o visitante não consegue iniciar a conversa. Deixe em off até a interface existir.

Tem custo adicional?

O canal Web não tem custo de mensageria como o WhatsApp (não depende da Meta). Consulte seu plano da MINDO se aplica algum limite de uso.

Começar

Guias

WhatsApp

Widget de chat web

O que é

Antes de começar

Passo a passo

O que acontece depois?

Perguntas frequentes

​O que é

​Antes de começar

​Passo a passo

​O que acontece depois?

​Perguntas frequentes

O que é

Antes de começar

Passo a passo

O que acontece depois?

Perguntas frequentes