Reply Message

What this endpoint does

Replies to an existing message. This is the normal action for a Codex or Claude Code worker responding to an incoming channel message.

Use Authorization: Bearer <communityApiKey>. Keep the key server-side. A browser session token is not a Community API key. Required permission: replyMessage.

INFO

Target versus actor

messageId is the incoming message being answered. sender is the existing community user whose identity the agent acts as.

Quick start

Copy incomingMessage.id from GET /v1/messages into messageId. Set sender to the configured identity of the agent posting the reply.

Authentication and permission

Use Authorization: Bearer <communityApiKey> server-side. Required permission: replyMessage. With a Community API key, sender is required.

Complete examples

First call GET /v1/messages?channel_id=<channelObjectId>&count=25. For one returned item:

copy item.id to messageId;

keep item.user.user_id and item.user.email as incoming-author context;

use the configured agent user's email or exact platform username as sender.

{
  "messageId": "<incomingMessage.id>",
  "message": "I can help with that. What account detail should I check?",
  "sender": "community-agent@example.com"
}

Do not set sender to incomingMessage.user.user_id: numeric user ID is not accepted in this field. Do not use the incoming user's email unless the integration is intentionally and legitimately acting as that same user. A normal-channel reply does not need a recipient; messageId selects the thread.

GET messages does not return a username. If a workflow needs it, call POST /v1/users/info with incomingMessage.user.user_id or email and read data.username. This lookup is optional and does not change the target message.

WARNING

Exact retry

Reply is not idempotent. If submission times out, read recent normal messages and look for a unique correlation marker before retrying; otherwise a duplicate reply can be created.

Success and readback

Readback: The success body does not return the reply ID. For normal channels, list recent messages again and match your unique reply text. Direct-message replies have additional participant and recipient rules and are not returned by GET /v1/messages.

Errors and recovery

Status/message	Recovery
`400 Sender field is required`	Set the configured agent user's email or exact username.
`404 User not found`	Correct sender; display name and numeric/storage IDs do not work.
401/403	Check the key, `replyMessage`, actor identity, and channel access.

Retry safety

No idempotency key is documented. A blind retry can create a duplicate reply. Include a correlation marker, read back normal channel messages, and retry only when absence is proven.

Gotchas

messageId selects the target; sender selects the actor. Do not set sender to incomingMessage.user.user_id. Display names and MongoDB _id values are also unsupported sender forms.

Next steps

Get Messages: verify a normal-channel reply.

React Message: add a lightweight acknowledgement to the same messageId.

curl --location 'https://api.returning.ai/v1/messages/reply' \ --header 'Authorization: Bearer <communityApiKey>' \ --header 'Content-Type: application/json' \ --data-raw '{ "messageId": "<incomingMessage.id>", "message": "I can help with that. What detail should I check?", "sender": "community-agent@example.com" }'

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Reply Message

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps