curl --request DELETE \
--url https://api.omni.z-api.io/v1/channels/{channelId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cancelReason": "Customer closed the company"
}
'Channels
Delete channel
Delete a channel via API
DELETE
/
v1
/
channels
/
{channelId}
curl --request DELETE \
--url https://api.omni.z-api.io/v1/channels/{channelId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cancelReason": "Customer closed the company"
}
'Overview
Deletes a channel. Once deleted, the channel can no longer be used, and deletion cannot be undone through the API.Conditions for deletion
Deletion is only allowed when the channel is disconnected and has no active subscription. If the channel is still connected, the API returns422 with INSTANCE_STILL_CONNECTED. The table below describes the behavior by status:
| Status | Deletion allowed | Notes |
|---|---|---|
| Trial | Yes | — |
| Pending | Yes | If there is an open invoice, it will be automatically cancelled |
| Paid | No | The channel must be cancelled before it can be deleted |
| Cancellation in progress | No | The channel must be cancelled before it can be deleted |
| Cancelled | Yes | — |
Deletion cannot be undone through the API. To delete a channel with an active subscription, first cancel the subscription via Cancel subscription and wait for the
CANCELED status.502 error
If deletion fails in the internal service, the API returns 502 with the body below, with no internal details. Try again and, if the error persists, contact support.
{
"error": "integration_unavailable",
"message": "The operation could not be completed right now. Try again in a few moments."
}
The
channelId is obtained from the Create channel endpoint.Authorizations
Secret Key generated in the Omni Z-API Security panel
Path Parameters
Channel ID (obtained via Create channel)
Example:
"019E4C54B1B375A28970B605CA9B03C3"
Body
application/json
Reason for deletion (optional, but recommended for auditing)
Example:
"Customer closed the company"
Response
Channel deleted successfully. No content returned.