API pública do widget do site

O widget do site coloca uma conversa com seu agente em qualquer página sua. Quem visita o site conversa com o mesmo agente que atende seus outros canais, e a conversa aparece em Conversas como as demais. Esta página mostra como instalar o script, como enviar dados da página para o agente e, para quem constrói a própria interface, como funciona a API pública por trás dele.

Instalar o script

Cada widget tem uma chave pública. Cole o script no HTML das páginas onde a conversa deve aparecer, trocando a chave pela do seu widget:

<script src="https://api.interage.ai/widget/v1.js" data-key="SUA_CHAVE_PUBLICA" async></script>

A chave pública não é um segredo: ela aparece no HTML do site. O que protege o widget é a lista de domínios permitidos. O widget só abre em sites dessa lista, e a lista vale também para cada chamada da conversa.

Enviar o contexto da página

Use window.Interage para dizer ao agente o que a pessoa está vendo, como o imóvel aberto, o plano consultado ou a página atual. O agente lê esses dados no próximo turno e responde com mais precisão.

Interage.setContext({ pagina: 'imovel-1234', plano: 'premium', logado: true })
Interage.open()
Interage.close()
Interage.isOpen() // true ou false

Os métodos acima só existem depois que o script carrega. Para enviar o contexto ou abrir a janela antes disso, declare a fila antes do script e empilhe as chamadas nela:

<script>
  window.Interage = window.Interage || { q: [] }
  Interage.q.push(['setContext', { pagina: 'imovel-1234' }])
  Interage.q.push(['open'])
</script>
<script src="https://api.interage.ai/widget/v1.js" data-key="SUA_CHAVE_PUBLICA" async></script>

Ao carregar, o widget executa a fila uma vez, na ordem, e troca window.Interage pelos métodos de verdade. Daí em diante, chame os métodos direto: o que for empilhado em Interage.q depois do carregamento é ignorado.

isOpen não entra na fila. Ele devolve false até o widget aparecer na página, e o widget não aparece quando está desligado, sem domínio ou num site fora da lista.

Formato do contexto

O contexto é um objeto plano. O que não cabe nas regras abaixo é descartado em silêncio, sem erro.

Na conversa, o painel mostra a página atual e o contexto recebido. A página atual é lida das chaves pagina, page ou url, nessa ordem.

Identificar o usuário logado

Em áreas logadas, seu servidor pode provar quem é a pessoa. Gere no servidor um JWT HS256 assinado com o segredo idsec_… do widget e entregue-o à página:

Interage.identify({ token: '<JWT gerado no seu servidor>' })

O token leva sub (o id do usuário no seu sistema, obrigatório), iat e exp (no máximo 24 h entre eles) e, se quiser, name, email, phone e context. Com o token válido, a conversa fica marcada como identidade verificada e é ligada ao contato que já existe no CRM. O mesmo sub volta sempre à mesma conversa, inclusive em outro navegador. Se a conversa aberta for de outro usuário, o widget a descarta e abre a do usuário atual.

A conversa identificada não fica guardada no navegador: ao recarregar a página, ela volta quando você chama Interage.identify de novo. Só a conversa de visitante anônimo fica guardada, por até 30 dias.

Nunca coloque o segredo idsec_… na página: ele fica só no seu servidor. Com Exigir identificação ligado, o botão do widget só aparece depois de Interage.identify.

A API pública

O script usa a API pública abaixo. Você só precisa dela para montar uma interface própria no lugar do widget pronto. Todas as rotas ficam em https://api.interage.ai/api/public/v1/widget.

Abrir a conversa

POST /:publicKey/sessions exige o cabeçalho Origin de um domínio permitido e o token do desafio Turnstile (turnstileToken), que prova que quem abre a conversa não é um robô. Opcionalmente, o corpo leva o pré-chat (prechat com name, phone, email), o context e o identityToken (o JWT de identificação).

A resposta traz o token da conversa. Guarde-o: ele só é devolvido uma vez. Com identityToken de um usuário que já tem conversa neste widget, a resposta volta com resumed: true e um token novo dessa conversa; o token anterior deixa de valer.

POST /sessions/:id/identify identifica uma conversa aberta sem token. O mesmo sub de novo responde 200. Outro sub, ou um sub que já tem outra conversa neste widget, responde 409 identity_mismatch: abra uma conversa nova com o token.

Obter o turnstileToken

O desafio só vale nos domínios cadastrados por nós, então ele roda numa página da API aberta num iframe no seu site:

1. Crie um iframe com https://api.interage.ai/widget/v1/turnstile?origin=<location.origin>&key=<chave pública>. A página só abre se origin estiver nos domínios permitidos do widget e só pode ser emoldurada por essa origem; fora disso, responde 403.
2. Escute message na janela do seu site. Aceite só eventos com event.origin igual à origem da API (https://api.interage.ai), vindos do próprio iframe (event.source === iframe.contentWindow) e com type: 'interage-widget-turnstile'.
3. A página manda { type: 'interage-widget-turnstile', token } quando o desafio passa, ou { type: 'interage-widget-turnstile', error: true } quando falha, expira ou não carrega. Remova o iframe depois da resposta.
4. Envie o token em turnstileToken. Ele vale para uma abertura só: em caso de erro, abra um iframe novo.

O desafio roda no modo interaction-only: em geral passa sem mostrar nada, então o iframe pode começar invisível. Quando o Cloudflare pede uma interação, o desafio aparece dentro do iframe. Por isso, se a resposta demorar alguns segundos, deixe o iframe visível para a pessoa resolver o desafio. O widget pronto mostra o iframe depois de 3 segundos e desiste em 20.

Token da conversa

Depois de aberta, toda chamada leva o token no cabeçalho x-widget-token. Nunca o envie na URL. A empresa e o widget saem da própria sessão, não do corpo do pedido. A conversa vale por 30 dias desde a última atividade; depois disso o token deixa de valer e é preciso abrir outra conversa.

Enviar mensagem

POST /sessions/:id/messages recebe:

A resposta é { messageId, duplicate, capped }. A resposta do agente não vem nela: busque em GET /sessions/:id/messages?after=, passando em after a data ISO (at) da última mensagem que você já tem, ou use o fluxo de eventos. Os eventos têm os tipos message_created, typing_started, typing_heartbeat, typing_stopped e state_changed.

Códigos de erro

Os erros voltam como { "error": "<código>", "message": "<texto>" }.

Limites e o que acontece em cada teto

Cada mensagem respondida pela IA é cobrada da sua empresa. Os limites impedem que alguém use seu widget para gerar custo. Você ajusta os quatro valores nas configurações do widget, dentro das faixas abaixo.

Um valor fora da faixa é recusado com 400.