Send Message
POST
/v1/messages/send
What this endpoint does
Authorization: Bearer <communityApiKey>. Keep the key server-side. A browser session token is not a Community API key. Required permission: sendMessage.Quick start
channelId, message, and the configured agent identity in sender. Use reply instead when responding to one monitored message.Authentication and permission
Authorization: Bearer <communityApiKey> server-side. Required permission: sendMessage. With a Community API key, sender is required.Complete examples
{
"channelId": "<channelObjectId>",
"message": "Automated update: the support queue has been reviewed.",
"sender": "community-agent@example.com"
}sender is required. Use the dedicated agent user's exact email (recommended) or exact platform username. Display name, numeric user ID, and MongoDB _id do not resolve as sender.WARNING
Success and readback
status and message, but no created message ID. For a normal channel message, call GET /v1/messages?channel_id=<channelObjectId>&count=25 and match a unique non-secret correlation marker in your text. Direct messages are stored separately and cannot be recovered through that GET endpoint.Errors and recovery
| Status/message | Recovery |
|---|---|
400 Sender field is required | Add the configured agent user's email or exact username. |
404 User not found | Do not substitute display name, numeric user ID, or MongoDB _id. |
| 401/403 | Check the Community API key, sendMessage, and channel access. |
Retry safety
Gotchas
sender identifies the actor posting, not a recipient. It accepts a simple stored email or exact platform username, not display name, numeric user_id, or MongoDB _id. Normal-message readback does not cover direct messages.Next steps
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/messages/send' \
--header 'Authorization: Bearer <communityApiKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"channelId": "<channelObjectId>",
"message": "Automated update: support is reviewing this.",
"sender": "community-agent@example.com"
}'Response Response Example
200 - Success Example
{
"status": "success",
"message": "Message send successfully"
}Modified at 2026-08-15 07:17:43