---
title: "Post a message into an item's chat as an agent"
method: POST
path: "/api/v1/items/{id}/messages"
tags: ["Chats"]
---

# Post a message into an item's chat as an agent

`POST /api/v1/items/{id}/messages`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/items/{id}/messages`
- Auth: HTTP bearer

Post a message into an item's chat as the calling agent: an action taken outside Roma with its link, or the one question the work is blocked on. On a shared item (shared on its own or through its list) the post lands in its Thread, where the owner and every member read it. The user sees it on every device as an unread reply on the item and as an Updates row under your name, and the agent cannot take it back, so a post per step, or a note that work is finished, reads as noise; a post the item's own body asks you for is the person's ask and is wanted. Set `needsInput` when the work is blocked on their answer. The same `messageKey` posted twice lands once. The person is offered Reply on your post only when you will read it: a live trigger wakes you by this `agentName` (manage_triggers, action create, with `agentName`), or you pass `readsReplies: true` because you read this chat again on your next run (read_chat_messages with `since`). Otherwise the post is a notification they cannot answer, so do not ask a question in it. The answer's `listening` says whether a reply would wake you at once. A registered agent (register_agent) posts under its record's name whatever `agentName` says, and the person's Reply wakes it through its own door.

## Path parameters

- `id` string, required

## Request body

- object
  - `message` string, required: The message, as Markdown.
  - `agentName` string: How the agent is named in the chat (default "Your agent"). For a registered agent: which of the person's agents on this client you are, when there are several.
  - `needsInput` boolean: True when the message is a question the work waits on.
  - `readsReplies` boolean: True when you read this chat again on your next run, so the person may answer here even with no trigger waking you.
  - `messageKey` string: Idempotency key: a retry with the same key updates the same message.

## Response `201`

Created; the body is the new item.

- object
  - `id` string, required
  - `sessionId` string, required
  - `createdAt` string, required
  - `listening` boolean, required: Whether a reply from the person would wake this agent through a trigger. False: the reply waits for the agent's next run.

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)