Salva uma mensagem em uma conversa: cria a conversa se o questionId não for enviado, ou adiciona a mensagem ao histórico se o questionId já existir. Pensado para integrações que orquestram a IA por conta própria e só precisam persistir as mensagens no Inbox/CRM da Mapaprop (diferente de POST /chat, que além disso gera a resposta).
Este endpoint sempre desconta o tokensUsed que você enviar do saldo de tokens de IA da conta (customer_ai_usage), mesmo que você tenha gerado a resposta com seu próprio motor. Se sua integração não consome tokens da Mapaprop, envie tokensUsed: 0. Para salvar passos do fluxo guiado (por exemplo, um clique em um botão) sem afetar o contador de tokens, use POST /thread em vez disso.
| 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/message
Parâmetros
customerId e websiteId são derivados do token de autenticação, não são enviados no body.
| Key | Type | Required | Descrição |
|---|---|---|---|
| message | string | sim | O conteúdo da mensagem. |
| direction | int | sim | 1 = mensagem do visitante, 3 = mensagem da IA. A resolução do remetente (from) só distingue esses dois casos: se você precisar registrar uma mensagem de um atendente humano ou do sistema (direction=2), use POST /thread em vez disso. |
| questionId | int | não | ID da conversa à qual adicionar a mensagem. Se for omitido, uma conversa nova é criada. |
| leadName | string | não | Nome do visitante. Default Visitante. |
| leadEmail | string | não | Email do visitante. Se for enviado e a conversa ainda não tiver contato associado, um contato é criado ou vinculado no CRM. |
| leadPhone | string | não | Telefone do visitante. |
| sourceUrl | string | não | URL da página onde o visitante enviou a mensagem. Só é usado ao criar uma conversa nova (quando questionId não é enviado). |
| sessionId | string | não | Identificador de sessão. Se não for enviado, um UUID é gerado automaticamente. |
| tokensUsed | int | não | Quantidade de tokens de IA a descontar do saldo do cliente por esta mensagem. Default 0. |
| propertiesReferenced | array de int | não | IDs de imóveis referenciados na mensagem. É salvo como metadata da conversa. |
| customerSearch | object | não | Dados de buscas/favoritos/consultas do visitante, usados para enriquecer o contato no CRM. |
Código de exemplo
POST /api/action/mapaprop-chat-ai-v1/message HTTP/1.1
Host: mapaprop.app
Content-Type: application/json
Authorization: Bearer {access_token}
{
"questionId": 481203,
"message": "Sí, tenemos 3 departamentos de 2 ambientes en Palermo.",
"direction": 3,
"tokensUsed": 0
}
Resposta
| Objeto | Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| Response | success | boolean | sim | true quando a mensagem foi salva corretamente. |
| questionId | int | sim | O ID da conversa (o mesmo que você enviou, ou o recém-criado). | |
| tokensUsed | int | sim | O tokensUsed que você enviou na requisição. | |
| totalTokensUsed | int | sim | Total de tokens consumidos pelo cliente no período de faturamento atual, após esta mensagem. | |
| tokensRemaining | int | sim | Tokens de IA restantes no período atual. |
Em caso de erro, não chega o shape acima com success: false: a requisição é cortada com um erro (ver tabela a seguir).
Erros
| Erro | Causa |
|---|---|
QUESTION_NOT_FOUND | O questionId enviado não existe ou não pertence a este cliente. |
SYSTEM_ERROR | Falhou o salvamento da mensagem por outro motivo (por exemplo, erro de banco de dados). |
Erros de validação (a requisição é cortada, não chega success: false)
| Erro | Causa |
|---|---|
REQUIRED_INPUT — "Message is required" | Falta o campo message. |
REQUIRED_INPUT — "Direction is required (1=visitor, 3=AI)" | Falta o campo direction. |
Exemplo de resposta
{
"success": true,
"questionId": 481203,
"tokensUsed": 0,
"totalTokensUsed": 12450,
"tokensRemaining": 87550
}
Exemplo de erro:
{
"success": false,
"error": "QUESTION_NOT_FOUND"
}