Send a text message as the agent

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:

{
  "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"]
  }
}