We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Media garbage collector

/v1/services/media/gc

The /services/media/gc endpoint provides a way for businesses to delete media from the database and file storage associated with their WhatsApp Business API client. When executed, garbage collector picks media which was not used for more than 30 days. When a media file is used to send a message, the 30 days rule will be reset for the file.

Before You Start

  • It is recommended you run this API request multiple times on larger databases (i.e., databases with a media table containing more than 10 million rows) to ensure the callbacks returns a complete status and no errors.
  • Media garbage collector works on the leader node and only one instance may work at a time

Request

PUT /v1/services/media/gc

Response

HTTP response

You should receive a response indicating the API request is being processed.

{
    "services": {
        "media": {
            "gc": {
                "status": "processing"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "3.0.0"
    }
}

Webhook notifications

Since the API request works asynchronously, once the garbage collection is complete, the WhatsApp Business API client will post a notification to the callback server in the following format.

{
    "services": [{
        "message": {
            "gc": {
                "items_deleted": 5,
                "status": "complete"
            }
        }
    }]
}

Errors

Errors Returned in Response

If the API request fails to initiate garbage collection, an error will be returned in the HTTP response.

{
    "meta": {
        "version": "3.0.0"
        "api_status": "stable"
    },
    "errors": [{
        "code": 1014,
        "title": "Internal error",
        "details": "Connection timed out. Please check if wacore is running: wacore:6252"
    }]
}

Webhook error notifications

If the garbage collection fails to complete, an error will be returned in the Webhook notification.

{
    "services": [{
        "media": {
            "gc": {
                "items_deleted": 0,
                "errors": [{
                    "code" : 1014,
                    "details" : "Could not delete media files",
                }],
            "status": "failed"
            }
        }
    }]
}