API Reference
Delete Message
Overview
Permanently delete a single message from the tenant workspace by its ID.
Call this endpoint when removing one message from moderation tools, admin panels, or cleanup flows. On success the API returns a deletion count. For removing many messages at once, use Bulk Delete Messages instead.
When to use this endpoint?
Use Delete Message when:
- Removing a single message after moderation or user request.
- Cleaning up one incorrect or unwanted message from a conversation.
- You already know the message
_idfrom List Messages. - You need a confirmation count that exactly one message was deleted.
To delete many messages in one request, use Bulk Delete Messages.
{baseUrl}/api/{apiVersion}/client/messages/:messageIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| messageId | string | Message _id (24-char Mongo ObjectId). |
Success Response (HTTP 200 OK)
On success, the API confirms how many messages were deleted.
{
"success": true,
"message": "Message deleted successfully",
"data": {
"messagesDeleted": 1
},
"error": null
}Error Responses
HTTP 404 Not Found — Not found
{
"success": false,
"message": "Message not found",
"data": null,
"error": "Message not found"
}Notes & Validation Rules
- Message not found (HTTP 404 - Not found)
Common Errors
HTTP 200 OK means the message was deleted. Deletion fails when the message does not exist or authentication is missing.
| Code | Reason |
|---|---|
| 400 Bad Request | Required headers are missing or messageId is invalid. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | Message not found for the given messageId. |
| 500 Internal Server Error | An unexpected error occurred while deleting the message. |
Best Practices
- Confirm the message exists via List Messages before deleting.
- Treat deletion as irreversible — require an explicit confirmation in your UI.
- Use Bulk Delete Messages when removing more than one message.
- Refresh list views after a successful delete so removed messages disappear immediately.
- Always send tenant headers and a valid Bearer token over HTTPS.
Message deleted
Refresh List Messages to confirm the record is gone. For batch cleanup, continue with Bulk Delete Messages.