Skip to Content
WhatsApp MCPPlan & PhasesOpsPhone Number Onboarding

Runbook — Phone Number Onboarding (stub)

This is a stub. The full runbook is promoted to docs/operations/phone-number-onboarding.md in Phase 7.

What this runbook covers

Adding a new WABA phone number to the server, registering it with Meta, and linking it to one or more clients.

Outline

Meta side

  1. In the Meta Business Manager → WhatsApp Manager, add the new phone number to an existing WABA (or create a new WABA).
  2. Verify the number (SMS or voice OTP).
  3. Generate a System User token scoped to the WABA (or reuse an existing one if the WABA is already wired).
  4. In the App Dashboard → WhatsApp → Configuration, subscribe the webhook URL https://wa.<yourdomain>/webhook/meta to this phone number, using a per-number verify token.

Secrets (Phase 7 onwards)

  1. Add three entries to ops/secrets/secrets.enc.yaml under unique keys: wa_access_token_<phone_id>, wa_app_secret_<phone_id> (often shared across WABA — confirm), wa_webhook_verify_token_<phone_id>.
  2. sops -e -i ops/secrets/secrets.enc.yaml, commit, deploy. Secrets re-materialise on systemctl restart whatsapp-mcp.

DB side

  1. admin numbers add --waba <waba-id> --phone-id <meta-phone-id> --display-number "+44..." --label "<context>" --token-ref secrets://wa_access_token_<phone_id> --app-secret-ref secrets://wa_app_secret_<phone_id> --verify-token-ref secrets://wa_webhook_verify_token_<phone_id>.
  2. The CLI writes the row and returns the internal phone_number_id UUID.
  1. admin grants add --client <client-id> --phone <internal-phone-id> --tools "send_message,get_messages,..." for every client that should use this number.

Verify

  1. From Meta dashboard, send a test webhook → server returns 200 within 200 ms, signature verified, messages row inserted.
  2. From the client: send_message with phoneNumberId = <internal-phone-id> succeeds, message arrives on the recipient’s WhatsApp.
  3. SELECT * FROM audit_log WHERE phone_number_id = '<internal-phone-id>' ORDER BY ts DESC LIMIT 10 shows the expected actions.

Open items

Full runbook will include the exact Meta dashboard click paths, a checklist for verifying the webhook subscription, and the rollback procedure if a number is added incorrectly.

Incident RunbookUpgrade