BETA

Mapaprop Chat AI API

API para integrar el Chat AI de Mapaprop —el asistente inmobiliario con IA que califica leads y busca propiedades en lenguaje natural— en tus propias aplicaciones y canales: sitios web propios, apps móviles, WhatsApp y otras plataformas de mensajería.

BETA. El motor de IA está probado en producción (es el mismo que usa el Chat AI de los sitios Mapaprop), pero esta superficie de API OAuth está en BETA: el contrato de los endpoints puede cambiar y todavía no tiene límite de uso (rate limiting) definido. Integrala con esa expectativa. Escribinos a dev@mapaprop.com si vas a integrar, así te avisamos de cualquier cambio.

El motor ya opera en producción dentro del ecosistema Mapaprop: entiende consultas en lenguaje natural, busca sobre el inventario real del cliente mediante búsqueda semántica, responde con propiedades concretas y captura los datos del interesado como lead calificado. Los leads generados quedan en la cuenta Mapaprop del cliente, integrados a su Inbox y CRM.

Modos de integración

Full Stack. Tu aplicación envía los mensajes del visitante y Mapaprop orquesta todo: la IA, la búsqueda sobre el inventario y la generación de la respuesta. Recibís la respuesta lista para mostrar. Es el modo más simple de integrar y es el que cubre esta documentación.

Autenticación

Esta API funciona con tu Token de API de Mapaprop, no con el registro de app OAuth2 de terceros. Si ya sos cliente Mapaprop Business, activás tu token con un clic desde tu cuenta —Configuración > API Token— y lo usás como Authorization: Bearer {token}. El token no expira (salvo que lo regeneres o lo desactives). Guía paso a paso: MapapropChatAi API Token.

No hace falta registrar ninguna aplicación ni pedir autorización: el token es self-service para clientes con plan Business. El flujo OAuth2 de Primeros pasos es para portales y terceros (Feeds/Customer/Network/Property API), no para esta API.

Todos los endpoints requieren el scope mapaprop-chat-ai (incluido en tu token si tenés Business). La identidad de la cuenta (customerId / websiteId) se deriva del token, no se envía como parámetro: cada token opera sobre el inventario y los leads de la cuenta Mapaprop a la que pertenece.

Si tu integración corre en el browser (webapp serverless), activá el scope CORS desde la misma pantalla. Ver CORS (cross-origin).

Flujo básico

Iniciá la conversación con POST /init. Devuelve el questionId (el identificador de la conversación) y el mensaje de bienvenida configurado. No consume tokens de IA.
Enviá cada mensaje del visitante con POST /chat (respuesta completa) o POST /chat/stream (respuesta en streaming SSE), reenviando siempre el questionId. Estos endpoints consumen tokens de IA de la cuenta del cliente.
Persistí los pasos del flujo guiado (botones Venta/Alquiler, etc.) con POST /thread y mensajes sueltos con POST /message. No invocan IA.
Los datos del visitante (nombre, email, teléfono) que envíes en la conversación se convierten en un lead calificado en el CRM del cliente.
Opcional — feedback de calidad: cada respuesta de POST /chat y POST /chat/stream trae un turnId. Si tu interfaz ofrece 👍/👎, enviá POST /feedback con ese turnId; las señales implícitas (regenerar, copiar) van por POST /signal. Ayuda a Mapaprop a mejorar el asistente.

Cada respuesta de POST /chat y POST /chat/stream incluye el questionId de la conversación (guardalo y reenvialo en el siguiente turno para mantener el hilo) y el turnId de esa respuesta puntual (para poder darle feedback). POST /init es útil cuando querés crear la conversación y mostrar el mensaje de bienvenida antes del primer mensaje del visitante.

Endpoints

Disponibilidad

Incluida en el plan Mapaprop Business. El scope mapaprop-chat-ai se agrega a tu Token de API cuando tu cuenta tiene Business activo.
Es self-service: no requiere registro de app, ni client_secret, ni aprobación previa.

Cómo activar tu token

Entrá a Configuración > API Token en tu cuenta Mapaprop.
Presioná Activar y copiá el token (un solo paso).
Usalo como Authorization: Bearer {token} en las llamadas a esta API.

Guía con capturas: MapapropChatAi API Token. Si aún no tenés plan Business, podés contratarlo desde tu cuenta.