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

# Add a message

> POST /v1/conversations/{id}/messages — add one customer or chatbot message to a ticket's conversation

Adds one message to a ticket's primary conversation: a line from the customer or a reply from your own bot. See [Bring your own chatbot](https://docs.replyful.com/api-reference/own-chatbot.md) for the full flow.

```http theme={null}
POST /v1/conversations/{id}/messages
```

## Authentication

A **Read & write** live key. See [Authentication](https://docs.replyful.com/api-reference/authentication.md).

## Path parameters

**id** `string` *required*

Conversation ID prefixed with `conv_`. Use the conversation with `role: "primary"` from the ticket.

## Body

**role** `string` *required*

`user` (the customer) or `assistant` (your bot).

**content** `string` *required*

Plain text, up to 20,000 characters.

## Response

`201` with the [`Message` object](https://docs.replyful.com/api-reference/conversations/messages). A message from your bot has `role: "assistant"` and `author: null`.

## Example

```bash curl theme={null}
curl https://api.replyful.com/v1/conversations/conv_4tGh7Kq2Lm9Zx1B/messages \
  -H "Authorization: Bearer rfl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e3c1e-2f0a-4c57-9d51-8a1f6f1f3a10" \
  -d '{ "role": "assistant", "content": "Your invoice was updated on 3 November." }'
```

```json Response theme={null}
{
  "id": "msg_2Hq8Lw5nTz3KcR7yVb1Xd0",
  "object": "message",
  "conversationId": "conv_4tGh7Kq2Lm9Zx1B",
  "type": "chat",
  "role": "assistant",
  "author": null,
  "content": "Your invoice was updated on 3 November.",
  "language": null,
  "attachments": [],
  "createdAt": "2026-11-10T09:15:11.000Z",
  "updatedAt": "2026-11-10T09:15:11.000Z"
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| `404` | `conversation_not_found` | The conversation does not exist or belongs to another organization. |
| `409` | `conversation_handed_over` | A person handles the ticket now. Only `user` messages are accepted. |
| `422` | `conversation_not_writable` | Not the primary conversation of a ticket that started on a chat channel. |


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