Skip to main content

WhatsApp Business

NearSync integrates with the Meta Business API (formerly Facebook Graph API) to send and receive WhatsApp messages directly from the admin dashboard. This integration powers the WhatsApp tab in Comms HQ and enables automatic lead creation from incoming messages.

What It Does​

Outbound Messaging​

From the admin dashboard, users can send WhatsApp messages to contacts:

  • Free-form messages -- Type and send a message to any WhatsApp number
  • Template messages -- Send pre-approved WhatsApp message templates (required by Meta for initiating conversations outside the 24-hour window)
  • Booking confirmations -- Automated WhatsApp notifications when bookings are created or updated

Messages are sent through the hyper-worker edge function, which calls the Meta Business API's messages endpoint with the configured phone number ID and access token.

Incoming Message Handling​

NearSync receives incoming WhatsApp messages through a webhook:

  1. Meta delivers incoming messages to the hyper-worker's WhatsApp webhook endpoint via HTTP POST.
  2. The hyper-worker validates the webhook payload using the verify token.
  3. The message is parsed, stored in the database, and linked to the appropriate contact record.
  4. The Comms HQ UI updates in real time to show the new message in the conversation thread.

Auto-Lead Creation​

When a WhatsApp message arrives from an unknown number (one not already associated with a contact in the CRM):

  1. The system creates a new contact record with the phone number.
  2. A new lead or deal is optionally created in Sales HQ, depending on organization settings.
  3. The message is linked to the newly created contact so the full conversation history is preserved from the first interaction.

This ensures no inbound inquiry falls through the cracks, even if the sender is not yet in the system.

Conversation Threading​

Messages are threaded by contact, creating a continuous conversation view in Comms HQ. Users can see the full message history with each contact, including both sent and received messages, with timestamps and delivery status.

Architecture​

The WhatsApp integration has two components:

  • hyper-worker edge function -- Handles outbound message sending (POST to Meta API), incoming webhook verification (GET), and incoming message processing (POST). Also handles the auto-lead creation logic.
  • @nearsync/comms-service package -- Provides client-side functions for sending messages and fetching conversation history. Calls the hyper-worker, which in turn calls the Meta API.

Credentials Required​

To enable WhatsApp messaging, the following credentials must be configured:

  • WhatsApp Phone Number ID -- The ID of the phone number registered with your WhatsApp Business account (found in the Meta Business Suite)
  • Access Token -- A permanent access token generated from your Meta Business app (used to authenticate API requests)
  • Verify Token -- A custom string you define, used by Meta to verify your webhook endpoint during setup

These credentials are stored in the organization's settings (not as environment variables) so they can be configured per-organization through the admin dashboard.

Meta Business Suite Setup​

To configure the WhatsApp integration:

  1. Create a Meta Business App at developers.facebook.com
  2. Add the WhatsApp product to your app
  3. Register and verify a phone number for your WhatsApp Business account
  4. Generate a permanent access token with the whatsapp_business_messaging permission
  5. Configure the webhook URL to point to your hyper-worker's WhatsApp endpoint
  6. Set the verify token to match what you configure in NearSync
  7. Subscribe to the messages webhook field

Webhook Verification​

When you configure the webhook URL in the Meta Business Suite, Meta sends a GET request with a challenge parameter. The hyper-worker responds with the challenge value if the verify token matches, completing the handshake.

If WhatsApp Is Unavailable​

  • Outbound WhatsApp messages fail to send
  • Incoming messages are not received (Meta cannot deliver webhook payloads)
  • Booking WhatsApp confirmations fail, but the booking itself is still created and email confirmations still send
  • Other communication channels (voice, email) continue to work independently
  • The WhatsApp tab in Comms HQ will display an error state

WhatsApp is a dedicated messaging channel with no automatic fallback to another messaging platform. If Meta's API is experiencing issues, messages will be retried by Meta's infrastructure according to their delivery policies.