Chats

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

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.

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

Path parameters

idstring required

The item's id, or a Roma link to it (roma.app/artifacts/<id>).

Request body

messagestring required

The message, as Markdown.

agentNamestring

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.

needsInputboolean

True when the message is a question the work waits on.

readsRepliesboolean

True when you read this chat again on your next run, so the person may answer here even with no trigger waking you.

messageKeystring

Idempotency key: a retry with the same key updates the same message.

Response

Created; the body is the new item.

idstring required
sessionIdstring required
createdAtstring required
listeningboolean required

Whether a reply from the person would wake this agent through a trigger. False: the reply waits for the agent's next run.

Changes

No recorded changes to this operation across all 1 revision of this API.