POST Conversar com o Assistente
Conversa com o assistente do PEP, que consulta e cria dados pelas ferramentas (tools) do MCP em nome do usuário. O cliente envia a conversa inteira a cada chamada (da mais antiga à mais nova; a última mensagem é do usuário); nada fica guardado no servidor. Aceita JSON puro ou multipart/form-data com anexos (imagem, PDF ou áudio), que só passam pelo modelo e não são gravados.
Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.
Não exige @CheckPermissions — basta estar autenticado.
O assistente usa o token do próprio usuário para chamar o MCP, então API Key não é aceita: a rota responde 403.
Cada pergunta custa chamadas ao modelo, por isso a rota tem limite próprio de 10 requisições por minuto (abaixo do limite global). Acima disso, 429.
Criar agendamento ou orçamento só acontece depois da confirmação do usuário, verificada no servidor. Quando a resposta pede a confirmação, vem o campo confirmation.
Endpoint
POST https://api-dev.imagemais.com.br/api/mcp-chat/messages
Corpo da Requisição
| Campo | Tipo | Obrigatório | Valores válidos | Descrição |
|---|---|---|---|---|
messages | object[] | ✅ | de 1 a 30 itens; a última com role: user | Conversa inteira. No multipart/form-data, envie como texto JSON |
messages[].role | string | ✅ | user ou assistant | Autor da mensagem |
messages[].content | string | ✅ | até 4000 caracteres; não vazio | Texto da mensagem |
model | string | ❌ | até 100 caracteres; um de GET /mcp-chat/models | Modelo da conversa. Fora da lista, usa o padrão e avisa em notice |
files | file[] | ❌ | multipart; até 10 arquivos | Anexos da pergunta atual (o campo antigo image, com uma imagem, também é aceito) |
Anexos (campo files, só em multipart/form-data):
| Tipo | Formatos | Limite por arquivo |
|---|---|---|
| Imagem | JPG, PNG, GIF, WebP | 5 MB |
| 10 MB | ||
| Áudio | MP3, WAV, M4A, WebM, OGG, FLAC | 20 MB |
No máximo 10 arquivos por mensagem e 32 MB somados. O tipo é conferido pelo conteúdo real do arquivo (trocar a extensão não passa). Áudios são transcritos. Os anexos valem só para a pergunta atual: não são reenviados nas seguintes.
Requisição
curl -X 'POST' \
'https://api-dev.imagemais.com.br/api/mcp-chat/messages' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"role": "user",
"content": "Quais agendamentos do Dr. Nome Exemplo estão marcados para amanhã?"
}
],
"model": "gpt-4o-mini"
}'
Respostas
200 Sucesso
{
"message": {
"role": "assistant",
"content": "Amanhã o Dr. Nome Exemplo tem 3 agendamentos: 08:00, 08:30 e 09:15."
},
"tools": [
{
"name": "listar_agendamentos",
"ok": true
}
],
"model": "gpt-4o-mini"
}
tools lista as ferramentas usadas para chegar à resposta (ok: false e error quando uma falhou). notice aparece quando o modelo pedido não está disponível e o padrão foi usado. confirmation ({ "tool": "criar_agendamento" } ou { "tool": "criar_orcamento" }) aparece só quando a resposta pede ao usuário que confirme uma criação.
400 Requisição inválida
Mensagens possíveis, além das de validação de messages e model:
A última mensagem da conversa deve ser do usuário.Envie no máximo 10 arquivos por mensagem.Os arquivos somam mais de 32 MB. Envie menos arquivos por vez.Os arquivos precisam ser imagem (JPG, PNG, GIF, WebP), PDF ou áudio (MP3, WAV, M4A, WebM, OGG, FLAC).O arquivo passa do limite de {5|10|20} MB para {imagem|PDF|áudio}.Anexe os arquivos no campo "files".
{
"message": "A última mensagem da conversa deve ser do usuário.",
"error": "Bad Request",
"statusCode": 400
}
403 Sem permissão
Retornado quando a chamada usa API Key (ou não traz o token Bearer de usuário).
{
"message": "O assistente só está disponível para usuários logados.",
"error": "Forbidden",
"statusCode": 403
}
413 Corpo grande demais
{
"message": "Os arquivos somam mais de 32 MB. Envie menos arquivos por vez.",
"error": "Payload Too Large",
"statusCode": 413
}
429 Limite de uso
Mais de 10 requisições por minuto.
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}
502 Falha no modelo ou na transcrição
Mensagens possíveis: Não foi possível obter a resposta do assistente. e Não foi possível transcrever o áudio. Tente novamente ou envie outro arquivo.
{
"message": "Não foi possível obter a resposta do assistente.",
"error": "Bad Gateway",
"statusCode": 502
}
503 Assistente indisponível
Mensagens possíveis: O assistente não está configurado neste ambiente., O assistente recusou a sua sessão. Entre novamente., O assistente está indisponível no momento. e O assistente está sobrecarregado. Tente novamente em instantes.
{
"message": "O assistente está indisponível no momento.",
"error": "Service Unavailable",
"statusCode": 503
}