Delete a conversation
curl --request DELETE \
--url https://api-ai.textyess.com/organization-settings/conversations/{conversationId} \
--header 'x-auth-token: <api-key>'import requests
url = "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}"
headers = {"x-auth-token": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text)const options = {method: 'DELETE', headers: {'x-auth-token': '<api-key>'}};
fetch('https://api-ai.textyess.com/organization-settings/conversations/{conversationId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"x-auth-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("x-auth-token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api-ai.textyess.com/organization-settings/conversations/{conversationId}")
.header("x-auth-token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-ai.textyess.com/organization-settings/conversations/{conversationId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["x-auth-token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"found": true,
"conversation_id": "507f191e810c19729de860ea",
"channel": "whatsapp",
"contact_ids": ["507f191e810c19729de860eb"],
"contact_link": "deleted",
"removed": {
"whatsapp_conversations": 1,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 1,
"customers": 1,
"tickets": 2,
"ticket_classifications": 1,
"message_events": 4,
"conversation_scores": 1,
"cms_orders": 1,
"consent_events": 2,
"flow_executions": 1,
"flow_suppressions": 0,
"flow_events": 3,
"message_logs": 5,
"email_events": 0,
"email_suppressions": 1,
"back_in_stock_interests": 0,
"outbound_message_statuses": 2,
"web_pixel_events": 8,
"popup_submissions": 0,
"discount_code_identifiers": 1,
"media_objects": 3
}
}
{
"found": false,
"conversation_id": "507f191e810c19729de860ea",
"channel": null,
"contact_ids": [],
"contact_link": null,
"removed": {
"whatsapp_conversations": 0,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 0,
"customers": 0,
"tickets": 0,
"ticket_classifications": 0,
"message_events": 0,
"conversation_scores": 0,
"cms_orders": 0,
"consent_events": 0,
"flow_executions": 0,
"flow_suppressions": 0,
"flow_events": 0,
"message_logs": 0,
"email_events": 0,
"email_suppressions": 0,
"back_in_stock_interests": 0,
"outbound_message_statuses": 0,
"web_pixel_events": 0,
"popup_submissions": 0,
"discount_code_identifiers": 0,
"media_objects": 0
}
}
{
"message": "conversationId must be a valid id."
}
{
"message": "Unauthorized"
}
{
"message": "Only an owner or admin can delete a conversation."
}
{
"message": "Running automations could not be cancelled. Retry the deletion."
}
Conversations API
Delete a conversation
Permanently delete a conversation and the contact it belongs to
DELETE
/
organization-settings
/
conversations
/
{conversationId}
Delete a conversation
curl --request DELETE \
--url https://api-ai.textyess.com/organization-settings/conversations/{conversationId} \
--header 'x-auth-token: <api-key>'import requests
url = "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}"
headers = {"x-auth-token": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text)const options = {method: 'DELETE', headers: {'x-auth-token': '<api-key>'}};
fetch('https://api-ai.textyess.com/organization-settings/conversations/{conversationId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"x-auth-token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-ai.textyess.com/organization-settings/conversations/{conversationId}"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("x-auth-token", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api-ai.textyess.com/organization-settings/conversations/{conversationId}")
.header("x-auth-token", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-ai.textyess.com/organization-settings/conversations/{conversationId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["x-auth-token"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"found": true,
"conversation_id": "507f191e810c19729de860ea",
"channel": "whatsapp",
"contact_ids": ["507f191e810c19729de860eb"],
"contact_link": "deleted",
"removed": {
"whatsapp_conversations": 1,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 1,
"customers": 1,
"tickets": 2,
"ticket_classifications": 1,
"message_events": 4,
"conversation_scores": 1,
"cms_orders": 1,
"consent_events": 2,
"flow_executions": 1,
"flow_suppressions": 0,
"flow_events": 3,
"message_logs": 5,
"email_events": 0,
"email_suppressions": 1,
"back_in_stock_interests": 0,
"outbound_message_statuses": 2,
"web_pixel_events": 8,
"popup_submissions": 0,
"discount_code_identifiers": 1,
"media_objects": 3
}
}
{
"found": false,
"conversation_id": "507f191e810c19729de860ea",
"channel": null,
"contact_ids": [],
"contact_link": null,
"removed": {
"whatsapp_conversations": 0,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 0,
"customers": 0,
"tickets": 0,
"ticket_classifications": 0,
"message_events": 0,
"conversation_scores": 0,
"cms_orders": 0,
"consent_events": 0,
"flow_executions": 0,
"flow_suppressions": 0,
"flow_events": 0,
"message_logs": 0,
"email_events": 0,
"email_suppressions": 0,
"back_in_stock_interests": 0,
"outbound_message_statuses": 0,
"web_pixel_events": 0,
"popup_submissions": 0,
"discount_code_identifiers": 0,
"media_objects": 0
}
}
{
"message": "conversationId must be a valid id."
}
{
"message": "Unauthorized"
}
{
"message": "Only an owner or admin can delete a conversation."
}
{
"message": "Running automations could not be cancelled. Retry the deletion."
}
Overview
Permanently delete one conversation and the contact tied to it. The conversation id is thechat_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 and every count at 0. The conversation itself is removed last, so a call that fails part way can be repeated with the same id.
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.customers, 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. That count is discount_code_identifiers.
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 gets403. It requires a valid JWT token in the x-auth-token header. You can find your token in the Developers section:
x-auth-token: your_jwt_token
Path Parameters
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.Response
boolean
true when the conversation existed in your organization and was deleted. false when it was already gone or belongs to another organization.string
The id you sent.
string
whatsapp, onsite, voice, or instagram when the conversation was found. null when found is false.array
Ids of the contacts deleted with this conversation. Empty when no contact was deleted, or when
found is false.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.object
How many records were removed, by store. Every key is present on every response. A missing conversation returns
0 for each key.whatsapp_conversations, onsite_chats, voice_calls, and instagram_conversations are the threads. contacts and customers are the person. tickets, ticket_classifications, message_events, conversation_scores, cms_orders, consent_events, flow_executions, flow_suppressions, flow_events, message_logs, email_events, email_suppressions, back_in_stock_interests, outbound_message_statuses, web_pixel_events, and popup_submissions are the related records. discount_code_identifiers is the number of discount codes whose recipient was cleared. media_objects is the number of stored media files deleted.{
"found": true,
"conversation_id": "507f191e810c19729de860ea",
"channel": "whatsapp",
"contact_ids": ["507f191e810c19729de860eb"],
"contact_link": "deleted",
"removed": {
"whatsapp_conversations": 1,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 1,
"customers": 1,
"tickets": 2,
"ticket_classifications": 1,
"message_events": 4,
"conversation_scores": 1,
"cms_orders": 1,
"consent_events": 2,
"flow_executions": 1,
"flow_suppressions": 0,
"flow_events": 3,
"message_logs": 5,
"email_events": 0,
"email_suppressions": 1,
"back_in_stock_interests": 0,
"outbound_message_statuses": 2,
"web_pixel_events": 8,
"popup_submissions": 0,
"discount_code_identifiers": 1,
"media_objects": 3
}
}
{
"found": false,
"conversation_id": "507f191e810c19729de860ea",
"channel": null,
"contact_ids": [],
"contact_link": null,
"removed": {
"whatsapp_conversations": 0,
"onsite_chats": 0,
"voice_calls": 0,
"instagram_conversations": 0,
"contacts": 0,
"customers": 0,
"tickets": 0,
"ticket_classifications": 0,
"message_events": 0,
"conversation_scores": 0,
"cms_orders": 0,
"consent_events": 0,
"flow_executions": 0,
"flow_suppressions": 0,
"flow_events": 0,
"message_logs": 0,
"email_events": 0,
"email_suppressions": 0,
"back_in_stock_interests": 0,
"outbound_message_statuses": 0,
"web_pixel_events": 0,
"popup_submissions": 0,
"discount_code_identifiers": 0,
"media_objects": 0
}
}
{
"message": "conversationId must be a valid id."
}
{
"message": "Unauthorized"
}
{
"message": "Only an owner or admin can delete a conversation."
}
{
"message": "Running automations could not be cancelled. Retry the deletion."
}