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

# Messages and attachments

> Send customer messages, attach files, and read the whole conversation back.

## Send a message

[`POST /conversations/{conversationId}/messages`](/api-reference/messages/send-a-message) adds a message **from the customer**.

```bash
curl https://api.usecerium.com/v1/conversations/thr_01k9z3m4q8/messages \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Here is the receipt.",
    "idempotencyKey": "order-1042-msg-2",
    "attachments": [
      {
        "url": "https://files.example.com/receipts/1042.pdf",
        "fileName": "receipt-1042.pdf",
        "mimeType": "application/pdf",
        "size": 48213
      }
    ]
  }'
```

| Field | Rules |
| - | - |
| `body` | Required. 1 to 20,000 characters. Surrounding whitespace is trimmed. |
| `idempotencyKey` | Optional, up to 64 characters. [Recommended.](/guides/idempotency.md) |
| `attachments` | Optional, up to 10. |

Returns **`201`** when the message is added, or **`200`** when the `idempotencyKey` was already used.

## Attachments

Cerium does not host the file. You upload it to your own storage and send its address.

| Field | Rules |
| - | - |
| `url` | Required. An `https` address that your support team can open. |
| `fileName` | Optional, up to 255 characters. |
| `mimeType` | Optional, up to 100 characters. |
| `size` | Optional. Size in bytes. |

> [!WARNING]
>
> Use a link that stays valid long enough for your team to open it, and that does not expose anything beyond the one file. A short-lived signed URL may have expired by the time someone looks.

## Read messages

```bash
curl "https://api.usecerium.com/v1/conversations/thr_01k9z3m4q8/messages?order=asc&limit=100" \
  -H "Authorization: Bearer $CERIUM_API_KEY"
```

```json
{
  "message": "Messages retrieved successfully.",
  "status": "success",
  "data": [
    {
      "id": "msg_5d1c",
      "conversationId": "thr_01k9z3m4q8",
      "from": "customer",
      "senderType": "customer",
      "senderName": "Ada Obi",
      "body": "Hi, I was charged twice for order 1042.",
      "attachments": [],
      "status": "sent",
      "sentAt": "2026-11-20T09:15:00.000Z"
    },
    {
      "id": "msg_5d1e",
      "conversationId": "thr_01k9z3m4q8",
      "from": "agent",
      "senderType": "ai",
      "senderName": "Cerium Assistant",
      "body": "Sorry about that. I can see both charges and I am checking them now.",
      "attachments": [],
      "status": "sent",
      "sentAt": "2026-11-20T09:15:04.000Z"
    }
  ],
  "meta": { "hasMore": false, "nextBefore": null }
}
```

| Parameter | Description |
| - | - |
| `limit` | 1 to 100. Default 50. |
| `order` | `desc` (newest first, default) or `asc`. |
| `before` | The id of the oldest message you hold. See [Pagination](/guides/pagination.md). |

### Who wrote it

Use `senderType` to style messages in your app:

| `senderType` | Shown as |
| - | - |
| `customer` | The customer. |
| `agent` | A member of your team. `senderName` is the team member's display name. |
| `ai` | Your AI agent. |
| `system` | A notice from Cerium. Often best shown as a small centred line. |

> [!NOTE]
>
> Messages you send through the API are always `customer` messages. Your team and AI agent reply from Cerium.
