Get messages
Get the newest messages in your community, optionally from one channel or one trader, as plain text with the sender and channel.
- Method
- GET
- Path
https://api.returning.ai / v1/ messages - Permission
- getMessages
- Retries
- Read-only; exact retries are safe
When to use this
- You watch a channel from your own system and want the latest messages.
- You want to see what one trader has posted recently.
- You need a message ID so you can reply to it or react to it.
Authentication#
- Header
Authorization: Bearer <API_KEY>- Permission
- getMessagesShown in the dashboard as “Get Messages”
Use a Community API key with getMessages, and keep it on your server. The key decides the community, so you only read that community's messages and never send a community ID.
Behaviour#
Messages come newest first, by the time they were posted. Without channel_id you get the newest messages from every channel in your community. Direct messages and deleted messages aren't included.
data.messages.message is plain text: formatting is removed and mentions read @Display Name. A message with a file reads Attached File, a GIF reads GIF Message, and a message with no text that can be shown reads -. Messages the community bot posted have user_id 0 and email Bot. There is no cursor or page parameter, so to catch up after a gap, read with a higher count and skip IDs you have already seen.
Request#
Query parameters#
RuleChannel ID in your community
Eg"66f000000000000000000a11"
Rule1-100, default 50
Eg20
email, not both.Eg"3247779"
user_id, not both.Eg"trader@example.com"
Headers#
getMessages.RuleBearer <API_KEY>
curl --request GET \
--url 'https://api.returning.ai/v1/messages?channel_id=66f000000000000000000a11&count=20' \
--header 'Authorization: Bearer <API_KEY>'
Response#
A 200 returns up to count messages in data.messages. data.total counts the messages in this response only. A channel with no messages returns an empty list.
Rulesuccess
Eg"messages fetched successfully"
Eg{ ... }
Eg1
count messages, newest first. Deleted messages aren't included.Eg[ ... ]
messageId to reply or react.Eg"66f000000000000000000a21"
Attached File and GIFs read GIF Message. A message with no text that can be shown reads -.Eg"Is the gold webinar still on for Friday?"
Eg{"user_id": "3247779", "email": "trader@example.com"}
0, and a message with no recorded sender has null.Eg"3247779"
Bot for the community bot, and null when the sender's account can't be found.Eg"trader@example.com"
Eg{"channel_id": "66f000000000000000000a11", "name": "general"}
null if the message has no valid channel.Eg"66f000000000000000000a11"
null if the channel no longer exists.Eg"general"
Eg"2026-09-26T08:30:00.000Z"
{
"status": "success",
"message": "messages fetched successfully",
"data": {
"total": 1,
"messages": [
{
"id": "66f000000000000000000a21",
"message": "Is the gold webinar still on for Friday?",
"user": {
"user_id": "3247779",
"email": "trader@example.com"
},
"channel": {
"channel_id": "66f000000000000000000a11",
"name": "general"
},
"timestamp": "2026-09-26T08:30:00.000Z"
}
]
}
}
Errors#
Validation errors put the reason in detail, and detail.fields names the bad parameter. Other errors carry only message, or message and detail. None has a machine-readable code, so branch on the HTTP status.
Fix the request03
count outside 1-100 or not a whole number, both user_id and email, an email that isn't an email address, or a parameter this endpoint doesn't accept. detail.fields names it.Invalid token), unknown (Invalid API key) or expired, or it lacks getMessages (Your api key does not have permission to access this action). Personal user API keys can't read messages. Add the permission in Settings > Integration > API Keys.user_id or email can't see the channel in channel_id. Drop one of the two filters, or pick a channel the trader can see.Fix the data01
detail says which. Channel not found: channel_id isn't a channel in your community, or isn't a 24-character channel ID; get it from List integration channels. User not found: user_id or email doesn't match a member of your community; check the value with Get User Data.Retry with backoff01
Authentication failed), or the messages could not be read (detail of Unable to fetch messages). Retry with backoff.Retries
This endpoint is read-only, so retrying the exact same request is safe after a network error or a 500. Use bounded exponential backoff. Over the rate limit, requests return 429; wait for the window to reset, then retry.
{
"meta": {
"status": "error",
"statusCode": 400
},
"message": "Get Messages Query Validation error.",
"detail": {
"message": "Invalid request query",
"fields": ["count"]
},
"solution": "Check your query in request and try again"
}