> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textyess.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete a conversation

> Permanently delete a conversation and the contact it belongs to

## Overview

Permanently delete one conversation and the contact tied to it. The conversation id is the `chat_id` column from the conversation export. For a voice call that value is the provider conversation id; for every other channel it is the conversation's own id.

The call removes the conversation document, its messages, the media files stored for it, and the contact's other conversations in the same organization. It also removes the records that hold that person's data: tickets, scores, consent history, flow runs, message logs, linked orders, and the same kind of row.

A running automation for that person is cancelled before its stop record is removed. If the cancel fails, the call returns `503` and deletes nothing further, so you can retry it.

An onsite chat is deleted on its own. The email a visitor types in the chat is not proof of who they are, so it is never used to find a contact or other records. An Instagram conversation has no verified link to a contact either. For both, only the thread is deleted and `contact_link` is `unsupported`. An email shared by more than one contact is not used to delete records.

Message logs for a billed extra stay as they are, because they are the billing record. Flow events are matched by phone number only.

Repeating the call is safe. A conversation that is already gone returns `200` with `found: false`. The conversation itself is removed last, so a call that fails part way can be repeated with the same id.

<Note>
  The deletion is limited to the organization of the token. A conversation id that belongs to another organization returns `found: false` and leaves that organization's data in place.
</Note>

One profile is stored per phone number and shared by every organization that has talked to that number. This call removes that profile for the number.

Discount codes stay in your pool. The call clears the recipient phone, email, and contact id on the codes that belonged to this person.

This call deletes the live data. It does not delete database backups, the analytics warehouse, or copies held by WhatsApp or the voice provider.

There is no dedicated rate limit. Each call writes across several collections, so pace a retention batch.

## Authentication

Only an owner or admin of the organization can call this endpoint. Any other user gets `403`. It requires a valid JWT token in the `x-auth-token` header. You can find your token in the [Developers section](https://ai.textyess.com/developers):

```bash theme={null}
x-auth-token: your_jwt_token
```

## Path Parameters

<ParamField path="conversationId" type="string" required>
  The conversation id. Use the `chat_id` value from the conversation export. Voice exports put the provider conversation id in that column. Other channels put the conversation's own id, a 24-character hex string.
</ParamField>

## Response

<ResponseField name="found" type="boolean">
  `true` when the conversation existed in your organization and was deleted. `false` when it was already gone or belongs to another organization.
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The id you sent.
</ResponseField>

<ResponseField name="channel" type="string">
  `whatsapp`, `onsite`, `voice`, or `instagram` when the conversation was found. `null` when `found` is `false`.
</ResponseField>

<ResponseField name="contact_ids" type="array">
  Ids of the contacts deleted with this conversation. Empty when no contact was deleted, or when `found` is `false`.
</ResponseField>

<ResponseField name="contact_link" type="string">
  How the contact was resolved. `deleted` when a contact was removed. `none` when the conversation had no contact. `unsupported` when the channel has no verified contact link, which is every onsite and Instagram conversation. `null` when `found` is `false`.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "found": true,
    "conversation_id": "507f191e810c19729de860ea",
    "channel": "whatsapp",
    "contact_ids": ["507f191e810c19729de860eb"],
    "contact_link": "deleted"
  }
  ```

  ```json 200 theme={null}
  {
    "found": false,
    "conversation_id": "507f191e810c19729de860ea",
    "channel": null,
    "contact_ids": [],
    "contact_link": null
  }
  ```

  ```json 400 theme={null}
  {
    "message": "conversationId must be a valid id."
  }
  ```

  ```json 401 theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 403 theme={null}
  {
    "message": "Only an owner or admin can delete a conversation."
  }
  ```

  ```json 503 theme={null}
  {
    "message": "Running automations could not be cancelled. Retry the deletion."
  }
  ```
</ResponseExample>