1. Messaging
Returning.AI
  • Getting Started
  • Users
    • User directory and provisioning
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
    • Update User XP and Currency
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
      GET
    • Send Message
      POST
    • Reply Message
      POST
    • React Message
      POST
    • Upload message images
      POST
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
      • Get Daily Calculation Data
      • Get Rolling Calculation Data
    • Match Predictions
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Rewards & Redemptions
    • Store catalog to redemptions
    • Update redemption order status or refund
      PUT
    • List redemption orders by user email
      POST
    • List redemption statuses
      POST
    • Get redemption status by ID
      POST
    • List redemption orders by community
      POST
    • Create redemption order status
      POST
    • Get redemption order status history
      POST
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
    • Get bulk update job status
    • Get bulk update job details
    • Bulk update users from CSV
    • Bulk update premium currency from CSV
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Store
    • Store catalog
    • Purchase History
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Update products in bulk
      • Create products in bulk
      • Create product with vouchers
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User field definitions and history
    • User Field History
      • Get all user field histories in a community
      • Get user field histories for a specific field
      • Get user field histories for a specific user
      • Get user field histories of specific user field and user
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Get A User Field Definition
    • Update A User Field Definition
    • Create A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Secure Auth
      • Register user with password
      • Verify user email
      • Log in user with password
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  1. Messaging

Reply Message

POST
/v1/messages/reply

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/messageRecovery
400 Sender field is requiredSet the configured agent user's email or exact username.
404 User not foundCorrect sender; display name and numeric/storage IDs do not work.
401/403Check 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.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK
application/json
Request completed successfully.
Bodyapplication/json

🟠400Bad Request
🟠401Unauthorized
🟠403Forbidden
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://adss-integration.returning.ai/apis/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"
}'
Response Response Example
200 - Success Example
{
    "status": "success",
    "message": "Message reply successfully"
}
Modified at 2026-08-15 05:27:57
Previous
Send Message
Next
React Message
Built with