Delete Conversation
Overview
Permanently delete a single conversation and its related messages and membership records.
The success response reports how many conversations, messages, and members were removed so you can confirm cleanup in admin tools and audit logs.
When to use this endpoint?
Use Delete Conversation when:
- An admin removes one conversation from the tenant workspace.
- You need to clean up a specific thread and its messages permanently.
- The UI offers a single-item delete action (not bulk selection).
To remove many conversations at once, use Conversations → Bulk Delete Conversations instead.
DELETE
{baseUrl}/api/{apiVersion}/client/conversations/:conversationId- Authentication
- Required (Bearer token)
- Tenant-scoped
- Yes (tenant DB - requires x-client-id)
Request Headers
Path Parameters
Success Response (HTTP 200 OK)
Deletion removes the conversation plus cascaded messages and members. Counts are returned in data.
json
{ "success": true, "message": "Conversation deleted successfully", "data": { "conversationsDeleted": 1, "messagesDeleted": 42, "membersDeleted": 3 }, "error": null}Error Responses
HTTP 404 Not Found - Not found
json
{ "success": false, "message": "Conversation not found", "data": null, "error": "Conversation not found"}Notes & Validation Rules
- Conversation not found (HTTP 404 - Not found)
Common Errors
Delete fails when the conversation does not exist or the request is not authenticated for the tenant.
Best Practices
- Treat delete as irreversible - confirm in the UI before calling the API.
- Use the returned
messagesDeletedandmembersDeletedcounts for audit or toast feedback. - Prefer Bulk Delete Conversations when removing multiple IDs in one request.
- Refresh list views after a successful delete so removed threads disappear immediately.
Conversation removed
Return to Conversations → List Conversations to confirm the thread is gone, or continue cleanup with Bulk Delete Conversations.