> ## 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.

# Send message (Chat)

> Send a message to an AI agent and get its reply.

# Send message

Sends a message to an agent and receives its AI-generated reply using the agent's knowledge base. Each call consumes AI credits from your plan; the amount depends on the agent's model (see [AI models and credits](https://docs.chatnorris.ai/en/guias/modelos-ia-creditos.md)).

```http theme={null}
POST https://app.chatnorris.ai/api/v2/chatbots/{chatbot_id}/chat
Authorization: Bearer <your_api_key>
Content-Type: application/json
```

**Required scope:** `chat:write`

***

## Path parameters

| Parameter | Type | Description |
| - | - | - |
| `chatbot_id` | string | ID of the agent the message is sent to |

***

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `message` | string | ✅ | Message text (1–4000 characters) |
| `conversation_id` | string | — | UUID of an existing conversation to continue the thread. If omitted, a new conversation is created. |
| `attachment` | object | — | Image or PDF attached to the message. Upload it first with [Upload attachment](https://docs.chatnorris.ai/en/api-referencia/agentes/adjuntos.md) and pass the object it returns. See [Attachments](#attachments). |
| `attachment.url` | string | ✅ (if `attachment` is sent) | URL returned by the attachments endpoint (max. 1000 characters) |
| `attachment.name` | string | — | File name (max. 200 characters) |
| `attachment.type` | string | — | File type, for example `image/png` or `application/pdf` (max. 100 characters) |

### Example — first message

```json theme={null}
{
  "message": "What are your opening hours?"
}
```

### Example — continue a conversation

```json theme={null}
{
  "message": "And on weekends?",
  "conversation_id": "conv_abc123"
}
```

### Example — message with an attachment

```json theme={null}
{
  "message": "What does this document say about the warranty?",
  "attachment": {
    "url": "https://<project>.supabase.co/storage/v1/object/public/chat-attachments/...",
    "name": "warranty.pdf",
    "type": "application/pdf"
  }
}
```

***

## Attachments

One attachment per message is supported: a PNG, JPEG, WebP or GIF image (up to 5 MB) or a PDF (up to 15 MB). The `message` field is still required.

* **Images:** the agent sees them if its model supports images. If not, it knows there was an attachment it couldn't see and may ask for it to be described.
* **PDF:** depending on the model, the agent reads the full document or the text extracted from the PDF. A scanned PDF without selectable text may not be readable for some models.

Only files uploaded with [Upload attachment](https://docs.chatnorris.ai/en/api-referencia/agentes/adjuntos.md) are processed. The attachment is saved in the conversation.

***

## Response

```json theme={null}
{
  "status": "success",
  "data": {
    "reply": "Our opening hours are Monday to Friday from 9:00 to 18:00.",
    "conversation_id": "conv_abc123",
    "contact_capture": null
  }
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `reply` | string | Reply generated by the agent |
| `conversation_id` | string | Conversation ID (new or existing). Use it in later calls to keep the context. |
| `contact_capture` | object \| null | Status of contact data capture in this turn, or `null` if nothing changed. See below. |

### `contact_capture`

| Field | Type | Description |
| - | - | - |
| `state` | string | `form_requested` (it's time to ask for the data of a contact form), `confirmation_required` (the agent asks to confirm detected data) or `confirmed` (the contact data was confirmed) |
| `action_id` | string | Only with `form_requested`: ID of the contact form action |
| `requested_fields` | array | Fields involved. With `form_requested`, each one has `key`, `label`, `required` and, if already known, `prefill`. With `confirmation_required`, each one has only `key`. With `confirmed`, the list is empty. |

***

## How context works

Each request that includes the same `conversation_id` keeps the history of the conversation's last 10 messages. This enables coherent multi-turn conversations.

Without `conversation_id`, each call is an independent conversation with no previous context.

***

## Common errors

| Code | Description |
| - | - |
| `INVALID_INPUT` | The message exceeds 4000 characters or the `conversation_id` isn't a valid UUID |
| `INSUFFICIENT_SCOPE` | The API key doesn't have the `chat:write` scope |
| `NOT_FOUND` | The agent doesn't exist, is inactive, or the conversation doesn't belong to this agent |
| `PLAN_LIMIT_REACHED` | The plan's monthly AI credit limit was reached (or the agent's own credit cap, if it has one configured) |


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