Returning.AIDevelopers
v1

API reference / Messaging

.md

Send message

Post a message to one of your community's channels as an existing member, with text, image links or both.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/messages/send
Permission
sendMessage
Retries
Not idempotent; check Get Messages before retrying

When to use this

  • Your system posts market updates or announcements into a community channel.
  • A bot or support account answers in a channel on your team's behalf.
  • You want to share a chart or image in a channel from a public image URL.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
sendMessageShown in the dashboard as “Send Messages”

Use a Community API key with sendMessage, and keep it on your server. The key decides the community, so never send a community ID. A personal user API key with its own send permission also works; then the message is posted as the key's owner and the channel's posting rules apply.

Behaviour#

The message appears straight away for everyone in the channel, posted as sender. With a Community API key the channel's posting rules aren't checked, so you can post as any member in any of your community's channels; pick sender with care. The sender earns the usual XP and message counts for a message, members named in @ mentions are mentioned, and your community's message webhooks fire. @all mentions every member.

A text that contains a link is handled as an attachment, not as text. When the whole message is one URL, that file is fetched and posted as an attachment with no text. Any other text with a link fails with 400 Error processing attachments. To share a picture with a caption, put the caption in message and the picture in images.

Images in images are copied to Returning.AI storage before posting. More than 10 images are posted as several messages, the first straight away and the rest just after the response.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with sendMessage.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

channelId#stringREQUIRED
The channel to post in, from List integration channels.

RuleChannel ID

Eg"66f000000000000000000a11"

sender#stringREQUIRED
The member the message is posted as, by username or email. Required with a Community API key. With a personal user API key, leave it out to post as the key's owner.

RuleUsername or email of a member

Eg"support@example.com"

message#stringOPTIONAL
The message text. Mention a member with @username, or use @{name} when the username has other characters.

RuleRequired unless you send images

Eg"The gold webinar starts in 15 minutes."

images#string[]OPTIONAL
Public image URLs to attach. Each image is copied and posted with the message, 10 images per message.

RuleRequired unless you send message

Eg["https://cdn.example.com/charts/xauusd.png"]

forumTopicId#stringOPTIONAL
The topic to post in, for a forum channel.

RuleTopic ID in that channel

recipient#stringOPTIONAL
For a direct-message channel, with a personal user API key only. The recipient's username or email.
curl --request POST \
  --url https://api.returning.ai/v1/messages/send \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channelId": "66f000000000000000000a11",
    "sender": "support@example.com",
    "message": "The gold webinar starts in 15 minutes."
  }'

Response#

A 200 means the message was posted. The response has no message ID; read the channel with Get Messages to find it.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Message sent successfully"

{
  "status": "success",
  "message": "Message sent successfully"
}

Errors#

Validation errors use meta, message, detail and solution, with detail naming the field. Every other error has message, sometimes with status or detail. None has a machine-readable code, so branch on the HTTP status and read message.

Fix the request03

400Fix the request
A field is missing or malformed, such as no channelId, neither message nor images, or an ID that isn't 24 hex characters (detail names the field). Sender field is required means you used a Community API key without sender. Error processing attachments means an image URL couldn't be fetched, or the text contains a link (see Behaviour). Nothing was posted.
401Fix the request
The key is missing (Invalid token), unknown (Invalid API key) or expired, or it lacks sendMessage (Your API key does not have permission to access this action). Add the permission in Settings > Integration > API Keys.
403Fix the request
Personal user API keys only: the key's owner can't post in this channel, sender names someone other than the key's owner, or the recipient isn't in the direct-message channel. Nothing was posted.

Fix the data01

404Fix the data
message says which: Channel not found (check channelId with List integration channels), User not found (no member has that sender), Recipient not found, or Forum topic not found or does not belong to this channel. Nothing was posted.

Retry with backoff01

500Retry with backoff
The send failed, or the key could not be checked (Authentication failed). The message may already be posted, so check Get Messages before you retry.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Send Message Validation validation error.",
  "detail": {
    "channelId": "Channel ID must be a valid ObjectId"
  },
  "solution": "Check your body in request and try again"
}

Next step#

Get messagesGET/v1/messagesConfirm the message is in the channel and get its id. This endpoint doesn't return one.