Zodiac Tech CRM Docs

Connect WhatsApp

Wizard step 10 — connect your WhatsApp Business number via the WhatsApp Cloud API. Optional, but it is where most conversations happen.

client admin Medium ⏱ 10 min Updated 2026-10-05

Connect WhatsApp

This is wizard step 10: "Talk to leads on WhatsApp". Connecting brings your WhatsApp Business number into the CRM: leads can be messaged, replies land in the WhatsApp inbox next to their lead record, and automations can greet new leads instantly.

This step is optional and skippable — the wizard says it plainly: "You can set this up any time — it is not required to start using your CRM."

Who this is for

  • Workspace owners and admins connecting the business number.
  • Admins re-connecting after a token was rotated.

Difficulty: Medium (you copy a few values between Meta and the CRM) · Time: 10 minutes · Prerequisites:

  • A WhatsApp Business Account (WABA) with a phone number registered on the WhatsApp Cloud API.
  • A Meta app/business that can see that WABA, with a permanent access token and the app secret.
  • Admin access to the platform's Meta configuration (ask Zodiac Tech support if the number was set up for you).

Step by step

1. Open the WhatsApp settings

  1. In the wizard step, click Connect WhatsApp (or go directly to Settings → Connections → WhatsApp, /admin/settings/whatsapp).
  2. What happens: the WhatsApp connection page opens with the credential fields and a webhook callback URL.

2. Fill in the connection details

Field Where it comes from
WABA ID Your WhatsApp Business Account id (Meta Business settings)
Phone number ID The id of the sending phone number (Cloud API settings — the numeric id, not the phone number itself)
Display phone number The number your customers see (for example +91 …)
Access token A permanent token with WhatsApp messaging permission
App secret The Meta app's secret (used to verify incoming webhooks)
Verify token A value you choose — it must be identical in Meta's webhook configuration and here
  1. Paste the values and Save.
  2. What happens: the CRM runs a health check against the number, then stores the credentials encrypted at rest. On later saves, a masked value (••••••••••••) keeps the stored secret unless you type a replacement.
  3. Expected result: the connection shows a healthy, connected state.

The verify token is a handshake, not a password Meta proves it can reach your CRM by echoing the verify token when the webhook is configured. The token must match exactly in both places, or Meta marks the webhook as failed.

3. Point Meta's webhook at your CRM

  1. Copy the callback URL shown on the connection page.
  2. In the Meta app's WhatsApp configuration, paste the callback URL and your verify token, and subscribe to message events.
  3. Expected result: Meta verifies the webhook successfully (a green "verified" state on Meta's side) and message events start flowing.

4. Prove it works

  1. Use the page's actions:
    • Sync Templates — pulls your approved message templates from Meta (required before template messages).
    • Test Message — sends a test message to your own number so you can see it work end to end.
  2. Expected result: the test message arrives on WhatsApp; the number is ready for the inbox and automations.

Free-form or template? WhatsApp only allows free-form replies within 24 hours of the customer's last message. Outside that window you must send an approved template. The CRM handles this rule for you in the inbox and in automations — the full story is in How WhatsApp messages are delivered.

5. Skipping for now

Click the skip option on the step. The step settles as SKIPPED (visible to Zodiac Tech) and auto-completes as soon as a healthy WhatsApp connection exists. You can connect any time from Settings → Connections → WhatsApp.

Expected result

  • A connected WhatsApp number on your workspace: credentials stored encrypted, webhook verified, templates synced, test message received.
  • The wizard step completes; incoming replies appear in WhatsApp inbox.

Common mistakes

  • Confusing the WABA id with the phone number id. They are different values; the phone number id is numeric and lives on the phone number's Cloud API page.
  • Using a temporary token. Temporary tokens expire within hours. Use a permanent token, or messages stop silently.
  • Mismatched verify token. Meta's webhook shows "verification failed" and no messages arrive.
  • Connecting a number that is still on the WhatsApp app/BSP. A number can only be active on one platform at a time — migrating it may require removing it from the other provider first.
  • Skipping Sync Templates. Without templates, you cannot message customers outside the 24-hour window.

Troubleshooting

Symptom Likely cause Fix
Save fails health check Wrong token / phone number id, or token missing WhatsApp permission Re-check the values in Meta, then save again
Test message fails Token expired or number not fully registered on Cloud API Regenerate a permanent token; complete Cloud API registration
Webhook never verifies in Meta Verify token mismatch or wrong callback URL Re-copy both from the connection page
Messages arrive in Meta but not the CRM Webhook not subscribed to message events Subscribe to the messages field in the Meta app configuration
Nothing sends after it worked before Token rotated or revoked Reconnect and re-save credentials
Want a clean removal — Use Disconnect to detach the number from the CRM

STOP is respected automatically Leads who reply with STOP are opted out of WhatsApp by the CRM; automations skip them. Their record shows the opt-out so your team knows why.

Technical details

  • Page: App\Filament\Pages\Settings\WhatsAppConnectionPage (settings/whatsapp). Credentials live on the whatsapp_connections table with access_token, app_secret and verify_token encrypted; legacy tenants.settings.messaging values are still read as a decrypt-fallback.
  • Sending: App\Services\WhatsApp\* (MetaCloudWhatsAppProvider, message/template/media services) — sends via graph.facebook.com/{version}/{phone_number_id}/messages.
  • Receiving: message and status webhooks are verified with X-Hub-Signature-256, then processed into conversations + WhatsApp messages; delivery statuses apply through WhatsAppMessageService (monotonic status ladder).
  • Resolver condition (whatsapp): a WhatsAppConnection with status connected (isConnected()).
  • STOP opt-out is stored on the lead (leads.whatsapp_opted_out_*).

Was this page helpful?