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. Without channel_id you get the newest messages from every channel in your community. Direct 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, and a GIF reads GIF Message. 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.Eg[ ... ]
messageId to reply or react.Eg"66f000000000000000000a21"
Attached File and GIFs read GIF Message.Eg"Is the gold webinar still on for Friday?"
Eg{"user_id": "3247779", "email": "trader@example.com"}
Eg"3247779"
Eg"trader@example.com"
Eg{"channel_id": "66f000000000000000000a11", "name": "general"}
Eg"66f000000000000000000a11"
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, a malformed channel_id, both user_id and email, or a parameter this endpoint doesn't accept. detail.fields names it. A detail of Channel not found means channel_id isn't a channel in your community. Any other detail text is an unexpected failure; retry it once with backoff.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
user_id or email doesn't match a member of your community. Check the value with Get User Data.Retry with backoff01
Authentication failed). Retry with backoff.{
"meta": {
"status": "error",
"statusCode": 400
},
"message": "Get Messages Query Validation validation error.",
"detail": {
"message": "Invalid request query",
"fields": ["count"]
},
"solution": "Check your query in request and try again"
}