Enviar mensagem

Envia uma mensagem a um agente e recebe a resposta gerada com IA usando a base de conhecimento do agente. Cada chamada consome créditos de IA do seu plano; a quantidade depende do modelo do agente (veja Modelos de IA e créditos).

POST https://app.chatnorris.ai/api/v2/chatbots/{chatbot_id}/chat
Authorization: Bearer <sua_api_key>
Content-Type: application/json

Escopo necessário: chat:write

Path parameters

Parâmetro	Tipo	Descrição
`chatbot_id`	string	ID do agente ao qual a mensagem é enviada

Corpo da request

Campo	Tipo	Obrigatório	Descrição
`message`	string	✅	Texto da mensagem (1–4000 caracteres)
`conversation_id`	string	—	UUID de uma conversa existente para continuar o histórico. Se for omitido, uma conversa nova é criada.
`attachment`	object	—	Imagem ou PDF anexado à mensagem. É enviado antes com Enviar anexo e é passado o objeto que ele retorna. Veja Anexos.
`attachment.url`	string	✅ (se `attachment` for enviado)	URL retornada pelo endpoint de anexos (máx. 1000 caracteres)
`attachment.name`	string	—	Nome do arquivo (máx. 200 caracteres)
`attachment.type`	string	—	Tipo do arquivo, por exemplo `image/png` ou `application/pdf` (máx. 100 caracteres)

Exemplo — primeira mensagem

{
  "message": "Qual é o horário de atendimento?"
}

Exemplo — continuar a conversa

{
  "message": "E nos fins de semana?",
  "conversation_id": "conv_abc123"
}

Exemplo — mensagem com anexo

{
  "message": "O que este documento diz sobre a garantia?",
  "attachment": {
    "url": "https://<projeto>.supabase.co/storage/v1/object/public/chat-attachments/...",
    "name": "garantia.pdf",
    "type": "application/pdf"
  }
}

Anexos

É aceito um anexo por mensagem: imagem PNG, JPEG, WebP ou GIF (até 5 MB) ou PDF (até 15 MB). O campo message continua obrigatório.

Imagens: o agente as vê se o modelo dele aceitar imagens. Caso contrário, ele sabe que houve um anexo que não conseguiu ver e pode pedir que ele seja descrito.
PDF: dependendo do modelo, o agente lê o documento completo ou o texto extraído do PDF. Um PDF digitalizado sem texto selecionável pode não ser legível para alguns modelos.

Apenas arquivos enviados com Enviar anexo são processados. O anexo fica salvo na conversa.

Resposta

{
  "status": "success",
  "data": {
    "reply": "Nosso horário de atendimento é de segunda a sexta, das 9h às 18h.",
    "conversation_id": "conv_abc123",
    "contact_capture": null
  }
}

Campos da resposta

Campo	Tipo	Descrição
`reply`	string	Resposta gerada pelo agente
`conversation_id`	string	ID da conversa (nova ou existente). Use-o nas próximas chamadas para manter o contexto.
`contact_capture`	object \| null	Estado da captura de dados de contato neste turno, ou `null` se não houver novidade. Veja abaixo.

`contact_capture`

Campo	Tipo	Descrição
`state`	string	`form_requested` (é o momento de pedir os dados de um formulário de contato), `confirmation_required` (o agente pede para confirmar dados detectados) ou `confirmed` (os dados do contato foram confirmados)
`action_id`	string	Apenas com `form_requested`: ID da ação de formulário de contato
`requested_fields`	array	Campos envolvidos. Com `form_requested`, cada um traz `key`, `label`, `required` e, se já for conhecido, `prefill`. Com `confirmation_required`, cada um traz apenas `key`. Com `confirmed`, a lista vem vazia.

Como o contexto funciona

Cada request que inclui o mesmo conversation_id mantém o histórico das últimas 10 mensagens da conversa. Isso permite conversas coerentes com vários turnos. Sem conversation_id, cada chamada é uma conversa independente, sem contexto anterior.

Erros comuns

Code	Descrição
`INVALID_INPUT`	A mensagem ultrapassa 4000 caracteres ou o `conversation_id` não é um UUID válido
`INSUFFICIENT_SCOPE`	A API key não tem o scope `chat:write`
`NOT_FOUND`	O agente não existe, está inativo ou a conversa não pertence a este agente
`PLAN_LIMIT_REACHED`	O limite mensal de créditos de IA do plano foi atingido (ou o teto de créditos próprio do agente, se houver um configurado)

Primeiros passos

Agentes de IA

Widget web

Canais

Conversas e chat ao vivo

Campanhas

Leads e análises

Equipe

Conta e configurações

Faturamento

Solução de problemas

Perguntas frequentes

Glossário

API pública v2

Enviar mensagem (Chat)

Enviar mensagem

Path parameters

Corpo da request

Exemplo — primeira mensagem

Exemplo — continuar a conversa

Exemplo — mensagem com anexo

Anexos

Resposta

Campos da resposta

`contact_capture`

Como o contexto funciona

Erros comuns

​Enviar mensagem

​Path parameters

​Corpo da request

​Exemplo — primeira mensagem

​Exemplo — continuar a conversa

​Exemplo — mensagem com anexo

​Anexos

​Resposta

​Campos da resposta

​contact_capture

​Como o contexto funciona

​Erros comuns

Enviar mensagem

Path parameters

Corpo da request

Exemplo — primeira mensagem

Exemplo — continuar a conversa

Exemplo — mensagem com anexo

Anexos

Resposta

Campos da resposta

`contact_capture`

Como o contexto funciona

Erros comuns