BETA

Mapaprop Chat AI API

API para integrar o Chat AI da Mapaprop —o assistente imobiliário com IA que qualifica leads e busca imóveis em linguagem natural— nas suas próprias aplicações e canais: sites próprios, apps mobile, WhatsApp e outras plataformas de mensagens.

BETA. O motor de IA está testado em produção (é o mesmo que usa o Chat AI dos sites Mapaprop), mas esta superfície de API OAuth está em BETA: o contrato dos endpoints pode mudar e ainda não tem limite de uso (rate limiting) definido. Integre com essa expectativa. Escreva para dev@mapaprop.com se for integrar, para que possamos avisar sobre qualquer mudança.

O motor já opera em produção dentro do ecossistema Mapaprop: entende consultas em linguagem natural, busca no inventário real do cliente por meio de busca semântica, responde com imóveis concretos e captura os dados do interessado como lead qualificado. Os leads gerados ficam na conta Mapaprop do cliente, integrados ao seu Inbox e CRM.

Modos de integração

Full Stack. Sua aplicação envia as mensagens do visitante e a Mapaprop orquestra tudo: a IA, a busca no inventário e a geração da resposta. Você recebe a resposta pronta para exibir. É o modo mais simples de integrar e é o que esta documentação cobre.

Autenticação

Esta API funciona com seu Token de API da Mapaprop, não com o registro de app OAuth2 de terceiros. Se você já é cliente Mapaprop Business, ativa seu token com um clique a partir da sua conta —Configurações > API Token— e o usa como Authorization: Bearer {token}. O token não expira (a menos que você o regenere ou o desative). Guia passo a passo: MapapropChatAi API Token.

Não é preciso registrar nenhuma aplicação nem pedir autorização: o token é self-service para clientes com plano Business. O fluxo OAuth2 de Primeiros passos é para portais e terceiros (Feeds/Customer/Network/Property API), não para esta API.

Todos os endpoints exigem o scope mapaprop-chat-ai (incluído no seu token se você tiver Business). A identidade da conta (customerId / websiteId) é derivada do token, não é enviada como parâmetro: cada token opera sobre o inventário e os leads da conta Mapaprop à qual pertence.

Se sua integração roda no browser (webapp serverless), ative o scope CORS na mesma tela. Ver CORS (cross-origin).

Fluxo básico

Inicie a conversa com POST /init. Retorna o questionId (o identificador da conversa) e a mensagem de boas-vindas configurada. Não consome tokens de IA.
Envie cada mensagem do visitante com POST /chat (resposta completa) ou POST /chat/stream (resposta em streaming SSE), reenviando sempre o questionId. Esses endpoints consomem tokens de IA da conta do cliente.
Persista os passos do fluxo guiado (botões Venda/Aluguel, etc.) com POST /thread e mensagens avulsas com POST /message. Não invocam IA.
Os dados do visitante (nome, email, telefone) que você enviar na conversa se transformam em um lead qualificado no CRM do cliente.

Cada resposta de POST /chat e POST /chat/stream inclui o questionId da conversa. Salve-o e reenvie-o no próximo turno para manter o fio da conversa. POST /init é útil quando você quer criar a conversa e mostrar a mensagem de boas-vindas antes da primeira mensagem do visitante.

Endpoints

Disponibilidade

Incluída no plano Mapaprop Business. O scope mapaprop-chat-ai é adicionado ao seu Token de API quando sua conta tem Business ativo.
É self-service: não exige registro de app, nem client_secret, nem aprovação prévia.

Como ativar seu token

Entre em Configurações > API Token na sua conta Mapaprop.
Pressione Ativar e copie o token (um único passo).
Use-o como Authorization: Bearer {token} nas chamadas a esta API.

Guia com capturas de tela: MapapropChatAi API Token. Se você ainda não tem o plano Business, pode contratá-lo pela sua conta.