Skip to content
Thirdlane

WhatsApp Accounts

WhatsApp Business Accounts connect your system to the Meta WhatsApp Cloud API, enabling WhatsApp messaging through Thirdlane Connect. Each tenant can have one or more WhatsApp Business accounts, subject to the limit set by the administrator.

Prerequisites

Before configuring a WhatsApp Business Account, you need:

  1. A Meta Business Account with access to the WhatsApp Business Platform
  2. A WhatsApp Business Account (WABA) created in the Meta Business Manager
  3. A System User Access Token with whatsapp_business_messaging and whatsapp_business_management permissions
  4. At least one phone number registered with your WABA

Create/Edit WhatsApp Account

Name. A friendly name to identify this WhatsApp Business account (e.g., “Support WhatsApp” or “Sales WABA”).

Domain. Hostname used in the inbound webhook URL Meta posts to. When the system has one hostname under Domain and SSL Certificate, this field is filled automatically and is not shown. It appears only if more than one SSL hostname is configured.

WABA ID. The WhatsApp Business Account ID from Meta Business Manager. Found under Business Settings > Accounts > WhatsApp Accounts.

Access Token. A permanent System User Access Token generated in Meta Business Manager. This token authenticates API calls to send messages and manage phone numbers.

App Secret. The App Secret from your Meta App settings. Used to verify the signature of incoming webhook payloads from Meta, ensuring they are authentic.

Verify Token. A custom string you define. When Meta sends a webhook verification request, it includes this token so the system can confirm the webhook subscription is legitimate. Choose any secure random string.

Status. The current connection status of this account:

  • Active — Connected and operational
  • Inactive — Not yet configured or intentionally disabled
  • Error — Connection issue detected (see status message for details)

Phone Numbers

After creating a WhatsApp account, use the Sync Phones button to retrieve all phone numbers registered under your WABA from Meta. Each phone number shows:

  • Display Phone Number — The phone number as displayed to recipients
  • Verified Name — The business name verified by Meta for this number
  • Quality Rating — Meta’s quality assessment of the number (GREEN is healthy, YELLOW is a warning, RED means quality is low and messaging may be throttled or blocked). Quality is driven largely by how recipients react - blocks and “report” actions lower it, so only message people who expect to hear from you.
  • Messaging Limit — Current sending tier assigned by Meta. Numbers start at a low tier and Meta raises the limit automatically as you send quality traffic over time.
  • Status — Registration status of the phone number
  • DID — The DID/phone number mapped to this WhatsApp number for routing

Message Templates

Use the Sync Templates button to retrieve approved message templates from Meta. Templates are required for initiating conversations with contacts outside the 24-hour messaging window. Each template shows its name, language, category, approval status, and component structure.

Variable Mappings

Templates contain numbered variable placeholders ({{1}}, {{2}}, etc.) that must be filled with actual values when sending. The mapping status column in the template grid shows how many variables have been mapped (e.g., “3/7 mapped”).

Click the pencil icon on any template row to open the Variable Mappings window. The window shows a grid of all parsed variables with their index, component type (HEADER, BODY, BUTTONS), and example value from Meta.

Click the pencil icon on any variable row to configure its mapping:

  • Source — where the value comes from:
    • Contact Field — from the CRM contact record (name, email, phone, etc.)
    • Account Field — from the contact’s linked company/account record
    • Custom Field — from a tenant-defined custom field
    • Static Value — always uses the default value you enter
    • Agent Enters — the agent fills the value manually at send time
  • Field — the specific field to use (dropdown updates based on the selected source)
  • Default Value — fallback value if the mapped field is empty
  • Label — optional label shown to agents to describe what to enter

After editing one or more variables, click Save at the bottom of the mappings window to persist all changes. Click Cancel to discard changes. If you close the window (via the X button) with unsaved changes, you will be prompted to confirm.

Webhook Configuration

To receive inbound WhatsApp messages, you must configure a webhook in your Meta App settings. After you save the account, the form shows the callback URL:

https://pbx.example.com/sms/whatsapp/WABA_ID

The hostname is the domain on the account (the public hostname from Domain and SSL Certificate). WABA_ID is the WhatsApp Business Account ID you entered.

In your Meta App’s WhatsApp settings:

  1. Navigate to Configuration > Webhook
  2. Set the Callback URL to the URL shown on the account form
  3. Set the Verify Token to the same value you entered in the WhatsApp account form
  4. Subscribe to the messages webhook field

DID Mapping

WhatsApp phone numbers can be mapped to DIDs for unified routing. This mapping is managed from the DID form — when editing a DID that belongs to a tenant with WhatsApp enabled, a WhatsApp Phone dropdown appears allowing you to associate a WhatsApp number with that DID.

The 24-hour messaging window

WhatsApp only lets a business send freeform messages within 24 hours of the customer’s last message. To start a conversation, or to reply after the window closes, you must send a pre-approved template. This is why template management and variable mappings matter: they are the only way to reliably re-engage a contact. Agents replying inside the window can send normal text.

Worked example: connect a WABA and send your first template

Goal: connect your Meta WhatsApp Business Account, get the number routable, and map a template so a personalized message fills itself in at send time.

  1. Gather Meta credentials. In Meta Business Manager, note the WABA ID, generate a permanent System User Access Token (with whatsapp_business_messaging and whatsapp_business_management), and copy the App Secret. Pick any secure random string as your Verify Token.
  2. Create the account. Click Add, enter a Name (“Support WhatsApp”), paste the WABA ID, Access Token, App Secret, and Verify Token, set Status Active, and Save. Run Test Connection to confirm the credentials are valid.
  3. Wire up the webhook. In your Meta App under Configuration > Webhook, set the Callback URL to the URL shown on the account form (it looks like https://pbx.example.com/sms/whatsapp/WABA_ID), enter the same Verify Token, and subscribe to the messages field. Inbound messages now reach the platform.
  4. Sync numbers and templates. Click Sync Phones to pull your WABA’s numbers (check the Quality Rating is GREEN), then Sync Templates to pull approved templates from Meta.
  5. Map template variables. On a template like appointment_reminder, the mapping status shows “0/2 mapped”. Click the pencil, then map {{1}} -> Contact Field first_name and {{2}} -> Contact Field … (or a Custom Field), giving each a Default Value. Save. Now the values fill automatically at send time - agents don’t retype them.
  6. Map the number to a DID and expose it. On the DID form, map the WhatsApp number to a DID, then create a Messaging Channel so agents can send, and an Inbound Messaging Route so replies land in the right queue.

Remember the 24-hour window: to start a conversation (or reply after 24 hours) you must use an approved template - which is exactly why steps 4-5 matter.

Best practices

  • Use a permanent System User token, not a temporary user token. Temporary tokens expire and will silently break sending; a permanent System User token keeps the connection stable.
  • Run Test Connection after any credential change. It confirms the WABA ID, access token, and app secret are valid before agents rely on the account.
  • Re-sync templates after editing them in Meta. Approved templates and their components only appear here after a sync; changes made in Meta Business Manager are not reflected until you click Sync Templates.
  • Map template variables before assigning the template. Pre-mapping {{1}}, {{2}} to CRM fields means values fill automatically at send time and agents don’t retype them.
  • Protect your quality rating. Only initiate template conversations with opted-in contacts; unwanted messages lead to blocks that lower quality and reduce your messaging limit.