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

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 and pass the object it returns. See 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

{
  "message": "What are your opening hours?"
}

Example — continue a conversation

{
  "message": "And on weekends?",
  "conversation_id": "conv_abc123"
}

Example — message with an attachment

{
  "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 are processed. The attachment is saved in the conversation.

Response

{
  "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)

Getting started

AI agents

Web widget

Channels

Conversations and live chat

Campaigns

Leads and analytics

Team

Account and settings

Billing

Troubleshooting

FAQ

Glossary

Public API v2

Send message (Chat)

Send message

Path parameters

Request body

Example — first message

Example — continue a conversation

Example — message with an attachment

Attachments

Response

Response fields

`contact_capture`

How context works

Common errors

​Send message

​Path parameters

​Request body

​Example — first message

​Example — continue a conversation

​Example — message with an attachment

​Attachments

​Response

​Response fields

​contact_capture

​How context works

​Common errors

Send message

Path parameters

Request body

Example — first message

Example — continue a conversation

Example — message with an attachment

Attachments

Response

Response fields

`contact_capture`

How context works

Common errors