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

# Messages

> List, inspect, and send messages and notes in a conversation.

Commands for the messages in a conversation. They sit under
`neetochat conversations messages`, since a message always belongs to a
conversation. For fields and response details, see the
[Messages API reference](https://apidocs.neetochat.com/api-reference/messages/list.md). For the conversation
itself, see [Conversations](https://apidocs.neetochat.com/cli-reference/conversations.md).

Samples on this page use `--json`, which is the format you get when output is
piped as well. On a terminal without that flag the same data prints as a table.
See [Output formats](https://apidocs.neetochat.com/cli/output-formats.md).

## List messages

Messages in a conversation, oldest first. Internal notes and messages created
by NeetoChat are included.

```bash theme={"system"}
neetochat conversations messages list de414e85-a1b5-4240-a465-7b32606980ce --json
```

**Required arguments:**

| Argument | Description |
| - | - |
| `<conversation-id>` | The conversation's UUID, from `neetochat conversations list`. |

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |

```json theme={"system"}
{
  "data": [
    {
      "id": "1bf689fc-9f92-4e39-9f71-4a97078d2b8f",
      "body": "<p>Thanks, we have processed your refund.</p>",
      "kind": "user_message",
      "status": "read",
      "external_id": null,
      "created_at": "2026-10-05T16:26:57.912Z",
      "updated_at": "2026-10-05T16:26:57.912Z",
      "sender": {
        "id": "05665eee-4602-4317-8f7f-767b04274e5f",
        "name": "Oliver Smith",
        "email": "oliver@example.com",
        "type": "User"
      },
      "attachments": [],
      "message_gif": null
    }
  ],
  "breadcrumbs": [
    {
      "label": "Show",
      "command": "neetochat conversations messages show de414e85-a1b5-4240-a465-7b32606980ce <message-id>"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 15
  }
}
```

## Show a message

One message in a conversation, when you already have its id and want the
full record.

```bash theme={"system"}
neetochat conversations messages show \
  de414e85-a1b5-4240-a465-7b32606980ce \
  1bf689fc-9f92-4e39-9f71-4a97078d2b8f \
  --json
```

**Required arguments:**

| Argument | Description |
| - | - |
| `<conversation-id>` | The conversation's UUID, from `neetochat conversations list`. |
| `<message-id>` | The message's UUID, from `neetochat conversations messages list`. |

This command takes no flags of its own.

```json theme={"system"}
{
  "data": {
    "message": {
      "id": "1bf689fc-9f92-4e39-9f71-4a97078d2b8f",
      "body": "<p>Thanks, we have processed your refund.</p>",
      "kind": "user_message",
      "status": "read",
      "external_id": null,
      "created_at": "2026-10-05T16:26:57.912Z",
      "updated_at": "2026-10-05T16:26:57.912Z",
      "sender": {
        "id": "05665eee-4602-4317-8f7f-767b04274e5f",
        "name": "Oliver Smith",
        "email": "oliver@example.com",
        "type": "User"
      },
      "attachments": [],
      "message_gif": null
    }
  }
}
```

A message created by NeetoChat itself, such as a status change, has a
`sender` with every field `null`.

## Add a message to a conversation

Sends a message or an internal note. The sender is resolved from
`--sender-email`: an active team member's address sends a reply from that
team member, and any other address sends it as a message from the contact,
creating a new contact when none exists with that email.

```bash theme={"system"}
neetochat conversations messages create de414e85-a1b5-4240-a465-7b32606980ce \
  --body "Thanks, we have processed your refund." \
  --sender-email oliver@example.com \
  --json
```

**Required arguments:**

| Argument | Description |
| - | - |
| `<conversation-id>` | The conversation's UUID, from `neetochat conversations list`. |

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--body` | `string` | Yes | | Message body |
| `--sender-email` | `string` | Yes | | Email of the sender (an agent or the visitor) |
| `--kind` | `string` | | `user_message` | Message kind: user\_message or note |
| `--mention` | `stringArray` | | `[]` | Agent email to mention (note only; repeat the flag for more than one) |
| `--external-id` | `string` | | | Your own identifier for this message, for idempotent creation |

```json theme={"system"}
{
  "data": {
    "message": {
      "id": "1bf689fc-9f92-4e39-9f71-4a97078d2b8f",
      "body": "Thanks, we have processed your refund.",
      "kind": "user_message",
      "status": "read",
      "external_id": null,
      "created_at": "2026-10-23T10:20:00.000Z",
      "updated_at": "2026-10-23T10:20:00.000Z",
      "sender": {
        "id": "05665eee-4602-4317-8f7f-767b04274e5f",
        "name": "Oliver Smith",
        "email": "oliver@example.com",
        "type": "User"
      },
      "attachments": [],
      "message_gif": null
    }
  }
}
```

`--kind note` adds an internal note that only team members can see; `--mention`
can then be repeated to mention team members by email, and is rejected on a
`user_message`. `--external-id` makes the request safe to retry: a message
with the same id already in the workspace is returned unchanged instead of
creating a second one.

> [!TIP]
>
> With `--quiet` the command prints only the new record's identifier, which is
> convenient in a script.


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