Inicia una conversación nueva: crea la conversación con los datos de contacto del visitante y guarda el mensaje de bienvenida como primer mensaje. Devuelve el questionId que hay que reenviar en las llamadas siguientes a POST /chat, POST /chat/stream, POST /message o POST /thread.
Este endpoint NO consume tokens de IA. Es el punto de entrada recomendado antes de mandar el primer mensaje del visitante, porque es la única forma confiable de obtener un questionId (la respuesta de POST /chat no lo incluye — ver la nota en esa página).
| Información del recurso | |
|---|---|
| Autenticación | Requerida (Token de API, Bearer) |
| Scope | mapaprop-chat-ai |
| HTTP Method | POST |
| Response | JSON |
| Version | 1 |
URL del recurso
https://mapaprop.app/api/action/mapaprop-chat-ai-v1/init
Parámetros
customerId y websiteId se derivan del token de autenticación, no se envían en el body.
| Key | Type | Required | Descripción |
|---|---|---|---|
| leadName | string | sí | Nombre del visitante. Se trunca a 100 caracteres. |
| leadEmail | string | sí | Email del visitante. Se trunca a 100 caracteres. Si es un email válido no vacío, se crea o vincula un contacto en el CRM del cliente desde el inicio de la conversación. |
| leadPhone | string | sí | Teléfono del visitante. Se trunca a 20 caracteres. |
| sourceUrl | string | no | URL de la página donde el visitante inició la conversación. |
| welcomeMessage | string | no | Mensaje de bienvenida a usar en lugar del configurado por el cliente. Si no se envía, se resuelve el mensaje de bienvenida configurado en la cuenta (customer_ai_config); si el cliente no configuró ninguno, se usa el genérico "Hola! En que puedo ayudarte hoy?". |
Código de ejemplo
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"
}
Respuesta
| Objeto | Campo | Tipo | Requerido | Descripción |
|---|---|---|---|---|
| Response | success | boolean | sí | true cuando la conversación se creó correctamente. |
| questionId | int | sí | El ID de la conversación. Guardalo y reenvialo en cada llamada posterior. | |
| sessionId | string | sí | Identificador de sesión generado automáticamente para esta conversación. | |
| welcomeMessage | string | sí | El texto de bienvenida efectivamente guardado como primer mensaje. |
En caso de error, no llega {"success": false}: la request se corta con un error (ver tabla siguiente).
Errores
| Error | Causa |
|---|---|
SYSTEM_ERROR | Falló la creación/persistencia de la conversación (por ejemplo, error de base de datos). |
Errores de validación (se corta la request, no llega success: false)
| Error | Causa |
|---|---|
REQUIRED_INPUT — "leadName is required" | Falta el campo leadName. |
REQUIRED_INPUT — "leadEmail is required" | Falta el campo leadEmail. |
REQUIRED_INPUT — "leadPhone is required" | Falta el campo leadPhone. |
Ejemplo de respuesta
{
"success": true,
"questionId": 481203,
"sessionId": "b6d1c6b0-2f2a-4e2e-9a4a-8e0a2a2f2a11",
"welcomeMessage": "Hola Juan! Soy el asistente virtual de la inmobiliaria. ¿En qué puedo ayudarte?"
}