API Reference
Bulk Delete Conversations
Overview
Delete up to 100 conversations in a single request, including their related messages and membership records.
Use this endpoint for admin cleanup jobs and multi-select delete actions. The response summarizes how many conversations, messages, and members were removed.
When to use this endpoint?
Use Bulk Delete Conversations when:
- The admin UI lets users select multiple conversations to remove.
- An automation job needs to purge a batch of obsolete threads.
- You want one round-trip instead of calling Delete Conversation per ID.
For a single conversation, prefer Conversations → Delete Conversation.
{baseUrl}/api/{apiVersion}/client/conversations/bulk-deleteAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Access Token from Login Client or Register Client. |
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
| Content-Type | application/json | — |
Request Payload
{
"conversationIds": [
"{{conversationId}}",
"6a4df14ab9d92d7cca830dff"
]
}Success Response (HTTP 200 OK)
The API returns aggregate deletion counts for conversations, messages, and members.
{
"success": true,
"message": "Conversations deleted successfully",
"data": {
"conversationsDeleted": 2,
"messagesDeleted": 57,
"membersDeleted": 5
},
"error": null
}Error Responses
HTTP 400 Bad Request — Invalid ids
{
"success": false,
"message": "conversationIds must be 1-100 valid ids",
"data": null,
"error": "conversationIds must be 1-100 valid ids"
}Notes & Validation Rules
- conversationIds must be 1-100 valid ids (HTTP 400 - Invalid ids)
Workflow
Follow this flow to remove multiple conversations safely and confirm the cleanup summary.
- 1
Select resources to remove
Collect 1–100 valid IDs from your admin UI or automation job.
- 2
Call the bulk-delete endpoint
Send the ID array in the request body with tenant headers and a Bearer token.
- 3
Review the deletion summary
Use the response counts to confirm how many records were removed and refresh your list views.
Common Errors
Bulk delete fails when the ID array is empty, too large, or contains invalid ObjectIds.
| Code | Reason |
|---|---|
| 400 Bad Request | conversationIds must be 1–100 valid ids. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 500 Internal Server Error | An unexpected error occurred while bulk-deleting conversations. |
Best Practices
- Cap selections at 100 IDs per request; split larger batches into multiple calls.
- Validate ObjectIds in the client before submitting to avoid 400 errors.
- Show a confirmation step — bulk delete is irreversible and cascades to messages and members.
- Use the response counts to update UI badges and refresh list views.
Bulk cleanup complete
Review the deletion summary, then reload Conversations → List Conversations to verify the selected threads are gone.