Skip to content

Template Migration

Also called: Migrate message templates · Template duplication · Copy templates between WABAs · migrate_message_templates

Copying approved WhatsApp templates from one WABA into another WABA owned by the same business, recreating them there rather than moving them.

Reviewed

What is template migration?

Template migration copies message templates from a source WhatsApp Business Account (WABA) into a destination WABA owned by the same Meta business. Despite the name, nothing moves: Meta recreates each eligible template in the destination as a new template with its own ID, and the originals stay where they were. Businesses use it when they open a second WABA for a new brand or region, consolidate accounts, or set up with a new Solution Partner and want their proven templates on the new account without drafting and reviewing them again.

Eligibility is narrow. Only templates whose status is APPROVED and whose quality_score is GREEN or UNKNOWN qualify, and both WABAs must belong to the same business; templates cannot be copied into another company's account. The call is POST /{DESTINATION_WABA_ID}/migrate_message_templates with source_waba_id, made with a system user or business token. Each request handles up to 500 templates: a zero-indexed page_number walks larger sets in batches of 500, count shrinks the batch, and template_ids (up to 500) retries specific templates.

The response splits the result in two: migrated_templates, the IDs that were duplicated, and failed_templates, a map of template IDs to reasons such as "Incorrect category" or "Formatting error - dangling parameter". Anything that fails does not exist in the destination until it is fixed and created there the normal way, through review.

Template migration is not phone number migration, which moves a registered number between WABAs or partners. When a number moves through Meta's partner-migration flow, templates that are APPROVED with a GREEN quality score are duplicated automatically, up to the destination's template limit; Meta's guide says the copies start with their source status, are re-checked for category (some can end up REJECTED) and start with an UNKNOWN quality rating. The migration endpoint is the tool for making the same copy deliberately, without moving a number, or for catching up on what the automatic duplication left behind.

Key takeaways

  • Template migration copies approved WhatsApp templates from one WABA to another WABA owned by the same business.
  • Only templates with status APPROVED and quality_score GREEN or UNKNOWN qualify, and copying to another company's WABA is not possible.
  • Call POST /{DESTINATION_WABA_ID}/migrate_message_templates with source_waba_id; each request handles up to 500 templates.
  • The response lists migrated_templates and failed_templates with a reason for each failure; failed templates must be fixed and created again.
  • Copies are new templates with new IDs in the destination, so remap stored template IDs before cut-over; names and languages stay the same.

See InfiQ pricing

Interactive stop

Step through a template migration call by call

9 / 9
  • Your scriptsystem user token
  • Graph APIv26.0
  • Source WABA312 templates
  • Destination WABAsame business

Step 9 of 9Response

Graph APIYour script

All required templates APPROVED: cut over

Sends now use the new WABA's phone number ID with the same names and languages.

  • Request — solid arrow — a call that expects an answer
  • Response — dashed arrow — the answer coming back
  • Event — dotted arrow — something happened and is pushed out
  • Async — double head — fire-and-forget, nobody waits
The pharmacy chain from the example copies its approved templates into a second WABA. Step through the audit, the migrate call, the split into migrated and failed templates, the retry and the final check before cut-over.

Step 9 of 9: Graph API to Your script — All required templates APPROVED: cut over. Sends now use the new WABA's phone number ID with the same names and languages.

How does template migration work?

  1. Confirm ownership and access

    Both WABAs must sit in the same business portfolio. Use a system user (or business) token that has whatsapp_business_management and is assigned to both accounts.

  2. Audit the source

    List what will qualify with GET /{SOURCE_WABA_ID}/message_templates?status=APPROVED&fields=id,name,language,quality_score. Anything paused, rejected or rated YELLOW or RED will not be copied, and copies count against the destination's template limit.

  3. Run the migration in batches

    POST /{DESTINATION_WABA_ID}/migrate_message_templates?source_waba_id={SOURCE_WABA_ID}&page_number=0. For 1,000 templates send pages 0 and 1; if a request runs past about 30 seconds and times out, lower count.

  4. Read both lists in the response

    Store migrated_templates and log every entry in failed_templates with its reason. Each reason tells you whether the template needs a formatting fix or a different category.

  5. Fix, retry or recreate the failures

    Retry transient failures with template_ids. For content problems, fix the template and create it in the destination with the Template Management API, where it goes through normal review.

  6. Verify, remap and cut over

    List the destination's templates, confirm each one you need is APPROVED, map old IDs to new ones by name and language, and only then point sends at the new WABA's phone number.

Example: A second WABA for a pharmacy chain's franchise network

An Ahmedabad pharmacy chain sets up a second WABA in the same business portfolio for its new franchise stores. The source account holds 312 templates; 268 are approved, and 251 of those have a GREEN or UNKNOWN quality score. One call with page_number=0 covers them all: 246 come back in migrated_templates and 5 in failed_templates, three marked "Incorrect category" and two with a dangling parameter. The developer adds closing text to the two formatting failures and creates them in the destination, where they are approved within hours, and the marketing team redrafts the three miscategorised reminders. Before cut-over the script lists the destination, confirms every template the franchise app uses is APPROVED, rewrites the stored template IDs, and keeps the 17 approved templates rated YELLOW or RED on the original WABA until they are reworked.

— A second WABA for a pharmacy chain's franchise network

Template migration in code

curl -X POST \
  "https://graph.facebook.com/v26.0/{DESTINATION_WABA_ID}/migrate_message_templates?source_waba_id={SOURCE_WABA_ID}&page_number=0" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
 
# 200 OK
# {
#   "migrated_templates": ["1473688840035974", "6162904357082268", "6147830171896170"],
#   "failed_templates": {
#     "1019496902803242": "Incorrect category",
#     "259672276895259": "Formatting error - dangling parameter"
#   }
# }

page_number is zero-indexed and each page is up to 500 templates.

Common mistakes with template migration

  • Expecting to migrate to another company

    The endpoint only works between WABAs owned by the same business. If the destination belongs to a different business, the templates have to be created there and reviewed from scratch.

  • Assuming every template comes along

    Paused, rejected and YELLOW- or RED-rated templates are not eligible. Audit the source first and plan fixes for anything the destination will need but cannot receive.

  • Ignoring failed_templates

    A failure means the template does not exist in the destination. Switch traffic without handling it and sends fail with 132001; log every reason and resolve each one before cut-over.

  • Reusing source template IDs

    Copies are new templates with new IDs. Sending by name and language keeps working, but anything keyed on template IDs, such as analytics, edits or deletes by hsm_id, must be remapped.

  • Cutting over on migration day

    Copies may need checking and failures need review time. Migrate days ahead, verify the destination's statuses, and keep the source WABA's templates until the new account has run cleanly.

Template migration: key facts and limits

Endpoint
POST /{DESTINATION_WABA_ID}/migrate_message_templates
Required parameter
source_waba_id
Ownership
Both WABAs owned by the same business
Eligible templates
APPROVED, quality_score GREEN or UNKNOWN
Batch size
Up to 500 per request (page_number, count)
Targeted retry
template_ids, up to 500 IDs
Response
migrated_templates + failed_templates (ID → reason)
Result
New copies with new IDs; source templates unchanged

Template Migration FAQs

Can I migrate WhatsApp templates to a WABA owned by another business?+
No. Template migration only works between WABAs owned by the same business. For an account owned by a different business, recreate the templates there and submit them for review.
Do my templates move automatically when I migrate my phone number?+
Partly. When a number moves through Meta's partner-migration flow, approved templates with a GREEN quality score are duplicated automatically up to the destination's template limit. Everything else must be recreated, or copied with the migration endpoint if it qualifies.
Do migrated templates need approval again?+
Eligible copies are created without you resubmitting them, but check each copy's status in the destination. Meta's partner-migration guide notes that duplicates are re-checked for category and some can end up rejected.
Does a template's quality rating carry over to the copy?+
No. According to Meta's partner-migration guide, duplicated templates start with an UNKNOWN rating, and a new one can appear after about 24 hours once there is enough data.
How many templates can I migrate in one request?+
Up to 500. For larger sets, send one request per page using the zero-indexed `page_number`, and lower `count` if a request takes longer than about 30 seconds.

Why does template migration matter?

Re-drafting and re-reviewing hundreds of approved templates is slow, and every review is another chance of a rejection or a category change landing on launch week. Migration lets a business stand up a new WABA with its working templates in minutes, keeping names and languages identical so sending code needs only a new WABA ID and phone number ID. The details are what make or break a cut-over: paused or low-quality templates are left behind, failures come back as a list you must act on, and every copy has a new ID, so a team that knows the rules plans the switch instead of discovering missing templates through 132001 errors.

Best practices for template migration

  • Check the destination's template limit before migrating; copies count against it like any template.
  • Build an old-ID to new-ID map keyed by name and language right after the call, while both accounts are fresh in the logs.
  • Rework YELLOW and RED templates before the move rather than carrying weak copy into a new account.
  • Expect copies to build their own quality history: Meta's partner-migration guide says ratings are not duplicated.

Talk to InfiQ

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