Permanently delete a conversation

POST
/v1/conversations/{id}/purge

Deletes for good the words, subject, attachments and stored emails of one conversation, and blanks the content of its history entries. It cannot be undone. What stays, and the answer says so in kept: the email addresses and phone numbers (opt-outs, sending limits and abuse checks use them), the fact that each message existed with its time, size and delivery status, the bill, and a record that this was done. It is refused with 409 retention_hold while a legal hold is on, and with 409 permanent_delete_off when the workspace has turned permanent delete off. If a step fails the answer is state: finishing and it resumes by itself. Needs a key allowed to delete conversations for good, which no preset gives; a person does it in the dashboard by typing a confirmation.

Requires an API key with the conversations:purge scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The conversation id.

Request Body

application/json
  1. body
confirm*boolean

Must be true. Pass it only after the person has said they want this conversation deleted for good.

Response Body

Deleted for good, or finishing (it resumes by itself)

application/json
  1. response
conversationId*string
Formatuuid
state*string
Value in"deleted""finishing"
removed*
kept*array<string>
summary*string
Example Request
curl -X POST "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/purge" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "confirm": true  }'
Example Response
{  "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",  "state": "deleted",  "removed": {    "messages": 3,    "files": 2,    "events": 9  },  "kept": [    "The email addresses and phone numbers that wrote and received, because opt-outs, sending limits and abuse checks use them.",    "That each message existed: its direction, its time, its size and whether it was delivered, and the bill for it.",    "A record that the conversation was permanently deleted, who asked for it and when."  ],  "summary": "Deleted for good: 3 messages, 2 stored files and the content of 9 history entries are gone."}