Skip to main content

​
DELETE /instance/delete/:instanceName

Permanently delete a WhatsApp instance. This will log out the instance, disconnect from WhatsApp, remove all stored data, and deactivate all integrations associated with the instance.
This action is irreversible. All instance data including messages, contacts, settings, and integrations will be permanently deleted. The instance cannot be recovered after deletion.

​
Authentication

This endpoint requires authentication via the apikey header. 
apikey: YOUR_API_KEY

​
Path Parameters

​
instanceName
string
required
Name of the instance you want to delete. This is the instanceName you specified when creating the instance.

​
Response

​
status
string
Status of the deletion operation: SUCCESS
​
error
boolean
Indicates if an error occurred: false on success
​
response
object
Response details
​
message
string
Confirmation message: Instance deleted

​
What Gets Deleted

When you delete an instance, the following data and configurations are permanently removed:
  • WhatsApp session: Instance is logged out from WhatsApp
  • Instance data: All database records for the instance
  • Messages and chats: All message history and chat data
  • Contacts: All contact information
  • Media files: All stored media (images, videos, documents)
  • Settings: All instance-specific settings
  • Integrations: All configured integrations (webhooks, Chatwoot, etc.)
  • Event subscriptions: All webhook and event system subscriptions
  • Cached data: All Redis/cache entries for the instance

​
Examples

curl -X DELETE "https://api.example.com/instance/delete/my-instance" \
  -H "apikey: YOUR_API_KEY"

​
Response Examples

Success Response
{
  "status": "SUCCESS",
  "error": false,
  "response": {
    "message": "Instance deleted"
  }
}
Error - Instance Not Found
{
  "error": true,
  "message": "The \"my-instance\" instance does not exist"
}
Error - Unauthorized
{
  "error": true,
  "message": "Unauthorized"
}

​
Deletion Process

When you call this endpoint, the following steps are executed:
  1. Validate instance exists - Check that the instance exists and you have permission
  2. Check connection state - Determine if instance is connected
  3. Logout from WhatsApp - If connected or connecting, perform logout
  4. Clear cache - Remove all cached data (Redis, Chatwoot cache)
  5. Send webhook notification - Trigger INSTANCE_DELETE webhook event
  6. Remove from registry - Remove instance from active instances list
  7. Delete database records - Remove all instance data from database
  8. Delete files - Remove stored media and session files
  9. Return confirmation - Confirm successful deletion

​
Webhook Notification

If you have webhooks configured, you’ll receive an INSTANCE_DELETE event:
INSTANCE_DELETE Event
{
  "event": "INSTANCE_DELETE",
  "instance": "my-instance",
  "data": {
    "instanceName": "my-instance",
    "instanceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
}
The webhook is sent before final deletion, so your webhook handler can perform cleanup tasks or logging.

​
Error Handling

The API returns standard HTTP status codes:
  • 200 - Success (instance deleted)
  • 400 - Bad request (instance doesn’t exist or deletion failed)
  • 401 - Unauthorized (invalid API key or no permission)
  • 500 - Internal server error
Common error scenarios:
  1. Instance doesn’t exist: The specified instance name is not found
  2. Permission denied: Your API key doesn’t have access to this instance
  3. Deletion in progress: Another deletion request is already being processed
  4. Database error: Temporary issue with database connection

​
Best Practices

Always confirm before deletion: Implement a confirmation step in your UI to prevent accidental deletions.
Export data first: If you need to preserve any data, export it before deleting the instance.
Update your records: Remove the instance from your application’s database or configuration after successful deletion.
Revoke webhooks: The instance will no longer send webhooks after deletion, so update your webhook handlers accordingly.

​
Alternative: Logout Without Deletion

If you want to disconnect from WhatsApp without deleting the instance, use the logout endpoint instead: 
curl -X DELETE "https://api.example.com/instance/logout/my-instance" \
  -H "apikey: YOUR_API_KEY"
This will:
  • Disconnect from WhatsApp
  • Preserve all instance data and settings
  • Allow you to reconnect later

​
Recovery Options

No recovery after deletion: Once an instance is deleted, it cannot be recovered. You will need to:
  1. Create a new instance with a different name
  2. Scan a new QR code to connect
  3. Reconfigure all settings and integrations
  4. You’ll lose all message history and contacts from the deleted instance

​
Rate Limiting

To prevent accidental mass deletions:
  • Maximum 10 deletions per minute
  • Maximum 100 deletions per hour
If you need to delete more instances, contact support for assistance.

​
Security Considerations

  1. API key security: Use instance-specific tokens when possible to limit deletion scope
  2. Audit logging: Log all deletion requests for security and compliance
  3. Two-factor confirmation: Consider implementing additional verification for deletion in production
  4. Role-based access: Restrict deletion permissions to administrators only

​
Use Cases

Development Testing 
// Clean up test instances after integration tests
const testInstances = ['test-instance-1', 'test-instance-2'];
for (const instance of testInstances) {
  await deleteInstance(instance);
}
User Requested Deletion 
// Handle user request to delete their WhatsApp connection
async function handleUserDeletion(userId, instanceName) {
  // Verify ownership
  if (await verifyInstanceOwnership(userId, instanceName)) {
    await deleteInstance(instanceName);
    await updateUserDatabase(userId, { instanceDeleted: true });
  }
}
Subscription Cancellation 
// Delete instances when subscription ends
async function handleSubscriptionCancelled(subscription) {
  const instances = await getInstancesBySubscription(subscription.id);
  for (const instance of instances) {
    await deleteInstance(instance.name);
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us