Skip to main content

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.

Autenticação necessária

Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.

Sem permissão específica

Não exige @CheckPermissions — basta estar autenticado.

Só token de usuário

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.

Limite de uso

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.

Criação de dados exige confirmação

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​

CampoTipoObrigatórioValores válidosDescrição
messagesobject[]✅de 1 a 30 itens; a última com role: userConversa inteira. No multipart/form-data, envie como texto JSON
messages[].rolestring✅user ou assistantAutor da mensagem
messages[].contentstring✅até 4000 caracteres; não vazioTexto da mensagem
modelstring❌até 100 caracteres; um de GET /mcp-chat/modelsModelo da conversa. Fora da lista, usa o padrão e avisa em notice
filesfile[]❌multipart; até 10 arquivosAnexos da pergunta atual (o campo antigo image, com uma imagem, também é aceito)

Anexos (campo files, só em multipart/form-data):

TipoFormatosLimite por arquivo
ImagemJPG, PNG, GIF, WebP5 MB
PDFPDF10 MB
ÁudioMP3, WAV, M4A, WebM, OGG, FLAC20 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
}