Get Messages
GET
/v1/messages
What this endpoint does
WARNING
INFO
message.id values -> reply or react using that ID.Quick start
Authorization: Bearer <communityApiKey>. Keep the key server-side. A browser session token is not a Community API key. Required permission: getMessages.Authentication and permission
Authorization: Bearer <communityApiKey> from a server-side secret. A browser session token is not a Community API key. Required permission: getMessages.Complete examples
{
"id": "<messageId>",
"message": "Can someone help with my account?",
"user": {
"user_id": "<numericPlatformUserId>",
"email": "member@example.com"
},
"channel": {
"channel_id": "<channelObjectId>",
"name": "support"
},
"timestamp": "2026-08-15T04:00:00.000Z"
}| Field | Use it for |
|---|---|
id | Send as messageId to reply or react. This is the target message. |
user.user_id | Filter later reads or call POST /v1/users/info. Do not use it as mutation sender. |
user.email | Identify/filter the author or look the user up. It is not required as a recipient for a normal-channel reply. |
channel.channel_id | Scope the next poll. |
sender on reply/react is a different concept: it is the existing community user whose identity the agent acts as. Configure the agent user's email or exact platform username. Do not copy the incoming author's numeric ID or display name into sender.POST /v1/users/info with the returned email or numeric ID and read data.username. Username lookup is not needed merely to reply because message.id already targets the conversation.Success and readback
count defaults to 50 and accepts 1 through 100.channel_id returns a community-wide newest-first normal-message feed.data.total is the number returned, not total stored history.channel_id and user_id, not camelCase query names.user_id and email.TIP
200 returns { status, message, data: { total, messages } }. Empty or zero-result responses return data.messages: []. There is no cursor; count defaults to 50 and accepts 1-100.Errors and recovery
| Status | Meaning | Recovery |
|---|---|---|
| 400 | Invalid count, query casing, identifier combination, or ObjectId | Correct the query. |
| 401 | Missing/invalid key | Use a Community API key in the Authorization header. |
| 403 | Missing permission or filtered user cannot view the channel | Fix key/channel access; do not broaden the query. |
| 404 | Filtered user not found in this community | Correct the email or numeric user ID. |
Retry safety
message.id values and advance it only after the whole batch is processed.Gotchas
channel_id and user_id, not camelCase. Omitting channel_id returns recent normal messages across the community. This endpoint does not return direct-message history or reaction state. Do not infer username from an email prefix.Next steps
id as messageId.id as messageId.data.username.Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/messages?user_id=%3CnumericPlatformUserId%3E&channel_id=%3CchannelObjectId%3E&count=25&email=member%40example.com' \
--header 'Authorization: Bearer <communityApiKey>'Response Response Example
200 - Success Example
{
"status": "success",
"message": "messages fetched successfully",
"data": {
"total": 10,
"messages": [
{
"id": "689b908502ad38f",
"message": "Hi",
"user": {
"user_id": "1243",
"email": "johndoe@gmail.com"
},
"channel": {
"channel_id": "663347f4361726479c6",
"name": "Rules"
},
"timestamp": "2025-08-05T01:39:43.561Z"
},
...
{
"id": "6633473f8a0f479cf",
"message": "Good morning everyone!",
"user": {
"user_id": "1243",
"email": "johndoe@gmail.com"
},
"channel": {
"channel_id": "66334714361726479c6",
"name": "General"
},
"timestamp": "2024-05-02T07:56:47.276Z"
}
]
}
}Modified at 2026-08-15 07:17:41