Starts a new conversation: creates the conversation with the visitor's contact data and saves the welcome message as the first message. Returns the questionId that must be resent in the following calls to POST /chat, POST /chat/stream, POST /message or POST /thread.
This endpoint does NOT consume AI tokens. It's the recommended entry point before sending the visitor's first message, because it's the only reliable way to get a questionId (the POST /chat response does not include it — see the note on that page).
| 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/init
Parameters
customerId and websiteId are derived from the authentication token, they are not sent in the body.
| Key | Type | Required | Description |
|---|---|---|---|
| leadName | string | yes | Visitor's name. Truncated to 100 characters. |
| leadEmail | string | yes | Visitor's email. Truncated to 100 characters. If it's a valid non-empty email, a contact is created or linked in the customer's CRM from the start of the conversation. |
| leadPhone | string | yes | Visitor's phone number. Truncated to 20 characters. |
| sourceUrl | string | no | URL of the page where the visitor started the conversation. |
| welcomeMessage | string | no | Welcome message to use instead of the one configured by the customer. If not sent, the welcome message configured on the account (customer_ai_config) is resolved; if the customer didn't configure one, the generic "Hola! En que puedo ayudarte hoy?" is used. |
Sample code
POST /api/action/mapaprop-chat-ai-v1/init HTTP/1.1
Host: mapaprop.app
Content-Type: application/json
Authorization: Bearer {access_token}
{
"leadName": "Juan Pérez",
"leadEmail": "juan@example.com",
"leadPhone": "+54 9 11 5555-5555",
"sourceUrl": "https://tuapp.com/propiedades"
}
Response
| Object | Field | Type | Required | Description |
|---|---|---|---|---|
| Response | success | boolean | yes | true when the conversation was created successfully. |
| questionId | int | yes | The conversation ID. Save it and resend it on every subsequent call. | |
| sessionId | string | yes | Session identifier automatically generated for this conversation. | |
| welcomeMessage | string | yes | The welcome text actually saved as the first message. |
In case of error, {"success": false} is not returned: the request is cut off with an error (see the following table).
Errors
| Error | Cause |
|---|---|
SYSTEM_ERROR | The conversation creation/persistence failed (for example, a database error). |
Validation errors (the request is cut off, success: false is not returned)
| Error | Cause |
|---|---|
REQUIRED_INPUT — "leadName is required" | The leadName field is missing. |
REQUIRED_INPUT — "leadEmail is required" | The leadEmail field is missing. |
REQUIRED_INPUT — "leadPhone is required" | The leadPhone field is missing. |
Sample response
{
"success": true,
"questionId": 481203,
"sessionId": "b6d1c6b0-2f2a-4e2e-9a4a-8e0a2a2f2a11",
"welcomeMessage": "Hola Juan! Soy el asistente virtual de la inmobiliaria. ¿En qué puedo ayudarte?"
}