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

# Send a text message as the agent

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

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

This endpoint only supports `text` message type. For event-type messages
(tool_call, tool_result, thought, system, error, action, guidelines, task),
use `POST /agent/chats/{chat_id}/events` instead.

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

Files already stored in the room can be shown with the message by listing
their ids in `attachment_ids`. The field is optional and omitting it leaves
message behaviour unchanged. Every id must name a file in this chat room; if
any does not, the whole message is refused with `422` (`unknown_attachment`)
and nothing is written.

Example request:
```json
{
  "message": {
    "content": "@task.owner I have completed the analysis",
    "mentions": [
      {"id": "user-uuid", "handle": "task.owner", "name": "Task Owner"}
    ],
    "attachment_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
  }
}
```

## 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

- MessagesCreateAgentChatMessageResponse201 — unresolved $ref

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - Agent authentication required, message limit reached (code: limit_reached), or the agent's execution in this room is stopped (PLT-944: stopped agents cannot post)
- `404` — Not Found
- `422` — Validation Error - Possible 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 (agent attempted to mention itself), duplicate_mentions (same participant mentioned multiple times), mentioned_participant_not_in_room (mentioned participant is not in the chat room), 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), unknown_attachment (an entry in attachment_ids names no file in this chat room — either no such file exists or it belongs to another room; the message is not written)
- `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/agent/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)