1. Messaging
Returning.AI
  • Getting Started
  • Users
    • User directory and provisioning
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
    • Update User XP and Currency
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
      GET
    • Send Message
      POST
    • Reply Message
      POST
    • React Message
      POST
    • Upload message images
      POST
    • Delete message
      DELETE
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Loyalty Points
      • Create loyalty points export
      • Get loyalty points export status
      • Get loyalty points export download link
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Rewards & Redemptions
    • Store catalog to redemptions
    • List redemption orders by custom-field identifier
    • Update redemption order status or refund
    • Create redemption order status
    • List redemption orders by user email
    • List redemption statuses
    • Get redemption status by ID
    • List redemption orders by community
    • Get redemption order status history
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
    • Get bulk update job status
    • Get bulk update job details
    • Bulk update users from CSV
    • Bulk update premium currency from CSV
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Store
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Update products in bulk
      • Create products in bulk
      • Create product with vouchers
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User field definitions and history
    • User Field History
      • Get all user field histories in a community
      • Get user field histories for a specific field
      • Get user field histories for a specific user
      • Get user field histories of specific user field and user
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Get A User Field Definition
    • Update A User Field Definition
    • Create A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Secure Auth
      • Register user with password
      • Verify user email
      • Log in user with password
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  • Data Workflows
    • Read event-ingest lifecycle status by trigger and batch ID.
    • Look up reward events
  • Community Logs
    • Retrieve and export community logs
  • Workflow Builder
    • Workflow Builder API overview
    • Connect an AI agent to the Workflow Builder tools
    • Bind step inputs to trigger and earlier-step outputs
    • Code steps through the API
    • Edit safely: revisions, conflicts, export, import and copying a workflow
    • Set up an event-ingest workflow and check batch status
    • Keep a member's tier or role in sync
    • Reversible rewards
    • Test without side effects, then confirm a live run
    • Build a trading-rewards workflow from event ingest
    • Reward members from your own system with a webhook workflow
    • List step types and trigger types
    • List workflows
    • Create a workflow
    • Get a workflow
    • Rename a workflow or set its failure webhook
    • Delete a workflow
    • Duplicate a workflow
    • Export a workflow definition
    • Validate a stored workflow
    • Create or replace the trigger
    • Add a step
    • Get a step
    • Update a step
    • Delete a step
    • Reorder a main-line step
    • Duplicate a step
    • Add a router branch
    • Update a router branch
    • Delete a router branch
    • Duplicate a router branch
    • Test one step
    • Test a whole workflow
    • Deploy a workflow
    • Undeploy a workflow
    • List the runs of a workflow
    • Get one run
    • Retry a failed run
    • Call the workflow tools over MCP
  • Schemas
    • Sample Schemas
    • Schemas
    • Outgoing webhooks
    • Analysis
    • Pet
    • Category
    • Tag
    • ValidationError
    • NotFoundError
    • InternalServerError
    • NotImplementedError
    • CreateUserFieldHistoryResponse
    • CreateUserFieldHistorySuccessResponse
    • UserFieldHistoryItem
    • GetUserFieldHistoriesResponse
    • UserFieldHistoriesValidationError
    • UserFieldHistoriesMetaWithValidation
    • UserFieldHistoriesMetaWithPagination
    • GetUserFieldHistoriesSuccessResponse
    • CreateUserFieldResponse
    • CreateUserFieldSuccessResponse
    • DeleteUserFieldResponse
    • DeleteUserFieldSuccessResponse
    • UserFieldCreator
    • GetUserFieldResponse
    • GetUserFieldSuccessResponse
    • ValidationErrorItem
    • GetUserFieldsMetaResponse
    • CreatorInfo
    • UserFieldResponse
    • GetUserFieldsSuccessResponse
    • UpdateUserFieldResponse
    • UpdateUserFieldPayload
    • UpdateUserFieldSuccessResponse
    • MetaResponse
    • GetUserResponse
    • GetUserSuccessResponse
    • Purchased store item
    • ErrorResponse
    • New message posted to channel
    • UpdateAnalysisRequest
    • User visits server
    • AppendDrawingsRequest
    • User join server
    • CreateAnalysisResponse
    • GetAnalysisResponse
    • UpdateAnalysisResponse
    • AppendDrawingsResponse
    • AnalysisMetadata
    • Expiry
    • Levels
    • LevelEntry
    • Drawing
    • HorizontalLineDrawing
    • LineDrawing
    • RectangleDrawing
    • ParallelDrawing
    • FibonacciRetracementDrawing
    • Coordinate
    • DrawingStyle
    • AnalysisDetail
    • AnalysisSummary
    • CreateAnalysisRequest
    • ListAnalysesResponse
    • StandardApiError
    • StandardSuccessEnvelope
    • PurchasedStoreItemEvent
    • ChannelMessagePostedEvent
    • UserVisitedCommunityEvent
    • UserJoinedCommunityEvent
  1. Messaging

Delete message

DELETE
/v1/messages/{messageId}

What this endpoint does#

Permanently remove a channel message in your community by its message ID.

Authentication#

Send a community API key with Delete Messages (deleteMessage) permission in Authorization: Bearer <API_KEY>.

Behaviour#

The key can delete ordinary messages from channels in its community, including messages written by other members. A direct message or a message outside the key's community returns 404. A broadcast or a forum topic's main post in the key's community returns 409. Send the message ID in the path and leave the request body empty.

Response#

A 200 confirms that the message was removed. Returning.AI also attempts to reverse rewards earned from the message and its reactions. Some of that work runs after the response. If you receive partial: true, the message was removed and an associated action failed. Ask support to check the side effects using the returned messageId.

Authentication errors#

A missing key returns 401 with Invalid token. An invalid key returns 401 with Invalid API key. A community key missing Delete Messages permission returns 401 with Your API key does not have permission to access this action. The permission error contains only message.

Retries#

A repeat delete returns 404 once the message is gone. After a timeout or 503, read the channel to check the outcome before trying the same ID again. A 404 on its own can also mean the message is outside your community, so check the ID and channel if you have no earlier confirmation. Retrying a deleted message does not rerun its reward reversals.
HTTPWhat to do
400Copy the 24-character message id from Get messages.
401Use a valid community API key with Delete Messages permission. A missing key, invalid key and missing permission all return 401.
404Check the ID and community. If you already confirmed the original deletion, stop retrying.
409Use the community's moderation controls for a broadcast or a forum topic's main post.
500Retry with backoff when authentication is available again.
503Check whether the message is still visible and retry with the same ID if needed.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Path Params

Responses

🟢200Message deleted
application/json
Bodyapplication/json

🟠400Message ID must be a 24-character hex ObjectId
🟠401Missing key, invalid key or missing Delete Messages permission
🟠404Message not found
🟠409Broadcast messages cannot be deleted through the API
🔴500Authentication failed
🔴503Message service unavailable, try again
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request DELETE 'https://api.returning.ai/v1/messages/66f000000000000000000a21' \
--header 'Authorization: Bearer <token>'
Response Response Example
200 - Message deleted
{
  "status": "success",
  "message": "Message deleted",
  "messageId": "66f000000000000000000a21"
}
Modified at 2026-11-21 00:24:00
Previous
Upload message images
Next
Leaderboards
Built with