--- title: "Delete a conversation" method: DELETE path: "/conversations/{conversation_id}" tags: ["Conversations"] --- # Delete a conversation `DELETE /conversations/{conversation_id}` ## Request - Base URL: `https://api.axilio.ai/api/v1` - URL: `https://api.axilio.ai/api/v1/conversations/{conversation_id}` - Auth: API key in header `X-Axilio-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Deletes every message in a conversation, as DELETE /messages/{message_id} does for one: the conversation and its messages are removed from every list at once, attachments within 48 hours, and the phone is asked to delete the conversation's messages on its side up to the newest message deleted here (anything it holds that is newer, including texts it has not passed on yet, stays). The response returns at once, with phone_deletion.status pending while the phone has not answered; Axilio keeps checking for up to 7 days, asking the phone again until it confirms (phone_deletion.next_check_at is the next check), and a phone not yet set up to delete messages (not_default_app) is asked once it can. GET /messages/{message_id} on any of the deleted messages shows where the phone's copy stands, and each message fires message.deleted, then message.phone_deleted or message.phone_delete_failed, as DELETE /messages/{message_id} describes. Deleting a conversation does not stop a message in it the phone is still sending. A conversation with no messages left is a 404. ## Path parameters - `conversation_id` string, uuid, required: conversation identifier ## Response `200` OK - ConversationDeleted: A deleted conversation: every message in it is deleted and it no longer appears in any list or read. - `deleted_at` string, date-time, required: When the conversation was deleted. - `id` string, required: The deleted conversation's id. - `message_count` integer, required: How many messages were deleted. - `phone_deletion` PhoneMessagePhoneDeletion, required: What the delete did to the copy on the phone itself. - `next_check_at` string, date-time, nullable, required: When Axilio next checks this delete: it asks the phone again if the phone can delete and the 7 days after the delete aren't over, or settles it. Null once the outcome is final: deleted, not_found, ambiguous, not_matched and not_sent at once, unconfirmed when the 7 days run out; message.phone_deleted or message.phone_delete_failed fires then. - `reason` string, required: A human-readable explanation of status. - `status` 'pending' | 'deleted' | 'not_found' | 'ambiguous' | 'not_default_app' | 'not_matched' | 'failed' | 'unconfirmed' | 'not_sent', required: pending (the phone has been asked and has not answered yet), deleted (the phone deleted its copy), not_found (the phone has no copy), ambiguous (an older text the phone cannot tell apart from an identical one; left on the phone), not_default_app (the phone is not set up to delete messages yet; it is asked once it can), not_matched (the phone stored this message before it became the phone's messaging app and could not identify it; its copy may still be there), failed (the phone tried and failed; it is asked again), unconfirmed (the phone has not confirmed the delete: the request could not be sent, or 7 days passed without an answer; its copy may still be there), or not_sent (the organization no longer rents the phone, so nothing was sent). next_check_at is null once the outcome is final. More values may be added. ## Other responses - `404`: Not Found - `422`: Unprocessable Entity - `500`: Internal Server Error ## Changes - **2026-10-24** `ecca093572e0`: 1 info - endpoint added [Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/conversations/:conversation_id/delete.md) --- [API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)