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

# Messages

> Conversation messages — the individual turns exchanged with a customer.

# Messages

A message is a single turn in a conversation: who sent it, what it said, and when. Messages are
the atoms the rest of the Response surface builds on — a
[channel thread](/response-api-reference/channel-threads) groups them, and a
[response](/response-api-reference/responses/get) is what an agent produced for one.

## Shape

| Field           | Type        | Notes                                          |
| --------------- | ----------- | ---------------------------------------------- |
| `id`            | string      | Unique identifier                              |
| `body`          | string      | The message text                               |
| `from`          | string      | Sender                                         |
| `to`            | string      | Recipient                                      |
| `username`      | string      | Display name of the sender                     |
| `user_id`       | string      | The user the message belongs to                |
| `is_public`     | boolean     | Whether the message is visible to the customer |
| `created_at`    | datetime    | When the record was created                    |
| `timestamp`     | datetime    | When the message was sent                      |
| `date` / `time` | date / time | Split components of `timestamp`                |

<Warning>
  `is_public` controls customer visibility. An internal note written with `is_public: true` is
  visible to the customer — set it deliberately rather than relying on the default.
</Warning>

## Endpoints

| Method   | Path               |                                                   |
| -------- | ------------------ | ------------------------------------------------- |
| `GET`    | `/v1/messages`     | [List](/response-api-reference/messages/list)     |
| `GET`    | `/v1/messages/:id` | [Get](/response-api-reference/messages/get)       |
| `POST`   | `/v1/messages`     | [Create](/response-api-reference/messages/create) |
| `POST`   | `/v1/messages/:id` | [Update](/response-api-reference/messages/update) |
| `DELETE` | `/v1/messages/:id` | [Delete](/response-api-reference/messages/delete) |

## Example

```bash theme={null}
curl https://api.stateset.com/v1/messages \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

Post a message into a conversation:

```bash theme={null}
curl -X POST https://api.stateset.com/v1/messages \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "body": "Your replacement has shipped — tracking 1Z999AA10123456784.",
    "from": "support@acme.com",
    "to": "customer@example.com",
    "is_public": true
  }'
```

## Related

* [Channel Threads](/response-api-reference/channel-threads) — grouping messages into a conversation
* [Conversations in StateSet Mail](/stateset-mail/conversations) — the triage layer for email