GET/api/public/widget/history

Carrega o histórico de mensagens anterior de uma conversa do widget, por exemplo após recarregar a página.

Passe `widget_code`, `session_id` e `visitor_id` como parâmetros de consulta. A resposta contém, no objeto `data`, a lista `messages` com `role` (`user` ou `assistant`), `text` e `created_at` pela ordem da conversa. A chamada é apenas de leitura e idempotente. O cabeçalho `X-Widget-Token` com o token de incorporação e `widget_code` são obrigatórios. Se o token estiver em falta, o servidor responde 401 `WIDGET_TOKEN_MISSING`; se for inválido, 401 `WIDGET_TOKEN_INVALID`; chamadas de domínios não autorizados recebem 403 `WIDGET_ORIGIN_DENIED`, e um widget desativado, 404 `WIDGET_DISABLED`. Se faltarem `session_id` ou `visitor_id`, o servidor responde 400 `PARAMS_REQUIRED`. Se a sessão já não for conhecida, inicie uma nova conversa.

Visão geral

Chamada: GET /api/public/widget/history. Este endpoint pertence ao grupo «Widget de chat» da API da Zentor App. Requer um token de incorporação de widget válido. A chamada é idempotente: chamadas repetidas com os mesmos dados devolvem o mesmo resultado. Parâmetros obrigatórios: widget_code (query), session_id (query), visitor_id (query). Casos de erro documentados: 400 PARAMS_REQUIRED. A resposta de exemplo abaixo mostra a estrutura de uma resposta bem-sucedida em formato JSON.

Autenticação e segurança

Token de incorporação do widget (cabeçalho X-Widget-Token) + lista de origens permitidas

Idempotente: Sim

Parâmetros

widget_code(query, string, obrigatório)— Código do widget do seu código de incorporação
session_id(query, string, obrigatório)— ID de sessão da conversa a partir da resposta de `message`
visitor_id(query, string, obrigatório)— ID de visitante gerado pelo widget e armazenado no navegador

Resposta de exemplo

{"ok":true,"data":{"messages":[{"role":"user","text":"Olá...","created_at":"..."},{"role":"assistant","text":"...","created_at":"..."}]}}

Códigos de erro

400 PARAMS_REQUIRED — `session_id` ou `visitor_id` está em falta.

Comportamento verificado

Uma sessão existente devolve 200 com o histórico de mensagens; parâmetros em falta devolvem 400 `PARAMS_REQUIRED`.

Widget de chat

GET /api/public/widget/healthVerificação simples de disponibilidade do serviço de widget.GET /api/public/widget/config/:widget_codeDevolve a configuração pública de um widget (nome de exibição, mensagem de boas-vindas, design, idioma, função de voz) para a inicialização no navegador.POST /api/public/widget/messageEnvia uma mensagem do visitante ao chatbot e devolve a sua resposta — o endpoint central do widget de chat.POST /api/public/widget/pollObtém mensagens recebidas após um determinado momento — por exemplo, a resposta de um colaborador que assumiu a conversa.POST /api/public/widget/ratingGuarda a avaliação do visitante sobre uma conversa (útil ou não útil).POST /api/public/widget/trackRegista um evento anónimo de utilização do widget (por exemplo, «widget aberto») para as análises no painel.POST /api/public/widget/voice-transcribeConverte uma gravação de voz do visitante em texto (entrada de voz), se a função de voz estiver ativada para o widget.POST /api/public/widget/voice-speakConverte texto em fala (saída de voz no widget), se a função de voz estiver ativada.

Artigos relacionados

← Widget de chat