Skip to Content
WhatsApp MCPPlan & PhasesOpsUpgrade

Runbook — Graph API Version Upgrade (stub)

This is a stub. The full runbook is promoted to docs/operations/upgrade.md in Phase 7.

What this runbook covers

The quarterly procedure for bumping the pinned Meta Graph API version (e.g. v23.0 → v24.0). Includes app version bumps and the rolling deploy sequence.

Outline

Graph API version bump (quarterly)

  1. Read the changelog — https://developers.facebook.com/docs/graph-api/changelog/breaking-changes for the target version. Note any breaking changes to:

    • Webhook payload shapes.
    • Message send endpoint structures.
    • Media upload/download endpoints.
    • Error codes (additions or removals).

  2. Update fixtures + types — apply any payload changes to src/meta/types.ts. Update test fixtures in tests/fixtures/meta-payloads/ to reflect new shapes.

  3. Branch and test — bump WA_GRAPH_API_VERSION in .env.example and docker-compose.prod.yml. Run full pnpm test:ci against the new version’s mocked endpoints.

  4. Staging dry-run — deploy to a staging compose pointing at a Meta test number. Run the smoke checklist. Send + receive across every message type.

  5. Production deploy — merge, deploy, watch audit_log for new error codes. Have a quick rollback path ready (revert + redeploy).

App version bumps

  • Patch / minor: standard rolling deploy. Inngest functions are versioned per the SDK; functions in-flight at deploy time finish on the old version, new events use the new version.
  • Major: read the migration notes. Drizzle migrations apply automatically on app startup — but DB-breaking changes require a maintenance window, documented per-bump.

Rolling deploy sequence

  1. CI builds image with new SHA, pushes to ghcr.io.
  2. On the host: cd /opt/whatsapp-mcp && git pull.
  3. docker compose pull app.
  4. docker compose up -d app — Compose restarts the app; Postgres + Nginx keep running.
  5. /health reaches 200 within 30 s.
  6. pnpm smoke green.

Rollback (forward-only migrations + restore-from-backup)

Drizzle is forward-only — there are no auto-generated DOWN scripts. The rollback policy is:

  1. App-only rollback (no schema change in the broken release): git checkout <previous-sha> → docker compose pull && docker compose up -d. Done in < 1 minute.
  2. App + schema rollback (broken release ran a migration): you cannot un-apply the migration in place. Instead:
    • Take an immediate pg_dump of the current (broken) state to a quarantine file in case forensics is needed.
    • Restore the latest pre-deploy pg_dump from /var/lib/whatsapp-mcp/backups/ into a fresh Postgres volume (see backups.md). Recent data since the last backup is lost — acceptable trade for “rollback safely”.
    • Deploy the previous app SHA.
    • Investigate the failed migration in a staging branch; fix forward in a new migration; re-deploy.

This is why backup cadence matters. Nightly is the floor; if a phase introduces a high-churn migration, take an ad-hoc pg_dump immediately before the deploy.

Open items

Full runbook will include the exact changelog-watching schedule (calendar invite), the staging compose file, and a per-version verification matrix.

Phone Number OnboardingDatabase