Registra um sinal implícito de comportamento sobre um turno da conversa: o visitante pediu a resposta novamente (regenerate), copiou a resposta (copy), clicou em um artigo de ajuda citado (citation) ou em um botão sugerido (bridge). Diferente de POST /feedback, é um feedback inferido do comportamento do visitante, não uma avaliação explícita, e nunca abre um caso de moderação.
regenerate e copy têm um sentimento implícito e são salvos como down e up respectivamente. citation e bridge são cliques de simples interação, sem sentimento próprio: são salvos sem rating forçado.
| Informação do recurso | |
|---|---|
| Autenticação | Obrigatória (Token de API, Bearer) |
| Scope | mapaprop-chat-ai |
| HTTP Method | POST |
| Response | JSON |
| Version | 1 |
URL do recurso
https://mapaprop.app/api/action/mapaprop-chat-ai-v1/signal
Parâmetros
| Key | Type | Required | Descrição |
|---|---|---|---|
| turnId | long | sim | ID do turno sobre o qual se registra o sinal. Vem na resposta de POST /chat (campo turnId) ou no evento SSE done de POST /chat/stream. Precisa pertencer à conta do token. |
| kind | string | sim | regenerate, copy, citation ou bridge. |
Código de exemplo
POST /api/action/mapaprop-chat-ai-v1/signal HTTP/1.1
Host: mapaprop.app
Content-Type: application/json
Authorization: Bearer {access_token}
{
"turnId": 481512,
"kind": "regenerate"
}
Resposta
| Objeto | Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| Response | success | boolean | sim | true quando o sinal foi registrado corretamente. |
| turnId | long | sim | O turnId que você enviou. | |
| kind | string | sim | O kind que você enviou. |
Em caso de erro, não chega o shape acima com success: false: a requisição é cortada com um erro (ver tabelas a seguir).
Erros
| Erro | Causa |
|---|---|
INVALID_PERMISSION (HTTP 403) | O turnId enviado não existe, ou pertence à conversa de outra conta. |
Erros de validação (a requisição é cortada, não chega success: false)
| Erro | Causa |
|---|---|
REQUIRED_INPUT — "El campo 'turnId' es requerido" | Falta o campo turnId, ou ele é menor ou igual a 0. |
REQUIRED_INPUT — "El campo 'kind' es requerido (regenerate, copy, citation o bridge)" | Falta o campo kind, ou seu valor não é um dos permitidos. |
Exemplo de resposta
{
"success": true,
"turnId": 481512,
"kind": "regenerate"
}
Exemplo de erro:
{
"success": false,
"error": "INVALID_PERMISSION"
}