> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatnorris.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar mensagem (Chat)

> Enviar uma mensagem a um agente de IA e obter a resposta dele.

# 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](https://docs.chatnorris.ai/pt/guias/modelos-ia-creditos.md)).

```http theme={null}
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](https://docs.chatnorris.ai/pt/api-referencia/agentes/adjuntos.md) e é passado o objeto que ele retorna. Veja [Anexos](#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

```json theme={null}
{
  "message": "Qual é o horário de atendimento?"
}
```

### Exemplo — continuar a conversa

```json theme={null}
{
  "message": "E nos fins de semana?",
  "conversation_id": "conv_abc123"
}
```

### Exemplo — mensagem com anexo

```json theme={null}
{
  "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](https://docs.chatnorris.ai/pt/api-referencia/agentes/adjuntos.md) são processados. O anexo fica salvo na conversa.

***

## Resposta

```json theme={null}
{
  "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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.