WhatsApp template submission and sync lifecycle runbook

WhatsApp template submission and sync lifecycle runbook explains how approved Meta templates move from Meta/SquareOS setup into campaign, automation, Inbox, profile activity, and mobile-safe usage without breaking variable order, approval state, consent, or delivery proof.

What this page is for

Who should use it

Owner, implementation, communications admin, marketing admin, platform admin, support

Where to find it

Meta WhatsApp Manager / Message templates, SquareOS Admin / WhatsApp Template Management

Before you start

WhatsApp template submission and sync lifecycle runbook: complete this lifecycle after Meta WhatsApp provider setup and before staff use a WhatsApp template in campaigns, automations, Inbox replies, profile activity, class group messages, or mobile actions.
WhatsApp template creation starts after a connected Meta WhatsApp Channel Account and Sender Account exist, and records template name, externalTemplateId, language code, category, header parameter keys, body parameter keys, body text, sender account, provider account, event key, and internal description.
Meta portal template request records WhatsApp Manager template name, language, category, components, header/body/footer/buttons, variable order, sample values, approval status, rejection reason, quality warnings, and provider template id before SquareOS marks the template approved.
SquareOS Submit template sets WhatsApp approvalStatus to PENDING, providerStatus to PENDING_REVIEW, submittedAt, rejectionReason null, lastSyncedAt, and an engagement.template.submit audit row.
SquareOS Sync templates or template sync must update approvalStatus, externalTemplateId, providerStatus, rejectionReason, syncedAt, language, category, and lastSyncedAt from the provider result or certified manual evidence.
Approved WhatsApp sends require active template status, approvalStatus APPROVED, externalTemplateId, matching language code, ordered body/header parameters from designJson, connected sender account, connected provider account, opt-in or service-window permission, and fake mode off for live certification.
Rejected or pending WhatsApp templates must keep campaign, automation, profile activity, Inbox, class group message, and mobile WhatsApp send actions disabled or routed to an approved replacement template.
Template variable QA must prove each SquareOS variable key maps to the same placeholder order approved in Meta and that missing variables fail closed or send only approved fallback text through a service-window path.
WhatsApp template secret handling forbids exposing Meta access tokens, app secret, webhook verify token, sample customer data, raw template submission payload, raw provider sync payload, or rejection screenshots containing private data in mobile screens, support tickets, analytics, or crash logs.
If Meta portal template labels or approval states differ from the runbook, extraction row must record template portal path attempted, copied value, SquareOS field, approver, rejection reason, replacement template id, and verification action.

Daily workflow

Confirm the Meta WhatsApp Channel Account is connected and the Sender Account exists for the same WABA/phone identity. SquareOS should reject WhatsApp template creation when the provider account is missing or not connected.
In Meta WhatsApp Manager / Message templates, create or review the template. Record the exact template name, language, category, component layout, header/body/footer/buttons, button URLs or quick replies, placeholder order, sample values, approval status, quality warning, rejection reason if any, and provider template id.
In SquareOS Admin / WhatsApp Template Management, create the template with channel WhatsApp, event key, sender account, provider account, externalTemplateId matching the approved Meta template name or id, language code such as en_US, category Utility/Marketing/Authentication, body text, header parameter keys, body parameter keys, and internal description.
Body parameter keys must be ordered exactly like the approved Meta body placeholders. Header parameter keys must be ordered exactly like the approved Meta header placeholders. Use SquareOS variable names such as memberName, dueAmount, appointmentDate, trainerName, or paymentLink according to the template event.
Click Submit only when the provider account, sender account, externalTemplateId, language, category, and variable order have been checked. SquareOS records approvalStatus PENDING, providerStatus PENDING_REVIEW, submittedAt, rejectionReason null, lastSyncedAt, and an engagement.template.submit audit row.
Use Sync templates after Meta approval or rejection. Sync must update approvalStatus, externalTemplateId, providerStatus, rejectionReason, syncedAt, language, category, and lastSyncedAt from provider result or certified manual evidence. If sync cannot read Meta directly, support must attach the Meta portal evidence row and mark the source as certified manual evidence.
For approved templates, run a variable QA send to an opted-in internal number. Confirm the worker sends Meta type template with template name externalTemplateId, language code, ordered header/body parameters from designJson, and no fallback text payload for the approved-template path.
For rejected templates, record the rejection reason, create a replacement template or fix the Meta template, keep the rejected template out of active campaigns and automations, and do not use manual free-form WhatsApp as a marketing workaround.
For pending templates, keep campaigns, automations, profile activity, Inbox, class group messages, and mobile WhatsApp sends disabled unless an active service-window free-form permission exists for the specific conversation.
For live certification, fake mode must be off. Send one approved template to an opted-in internal phone, verify Meta provider message id, signed status callback, delivery/read update, inbound reply mapping into Inbox/profile activity, DeliveryAttempt, Message, CampaignDeliveryLog if campaign-originated, and no unresolved dead-letter.
Record official source references used for the extraction row: Meta WhatsApp template creation/submission documentation, template components and parameters documentation, template status/rejection documentation, Cloud API template-message send documentation, and SquareOS audit/delivery evidence.

Watch out

Do not use the display label as externalTemplateId unless Meta confirms the approved template name/id is the same exact value. SquareOS sends Meta template payloads by externalTemplateId plus language.
Do not change body copy, placeholder order, language, category, or buttons in SquareOS after Meta approval unless the Meta template is also changed, resubmitted, synced, and recertified.
Do not mark a template approved from memory, chat screenshots, stale cache, or a staff note. Sync or certified manual evidence must record the provider status, synced time, approver, and rejection reason when relevant.
Do not expose Meta access tokens, app secret, webhook verify token, raw template submission payload, raw sync payload, sample customer values, or private rejection screenshots outside Admin/support-secure evidence.
Do not let mobile create, submit, sync, approve, reject, archive, or map WhatsApp templates. Mobile can only show read-only readiness and use backend-approved template sends.
Do not use fake-mode delivery attempt ids or unsynced approved labels as production proof. Live proof requires a real Meta provider message id, signed callback, and inbound reply evidence.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.