Skip to content

Template Deletion

Removing a WhatsApp message template from a WABA by name (every language) or by ID, after which an approved template's name stays blocked for 30 days.

Also called: Delete WhatsApp template · Delete message template · Template removal · PENDING_DELETION

Reviewed

Interactive lab

Hands on: use the controls to explore. Anything that plays on its own pauses while you are working inside it.

Send the DELETE and read what comes back

2 / 2
DELETEhttps://graph.facebook.com/v26.0/102290129340398/message_templates?name=order_eta&hsm_id=1407680676729941

DELETE 200 in 650 ms

Request

2 headers
DELETE /v26.0/102290129340398/message_templates?name=order_eta&hsm_id=1407680676729941 HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true
}
Try another response
A delete by name plus hsm_id removes one language version of order_eta. Toggle the alternatives to see the permissions error and a bulk request where one bad ID means nothing is deleted.

Response: 200 OK after 650 ms.

01What is template deletion?

Template deletion removes a message template from a WhatsApp Business Account (WABA) so it can no longer be sent. It is done in WhatsApp Manager or with a DELETE request to the WABA's message_templates edge, using a token that holds the whatsapp_business_management permission — a token with only whatsapp_business_messaging gets a permissions error (code 200).

How you identify the template decides how much is removed. Passing only name deletes every template with that name — all of its language versions at once. Adding hsm_id (the template ID) alongside name deletes just that one translation. For clean-ups, hsm_ids takes an array of up to 100 template IDs; it cannot be combined with name or hsm_id, and if any ID in the list is invalid, nothing is deleted.

Deletion has after-effects worth planning for. If a message using the template was sent but not yet delivered — the customer's phone is off, say — the template moves to PENDING_DELETION and WhatsApp keeps trying to deliver that message for 30 days. Once an approved template is deleted, its name cannot be used for a new template for 30 days. Disabled templates cannot be deleted at all.

That finality is what separates deletion from editing. An edit keeps the template's ID and name and sends the new content back to review; deleting and recreating gives you a new ID, a full new review and, for an approved name, a month-long wait before the name is free again.

Key takeaways

  • Template deletion removes a WhatsApp template from a WABA, in WhatsApp Manager or with DELETE /{WABA_ID}/message_templates.
  • Deleting by name alone removes every language version; add hsm_id to delete one translation, or pass hsm_ids for up to 100 IDs.
  • Once an approved template is deleted, its name cannot be used for a new template for 30 days.
  • Undelivered messages keep a deleted template in PENDING_DELETION while WhatsApp retries delivery for 30 days.
  • Deletion needs the whatsapp_business_management permission, and templates in a disabled status cannot be deleted.

02 · How it works, step by step

How does template deletion work?

  1. Step 1

    Find the exact template

    List templates with GET /{WABA_ID}/message_templates?fields=id,name,language,status and note the id of each language version you mean to remove.

  2. Step 2

    Check that nothing still sends it

    Search campaigns, journeys, chatbot flows and code for the template name and language. A deleted template can no longer be sent, so retire every reference first.

  3. Step 3

    Choose the scope

    Use name alone to remove every language version, name plus hsm_id for one translation, or hsm_ids with up to 100 IDs for a bulk clean-up.

  4. Step 4

    Send the DELETE and read the result

    A successful call returns {"success": true}. A template with messages still in flight shows PENDING_DELETION while WhatsApp keeps trying to deliver them for up to 30 days.

  5. Step 5

    Plan around the name lock

    If you will want the same name again — for a corrected version, say — expect a 30-day wait after deleting an approved template. Editing it in place avoids the wait.

03Template deletion in code

# One language version: name + template ID
curl -X DELETE \
  "https://graph.facebook.com/v26.0/{WABA_ID}/message_templates?name=order_eta&hsm_id={TEMPLATE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
 
# Every language version of a name
curl -X DELETE \
  "https://graph.facebook.com/v26.0/{WABA_ID}/message_templates?name=diwali_sale_2025" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
 
# Bulk by ID: up to 100, not combinable with name or hsm_id
curl -X DELETE -G \
  "https://graph.facebook.com/v26.0/{WABA_ID}/message_templates" \
  --data-urlencode "hsm_ids=[1387372356726668,1304694804498707]" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
 
# Each successful call returns: {"success": true}

04 · Common mistakes, and the fix

Common mistakes with template deletion

  • Deleting by name when you meant one language

    name alone removes every translation. Pass the translation's hsm_id with the name whenever only one language should go.

  • Deleting a template automation still uses

    Journeys and bots that reference the template start failing as soon as it is gone. Retire references and confirm no scheduled send uses it before deleting.

  • Deleting and recreating to fix a typo

    For an approved template the name is then locked for 30 days and the new template needs a full review. Edit it instead — an edit keeps the ID and the name.

  • Sending a bulk list with one stale ID

    If any ID in hsm_ids is invalid, the whole request fails and nothing is deleted. Re-list templates just before a bulk call and drop IDs that are already gone.

  • Using a messaging-only token

    Tokens scoped to whatsapp_business_messaging can send templates but not manage them. Deletion needs whatsapp_business_management, or the call fails with code 200.

05Template deletion: key facts and limits

Endpoint
DELETE /{WABA_ID}/message_templates
By name only
Deletes every language version
By name + hsm_id
Deletes one template ID
Bulk
hsm_ids, up to 100 IDs per request
Undelivered messages
PENDING_DELETION, retried for 30 days
Name reuse (approved template)
Blocked for 30 days
Permission
whatsapp_business_management
Disabled templates
Cannot be deleted

06Example: A clean-up that kept two translations alive

A Bengaluru food-delivery start-up is close to its template limit after two years of festive campaigns. Its developer lists the WABA's templates, finds 140 rejected or retired marketing drafts, confirms the campaign tool no longer references any of them, and removes them in two hsm_ids calls of up to 100 IDs each. One live template, order_eta, exists in English, Kannada and Hindi, and only the English copy is outdated. The team edits that translation instead of deleting anything: deleting by name would have removed all three versions, and recreating the English one under the same name would have meant a 30-day wait.

07Why does template deletion matter?

Deletion is housekeeping with sharp edges. Every WABA has a template limit, so unused campaigns and rejected drafts eventually have to go — but a careless call by name can remove the Hindi and Tamil versions along with the one English draft you meant to drop, and deleting a live template breaks every journey, bot or code path that still sends it. Knowing the scope rules and the 30-day name lock turns clean-up into a safe routine instead of an outage.

08Template Deletion FAQs

Can I undo a template deletion?+
Not through the API — there is no restore call. Recreate the template from your own records and submit it for review, remembering that a deleted approved template's name is blocked for 30 days.
What happens to messages already sent with a deleted template?+
Delivered messages stay in the customer's chat. Messages not yet delivered keep being retried for 30 days while the template shows PENDING_DELETION; after that they are not delivered.
Why can't I delete a disabled template?+
Meta does not allow it. A template disabled after repeated low-quality pauses stays on the WABA. You can edit it and resubmit it for review, or create a new template with different content.
Does deleting a template free a slot under the template limit?+
Yes, deletion is how you make room under the 250 or 6,000 cap. Each language version counts separately, so deleting one translation frees one slot.

09 · Tips from the bench

Best practices for template deletion

  • Log the template ID, name, language, category and components before every deletion so a mistaken clean-up can be rebuilt.
  • Let Meta's archiving handle long-idle templates: after 12 months without use they are archived, then deleted 28 days later unless unarchived.
  • Run bulk deletions in batches of 100 IDs or fewer, one batch per request.
  • Treat PENDING_DELETION as normal — it means messages are still in flight, not that the call failed.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms