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.
DELETE
{baseUrl}/api/{apiVersion}/client/messages/:messageId- Authentication
- Required (Bearer token)
- Tenant-scoped
- Yes (tenant DB - requires x-client-id)
Request Headers
Path Parameters
Success Response (HTTP 200 OK)
On success, the API confirms how many messages were deleted.
json
{ "success": true, "message": "Message deleted successfully", "data": { "messagesDeleted": 1 }, "error": null}Error Responses
HTTP 404 Not Found - Not found
json
{ "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.
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.