Inicia uma conversa nova: cria a conversa com os dados de contato do visitante e salva a mensagem de boas-vindas como primeira mensagem. Retorna o questionId que deve ser reenviado nas chamadas seguintes a POST /chat, POST /chat/stream, POST /message ou POST /thread.
Este endpoint NÃO consome tokens de IA. É o ponto de entrada recomendado antes de enviar a primeira mensagem do visitante, porque é a única forma confiável de obter um questionId (a resposta do POST /chat não o inclui — ver a nota nessa página).
| Informação do recurso | |
|---|---|
| Autenticação | Obrigatória (Token de API, Bearer) |
| Scope | mapaprop-chat-ai |
| HTTP Method | POST |
| Response | JSON |
| Version | 1 |
URL do recurso
https://mapaprop.app/api/action/mapaprop-chat-ai-v1/init
Parâmetros
customerId e websiteId são derivados do token de autenticação, não são enviados no body.
| Key | Type | Required | Descrição |
|---|---|---|---|
| leadName | string | sim | Nome do visitante. É truncado para 100 caracteres. |
| leadEmail | string | sim | Email do visitante. É truncado para 100 caracteres. Se for um email válido e não vazio, um contato é criado ou vinculado no CRM do cliente desde o início da conversa. |
| leadPhone | string | sim | Telefone do visitante. É truncado para 20 caracteres. |
| sourceUrl | string | não | URL da página onde o visitante iniciou a conversa. |
| welcomeMessage | string | não | Mensagem de boas-vindas a usar no lugar da configurada pelo cliente. Se não for enviada, a mensagem de boas-vindas configurada na conta é resolvida (customer_ai_config); se o cliente não configurou nenhuma, é usada a genérica "Hola! En que puedo ayudarte hoy?". |
Código de exemplo
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"
}
Resposta
| Objeto | Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| Response | success | boolean | sim | true quando a conversa foi criada corretamente. |
| questionId | int | sim | O ID da conversa. Salve-o e reenvie-o em cada chamada posterior. | |
| sessionId | string | sim | Identificador de sessão gerado automaticamente para esta conversa. | |
| welcomeMessage | string | sim | O texto de boas-vindas efetivamente salvo como primeira mensagem. |
Em caso de erro, não chega {"success": false}: a requisição é cortada com um erro (ver tabela a seguir).
Erros
| Erro | Causa |
|---|---|
SYSTEM_ERROR | Falhou a criação/persistência da conversa (por exemplo, erro de banco de dados). |
Erros de validação (a requisição é cortada, não chega success: false)
| Erro | Causa |
|---|---|
REQUIRED_INPUT — "leadName is required" | Falta o campo leadName. |
REQUIRED_INPUT — "leadEmail is required" | Falta o campo leadEmail. |
REQUIRED_INPUT — "leadPhone is required" | Falta o campo leadPhone. |
Exemplo de resposta
{
"success": true,
"questionId": 481203,
"sessionId": "b6d1c6b0-2f2a-4e2e-9a4a-8e0a2a2f2a11",
"welcomeMessage": "Hola Juan! Soy el asistente virtual de la inmobiliaria. ¿En qué puedo ayudarte?"
}