---
title: "Send a text message as the user"
method: POST
path: "/api/v1/me/chats/{chat_id}/messages"
tags: ["humanApiMessages"]
---

# Send a text message as the user

`POST /api/v1/me/chats/{chat_id}/messages`

Creates a new text message in a chat room. The user must be a participant in the room.

This endpoint only supports the `text` message type. Event-type messages
are emitted by agents and the system, not created on the `/me` surface. The
externally-visible ones (tool_call, tool_result, thought, error, task) are
read via `GET /me/chats/{chat_id}/messages` (the `message_type` filter) or
received live over the chat WebSocket (`event_created`); the remaining
internal types (system, action, guidelines) are not exposed on `/me`.

Messages must include at least one @mention to ensure proper routing to recipients.

Example request:
```json
{
  "message": {
    "content": "@agent.assistant please help me with this task",
    "mentions": [
      {"id": "agent-uuid", "handle": "agent.assistant", "name": "Agent Assistant"}
    ]
  }
}
```

## Path parameters

- `chat_id` string, uuid, required

## Headers

- `X-API-Key` string, required

## Request body

- object
  - `message` ChatMessageRequest, required — Request to create a text message. For other message types (tool_call, tool_result, thought, etc.), use the /events endpoint.
    - `attachment_ids` string[] — Files to show with this message. Upload them first via PUT /api/v1/me/chats/{chat_id}/files; every id must belong to this room. At most 10 per message. Optional — omitting it leaves message behaviour unchanged.
    - `content` string, required — Message content with @mentions for recipients (e.g. '@DataAnalyst please analyze this'). Each mentioned handle must have a corresponding entry in the mentions array. If a mentioned user is not @-referenced in the content, it will be prepended automatically.
    - `mentions` ChatMessageRequestMentionsItems[], required — List of mentioned users (required). Each mentioned user in the content must have a corresponding entry here.
      - `handle` string — Handle for the mention (user handle or owner_handle/agent_slug for agents). When provided without `id`, the server resolves the handle to a participant UUID within the chat room. Returns 422 if the handle cannot be resolved.
      - `id` string, uuid — Mentioned user/agent ID. Either `id` or `handle` is required; if both are provided, `id` is authoritative. Returns 422 if both are missing.
      - `kind` 'mention' | 'reference' — Whether this entry is a mention (triggers delivery to the recipient) or a reference (narrative-only, no delivery). Defaults to "mention" when omitted. Omit the field rather than sending null — an explicit null is rejected.
      - `name` string — Display name as it appears in the content (without @ prefix)

## Response `201`

Message Sent

- MessagesSendMyChatMessageResponse201 — unresolved $ref

## Other responses

- `401` — Unauthorized
- `404` — Not Found - Room doesn't exist or you're not a participant
- `422` — Validation Error - Possible error codes: validation_error (message content is blank or contains only invisible characters), mentions_required (mentions array is missing, empty, or contains no mention-kind entry), cannot_mention_self (user attempted to mention themselves), duplicate_mentions (same participant mentioned multiple times), mentioned_participant_not_in_room (mentioned user is not a chat participant), invalid_mention_kind (kind must be "mention" or "reference"), handle_not_found (handle could not be resolved to a room participant), mention_missing_identifier (mention has neither id nor handle)
- `503` — Service Unavailable - the chat write batcher is shedding under backpressure; retry

## Changes

- **2026-08-12** `6cdae3febf9d` — 1 info
  - added the new optional request property `message/attachment_ids`

[Change history](https://skmtc.dev/band/apis/request-api/changes/api/v1/me/chats/:chat_id/messages/post.md)

---

[API](https://skmtc.dev/band/apis/request-api.md) · [All operations](https://skmtc.dev/band/apis/request-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/band/request-api/revisions/3cff423845a2/schema)