Widget, portal e central de ajuda

Os seus clientes falam com o atendimento sem sair do seu site: um balão de conversa no canto da página, uma área para acompanhar os chamados e uma central de ajuda com artigos. A TAI entrega as três prontas; as rotas públicas abaixo servem para quem quer uma interface própria — um app, um chat nativo, uma central com a cara do seu produto.

Quando usar	Clientes externos abrem e acompanham chamados no seu site ou app
Porta	Página pública · rotas públicas (sem login de usuário da TAI)
Você vai precisar	módulo ATENDIMENTO; ATENDIMENTO_PARAMETRIZAR para criar o widget e publicar a central; para portal e central, o subdomínio da empresa

Porta	Para quê
Widget	Balão de conversa no canto do seu site
Portal do cliente	Área em que o cliente acompanha os próprios chamados
Central de ajuda	Artigos públicos, busca, resposta automática e abertura de chamado

Como funciona

visitante ──► widget (iframe) ──► /public/atendimento/widget/{chave}/…   ─┐
cliente   ──► portal          ──► /public/atendimento/portal/{subdominio}/… ├─► chamado na caixa de entrada
visitante ──► central         ──► /public/atendimento/central/{subdominio}/…┘
equipe responde na TAI ──► e-mail ao cliente + mensagem no widget/portal

Instalar o widget

1. Na plataforma, abra Atendimento → Configurações → Canais, aba Widget, e crie o widget.

2. Cadastre em Domínios permitidos os sites onde o widget vai aparecer — separados por vírgula; *.suaempresa.com.br cobre o domínio e todos os subdomínios.

3. Copie o trecho gerado e cole antes do </body> do seu site:

   <script src="https://app.taitecnologia.com/widget/tai-atendimento.js"
           data-chave="SUA_CHAVE_DE_24_CARACTERES" async></script>

Atributos opcionais:

Atributo	Efeito
data-cor	Cor do botão (ex.: #2883C5)
data-posicao="esquerda"	Mostra o botão no canto esquerdo

O script abre o widget num iframe. A página hospedeira recebe por postMessage os eventos tai-widget:close (o visitante fechou) e tai-widget:unread (com count, as mensagens não lidas) — úteis para sincronizar um contador no seu layout.

Cuidado

Um site fora da lista de domínios permitidos recebe 403 — “Este site não está autorizado a usar o widget.” Se a chave vazar, regenere-a na mesma tela; a antiga para de funcionar na hora.

Rotas públicas do widget

Para uma interface própria (aplicativo, chat nativo), as rotas ficam em /public/atendimento/widget/{chave}:

Rota	O que faz
GET /config	Título, cor, mensagem de boas-vindas e se exige e-mail confirmado
POST /identificar	{nome, email} → sessão, ou {precisaCodigo: true} se o e-mail precisa ser confirmado
POST /verificar	{email, codigo} → sessão
GET /sessao	Quem é o visitante da sessão
GET /chamados	Últimos chamados do visitante
POST /chamado	Abre chamado: {assunto?, corpoHtml}
GET /chamado/{id}	Uma conversa do visitante
GET /chamado/{id}/mensagens?apos={id}	Mensagens novas desde a última lida — use para polling
POST /chamado/{id}/mensagem	Responde: {corpoHtml}
POST /sair	Encerra a sessão

A sessão devolve um token, enviado nas chamadas seguintes no cabeçalho X-Widget-Token, e vale 90 dias.

Portal do cliente

Rotas em /public/atendimento/portal/{subdominio}. O cliente entra com um código enviado por e-mail (POST /acesso/solicitar e POST /acesso/verificar) e recebe um token para o cabeçalho X-Portal-Token, válido por 30 dias. Com ele:

Rota	O que faz
GET /sessao	Quem está logado
GET /chamados	Os chamados do cliente
POST /chamados	Abre um chamado
GET /chamados/{numero} e /mensagens	Detalhe e conversa
POST /chamados/{numero}/responder	Responde
POST /chamados/{numero}/anexo	Anexa arquivo
GET /anexo/{anexoId}/download	Baixa um anexo
POST /chamados/{numero}/avaliar	Avalia o atendimento (nota 1–5 e comentário), uma vez, depois de resolvido
POST /sair	Encerra a sessão

O cliente só vê os próprios chamados: o de outra pessoa responde 404.

Central de ajuda

Rotas em /public/atendimento/central/{subdominio}, sem login:

Rota	O que faz
GET /config	Aparência: título, cor, logo, saudação, rodapé
GET /categorias	Categorias de artigos
GET /artigos?categoria=&q=	Lista e busca artigos
GET /artigos/populares	Os mais lidos
GET /artigos/{slug}	Um artigo
POST /artigos/{slug}/util	“Este artigo ajudou?” — {"util": true}
POST /perguntar	{"pergunta": "…"} → resposta automática com base nos artigos
POST /chamado	Abre chamado sem login: {nome, email, assunto, corpoHtml, campos?}

Com o X-Portal-Token de um cliente logado, a central também mostra os artigos restritos a solicitantes. A central publicada fica em https://{subdominio}.ajuda.taitecnologia.com. Para publicar artigos a partir do seu sistema, veja Levar os chamados para o seu sistema.

Avaliação por link

Quando um chamado é resolvido, o solicitante recebe um link de avaliação. As rotas GET /public/atendimento/avaliacao/{token} (o que a página mostra) e POST /public/atendimento/avaliacao/{token} ({"nota": 5, "comentario": "…"}) permitem uma página própria. Só a primeira resposta vale.

Códigos por e-mail

Os códigos de confirmação têm 6 dígitos, valem 10 minutos, aceitam 5 tentativas e podem ser pedidos de novo depois de 60 segundos.

Limites

Ação	Limite por IP
Pedir código	10 por minuto
Verificar código	20 por minuto
Identificar no widget	20 por minuto
Perguntar na central	20 por minuto
Abrir chamado sem login	5 por minuto
Avaliar atendimento	30 por minuto

Cuidados

• A chave do widget é pública — ela vai no HTML do seu site. Quem protege é a lista de domínios permitidos; mantenha-a curta.
• Abertura sem login confirma por e-mail: quem abre pela central ou pelo widget recebe o número e o link para acompanhar.
• Para levar esses chamados a outro sistema, assine os eventos do Atendimento — Um chamado é aberto (CHAMADO_ABERTO), Um chamado é avaliado (CHAMADO_AVALIADO)… — num webhook, ou use um gatilho com a ação Webhook — veja Levar os chamados para o seu sistema.