POST/api/public/widget/message

Envia uma mensagem do visitante ao chatbot e devolve a sua resposta — o endpoint central do widget de chat.

Envie `widget_code`, `message`, a `visitor_id` e — a partir da segunda mensagem — a `session_id` da resposta anterior. Na primeira chamada de uma nova conversa, deixe `session_id` vazio ou defina-o como `null`. A resposta contém, no objeto `data`, a `session_id`, o texto de resposta `response` e, se aplicável, botões (`buttons`), sugestões de produto (`products`) e o estado da conversa (`state`). 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 a `visitor_id` estiver em falta, o servidor responde 400 `VISITOR_ID_REQUIRED`. A chamada não é idempotente: cada envio cria outra mensagem do visitante e outra resposta. Bloqueie a entrada enquanto um pedido está pendente e não a repita automaticamente.

Visão geral

Chamada: POST /api/public/widget/message. 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 não é idempotente: cada chamada bem-sucedida volta a desencadear a ação. Parâmetros obrigatórios: widget_code (body), message (body), visitor_id (body). Parâmetros opcionais: session_id (body). Casos de erro documentados: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_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: Não

Parâmetros

widget_code(body, string, obrigatório)— Código do widget do seu código de incorporação
message(body, string, obrigatório)— Texto da mensagem do visitante
visitor_id(body, string, obrigatório)— ID de visitante gerado pelo widget e armazenado no navegador
session_id(body, string)— ID de sessão da resposta anterior; vazio ou `null` na primeira chamada de uma nova conversa

Pedido de exemplo

{"widget_code":"...","message":"Olá, o que pode fazer a Zentor App?","visitor_id":"<UUID ou ID gerado pelo cliente>"}

Resposta de exemplo

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

Códigos de erro

401 WIDGET_TOKEN_MISSING — O cabeçalho `X-Widget-Token` está em falta.
401 WIDGET_TOKEN_INVALID — O token de incorporação não corresponde ao código do widget.
400 VISITOR_ID_REQUIRED — O campo `visitor_id` está em falta.

Comportamento verificado

Uma mensagem válida devolve 200 com a resposta do chatbot; um token em falta ou inválido e uma `visitor_id` em falta devolvem os códigos de erro documentados.

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.GET /api/public/widget/historyCarrega o histórico de mensagens anterior de uma conversa do widget, por exemplo após recarregar a página.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