Saves a message in a conversation: creates the conversation if questionId is not sent, or adds the message to the history if questionId already exists. Intended for integrations that orchestrate the AI on their own and only need to persist the messages in Mapaprop's Inbox/CRM (unlike POST /chat, which also generates the response).
This endpoint always deducts the tokensUsed you send from the account's AI token balance (customer_ai_usage), even if you generated the response with your own engine. If your integration doesn't consume Mapaprop tokens, send tokensUsed: 0. To save steps of the guided flow (for example, a click on a button) without touching the token counter, use POST /thread instead.
| Resource information | |
|---|---|
| Authentication | Required (API Token, Bearer) |
| Scope | mapaprop-chat-ai |
| HTTP Method | POST |
| Response | JSON |
| Version | 1 |
Resource URL
https://mapaprop.app/api/action/mapaprop-chat-ai-v1/message
Parameters
customerId and websiteId are derived from the authentication token, they are not sent in the body.
| Key | Type | Required | Description |
|---|---|---|---|
| message | string | yes | The message content. |
| direction | int | yes | 1 = visitor message, 3 = AI message. Sender (from) resolution only distinguishes these two cases: if you need to register a message from a human agent or the system (direction=2), use POST /thread instead. |
| questionId | int | no | ID of the conversation to add the message to. If omitted, a new conversation is created. |
| leadName | string | no | Visitor's name. Default Visitante. |
| leadEmail | string | no | Visitor's email. If sent and the conversation doesn't have an associated contact yet, a contact is created or linked in the CRM. |
| leadPhone | string | no | Visitor's phone number. |
| sourceUrl | string | no | URL of the page where the visitor sent the message. Only used when creating a new conversation (when questionId is not sent). |
| sessionId | string | no | Session identifier. If not sent, a UUID is generated automatically. |
| tokensUsed | int | no | Number of AI tokens to deduct from the customer's balance for this message. Default 0. |
| propertiesReferenced | array of int | no | IDs of properties referenced in the message. Saved as conversation metadata. |
| customerSearch | object | no | Data from the visitor's searches/favorites/inquiries, used to enrich the contact in the CRM. |
Sample code
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
}
Response
| Object | Field | Type | Required | Description |
|---|---|---|---|---|
| Response | success | boolean | yes | true when the message was saved successfully. |
| questionId | int | yes | The conversation ID (the same one you sent, or the newly created one). | |
| tokensUsed | int | yes | The tokensUsed you sent in the request. | |
| totalTokensUsed | int | yes | Total tokens consumed by the customer in the current billing period, after this message. | |
| tokensRemaining | int | yes | AI tokens remaining in the current period. |
In case of error, the shape above with success: false is not returned: the request is cut off with an error (see the following table).
Errors
| Error | Cause |
|---|---|
QUESTION_NOT_FOUND | The questionId sent doesn't exist or doesn't belong to this customer. |
SYSTEM_ERROR | Saving the message failed for another reason (for example, a database error). |
Validation errors (the request is cut off, success: false is not returned)
| Error | Cause |
|---|---|
REQUIRED_INPUT — "Message is required" | The message field is missing. |
REQUIRED_INPUT — "Direction is required (1=visitor, 3=AI)" | The direction field is missing. |
Sample response
{
"success": true,
"questionId": 481203,
"tokensUsed": 0,
"totalTokensUsed": 12450,
"tokensRemaining": 87550
}
Error example:
{
"success": false,
"error": "QUESTION_NOT_FOUND"
}