WhatsApp Cloud — Deployment

Catalog

Billable module whatsapp-cloud 1.4.0 (CRM). Register and bump via migrate-only data migrations:

Migration	Effect
2026_08_16_100005_register_whatsapp_cloud_module	Register 1.0.0
2026_08_16_100006_add_whatsapp_cloud_permissions	Permissions
2026_08_21_234243_add_auto_create_leads_to_whatsapp_connections_table	Lead Source columns
2026_08_21_234245_bump_whatsapp_cloud_module_version_to_1_1_0	1.0.0 → 1.1.0
2026_08_21_235205_bump_automation_and_whatsapp_cloud_for_wa_triggers	Automation 1.1.0, WA 1.2.0
2026_08_21_235553_create_whatsapp_message_attachments_table	Media attachments
2026_08_21_235556_bump_whatsapp_cloud_module_version_to_1_3_0	1.2.0 → 1.3.0
2026_09_27_213615_add_interactive_payload_to_whatsapp_messages_table	interactive_payload JSON
2026_09_27_214240_bump_whatsapp_cloud_module_version_to_1_4_0	1.3.0 → 1.4.0

Do not rely on db:seed in production.

Environment

META_GRAPH_VERSION=v21.0
# Shared with Lead Ads when empty:
META_LEAD_ADS_APP_ID=
META_LEAD_ADS_APP_SECRET=
META_LEAD_ADS_WEBHOOK_VERIFY_TOKEN=
# Optional WhatsApp-specific overrides:
META_WHATSAPP_APP_ID=
META_WHATSAPP_APP_SECRET=
META_WHATSAPP_WEBHOOK_VERIFY_TOKEN=
# Local / Playwright only — never set in production.
# When APP_ENV=production, a truthy META_HTTP_FAKE refuses boot (hard fail).
# META_HTTP_FAKE=true

Central settings keys (encrypted secrets): meta_whatsapp_app_id, meta_whatsapp_app_secret, meta_whatsapp_webhook_verify_token (fall back to Lead Ads keys).

Align FRONTEND_URL with the SPA origin tenants use (OAuth callback redirects here).

Production cutover: confirm META_HTTP_FAKE is unset (or false) in Forge/Cloud env before deploy.

Meta App

1. Enable WhatsApp product on the platform Meta App (may share portfolio with Lead Ads).
2. Webhook callback: {APP_URL}/webhooks/whatsapp/cloud — subscribe to messages.
3. OAuth redirect: {APP_URL}/api/oauth/whatsapp/cloud/callback
4. Verify token must match Central / env.

See Meta App Setup (WhatsApp section).

Queues

Queue	Jobs
whatsapp-inbound	ProcessWhatsAppWebhookJob, DownloadWhatsAppMediaJob
whatsapp-outbound	SendWhatsAppMessageJob (text / template / media)
automations	WA trigger/action workflow runs (when Automation entitled)

Workers must listen to WhatsApp queues (and automations when using WA Automation). See Forge notes in Laravel Forge and the production readiness pre-flight.

Soft dependencies

Feature	Also entitle
Lead soft-link / Lead Source auto-create	Leads
Media send/receive counting toward quota	Storage (free module / packs as needed)
WA Automation trigger/action	Automation 1.1.0+

Smoke

1. Install module → connect OAuth → select WABA → select phone.
2. Inbound test message creates conversation; soft-link a Lead from the inbox header.
3. Reply text inside 24h; template outside 24h.
4. (1.1) Toggle auto-create leads; confirm unknown inbound creates/links Lead; toggle off.
5. (1.2) Automation workflow on whatsapp.message_received; optional send_whatsapp_template.
6. (1.3) Inbound media downloads; outbound attach inside 24h; Storage quota respected.
7. Disconnect retains history and releases the Meta phone id for reclaim; tokens cleared.

Full go-live checklist: WhatsApp Cloud production readiness.