> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dmly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect WhatsApp

> Connect a WhatsApp Business number to DMLY, register it with Meta, and work within the 24-hour window.

WhatsApp is the channel DMLY is built around. Once a number is connected you get it in the
Inbox, in Broadcasts, in Automation, in appointment and invoice notifications, and on voice
calls. Getting there means going through Meta, and Meta sets rules that shape everything you
do afterwards.

Read the next two sections before you start. They are the two things people are most often
surprised by.

## The 24-hour window governs everything

You can only send a **free-form** WhatsApp message to a contact within 24 hours of *their*
last message to you. Outside that window, Meta delivers **approved templates only** — nothing
else. This is Meta's rule, not DMLY's, and there is no way around it.

Three consequences worth internalising:

* **A contact who has never messaged you has no open window.** A brand-new lead you imported
  from a spreadsheet can only be reached with an approved template. Not a "quick hello".
* **WhatsApp gets no extension.** Facebook Messenger and Instagram give you a longer period
  when a human replies. WhatsApp does not — 24 hours is 24 hours.
* **The window is per contact and resets on every inbound message.** Every reply they send
  restarts the clock.

DMLY enforces this before anything leaves the building. A free-form send to a contact whose
window has closed is stopped and recorded as failed rather than pretended into a "Sent". The
Inbox shows a countdown and a **WhatsApp 24-hour customer-care window** hint, and offers you
the template route when the window is shut.

<Note>
  The practical rule: **templates start conversations, free-form continues them.** Broadcasts,
  reminders, invoices and receipts to cold contacts all need an approved template. Read
  [Message templates](/broadcasts/message-templates) and
  [WhatsApp rules and limits](/broadcasts/whatsapp-rules-and-limits).
</Note>

## Connecting is not instant

Connecting a number is a Meta process, not a DMLY form. Expect to:

* have a phone number that meets Meta's criteria (below),
* have access to your Business Manager,
* have business documents ready if your business is not already verified with Meta,
* **register** the number with a 6-digit PIN before it can send or receive anything,
* wait for Meta to approve each message template before you can use it.

Templates are submitted for review and come back **Approved** or **Rejected** on Meta's
schedule. Plan your first broadcast around that, not around the day you connect.

## Before you connect

<Columns cols={2}>
  <Card title="Phone Number" icon="phone">
    A phone number without a WhatsApp account, or with an existing WhatsApp Business Account.
    It must be owned by you, have a country code, and be able to receive a one-time code by
    voice call or SMS.
  </Card>

  <Card title="Business Manager Access" icon="building">
    Make sure you can access Business Manager for your company. If you can see the business,
    you have access to configure.
  </Card>

  <Card title="Business Documents" icon="file-lines">
    Have your accepted business documents ready if your business is not already verified with
    Meta.
  </Card>

  <Card title="A plan that includes WhatsApp" icon="unlock">
    If your plan doesn't include the WhatsApp channel, connecting is blocked and you're asked
    to upgrade.
  </Card>
</Columns>

Meta's own limits, shown verbatim during signup, are worth reading twice:

* To onboard via Cloud API you can either delete an existing WhatsApp account or use an
  eligible WhatsApp Business Account.
* Not all WhatsApp Business Accounts qualify for embedded signup — only accounts with
  significant message history and growth potential can onboard.
* Some features may not be available for WhatsApp Business Accounts due to Meta's limitations.

You can still use the number for regular calls and messages after registration.

<Warning>
  If you are migrating the number from another provider, disable two-factor authentication in
  your WhatsApp Business Manager first. Migrations fail with 2FA still on.
</Warning>

## Connect your number

The recommended path is Meta's Embedded Signup — the page describes it as **Configure
WhatsApp via Embedded Signup — Simple (10 mins)**.

<Steps>
  <Step title="Open the channel picker">
    Go to **Integrations → Channels** and select **Add account**.
  </Step>

  <Step title="Choose WhatsApp">
    Select the **WhatsApp** tile (**Connect a business number**). It opens **WhatsApp Cloud
    API Configuration**.
  </Step>

  <Step title="Start signup">
    Select **Connect a WhatsApp number**. A requirements page appears — read it, then select
    **Connect a WhatsApp number** again.
  </Step>

  <Step title="Finish at Meta">
    You're taken to Facebook to sign in, pick or create the WhatsApp Business Account, add the
    phone number and verify it with the code Meta sends. Complete every step — stopping
    halfway returns you with no account granted.
  </Step>

  <Step title="Land back in DMLY">
    DMLY reads the granted WhatsApp Business Account and its phone number, subscribes your
    number to inbound messages, creates the Channel, and submits the built-in DMLY message
    templates to Meta for review.
  </Step>
</Steps>

If something breaks on the way back, the message tells you which step failed — the
authorisation code couldn't be exchanged, no WhatsApp Business Account was granted, or the
account has no phone number yet. In each case, retry signup and complete every screen.

<Accordion title="Bring your own WhatsApp Cloud API keys (advanced)">
  The second option on the same page — **Bring your own WhatsApp Cloud API keys — Complex (30
  mins)** — is for businesses that already run their own Meta developer app. Select
  **Configure** and supply:

  * **API Token** — a system-user generated permanent API token
  * **WhatsApp Phone Number ID** — from your Meta Developer App › WhatsApp › Getting Started
  * **WhatsApp Business Account ID**

  DMLY checks the API Token and Phone Number ID against Meta before saving; the WhatsApp
  Business Account ID isn't validated. You then paste the **Callback URL** and
  **Verify Token** shown on the page into Meta Developer App › WhatsApp › Configuration —
  exactly as shown, with no trailing slash — and subscribe the `messages` field.

  If Meta rejects the inbound subscription, the number still connects but messages won't
  arrive: the token needs the `whatsapp_business_management` permission and the number must be
  registered, not pending.
</Accordion>

## Register the number

**Connected is not the same as registered.** A number that isn't registered for Cloud API
can't send or receive anything, even though it shows up in DMLY.

Open **Bot Setup → WhatsApp → Configuration**. If the number shows **Not registered**, enter
the 6-digit two-step verification PIN for that number to register it for Cloud API messaging.
If Meta refuses, the reason appears on the PIN field — DMLY won't claim success it didn't get.

## Check the number's health

The **Configuration** tab reads live from Meta every time you open it:

* **Quality rating** — Meta's view of how recipients react to your messages. Let it slide and
  your limits drop.
* **Messaging limit tier** — how many customers you can start conversations with per day:
  **50 customers / 24h**, **250 customers / 24h**, **1,000 customers / 24h**, **10,000
  customers / 24h**, **100,000 customers / 24h**, or **Unlimited**. Meta raises this on its
  own as you send well-received messages; nothing in DMLY changes it. See
  [WhatsApp limits](/channels/whatsapp-limits).
* **Registration and verification state** — including whether the display name has been
  reviewed.

## What you get

<Columns cols={2}>
  <Card title="Unified Inbox" icon="inbox" href="/inbox/overview">
    Every inbound WhatsApp message threads onto its Contact, with assignment, statuses and
    quick replies.
  </Card>

  <Card title="Broadcasts" icon="bullhorn" href="/broadcasts/overview">
    One-to-many campaigns — using approved templates for anyone outside the 24-hour window.
  </Card>

  <Card title="Templates" icon="file-lines" href="/broadcasts/message-templates">
    Sync approved templates from Meta and build new ones to submit for review.
  </Card>

  <Card title="Automation" icon="diagram-project" href="/automation/flow-builder">
    Flows with buttons, lists, link buttons, location requests, phone requests, catalogues and
    WhatsApp Flows.
  </Card>

  <Card title="Voice calling" icon="phone-volume" href="/inbox/whatsapp-calling">
    Customers call your number on WhatsApp, and you call them back from the Inbox.
  </Card>

  <Card title="Profile and Commerce" icon="store">
    Your business profile and catalogue settings, on their own tabs under **Bot Setup →
    WhatsApp**.
  </Card>
</Columns>

The **Bot Setup → WhatsApp** page (**WhatsApp Cloud API Configuration**) holds all of it:
**Configuration**, **Profile**, **Commerce**, **Conversational Components** and **Calling**.

<Accordion title="Voice calling in short">
  On the **Calling** tab, **Enable voice calling** turns WhatsApp Business calling on for the
  number. **Auto-grant call-back permission** lets you call a customer back for 7 days after
  they call you, without a separate permission request. **Call button in WhatsApp** controls
  whether the call icon shows in the customer's chat with you.

  Inbound calls are free and global. Outbound calls are billed per minute, need the contact's
  permission, and are unavailable to recipients in some countries (including the US, Canada
  and Nigeria). Full detail: [WhatsApp calling](/inbox/whatsapp-calling).
</Accordion>

## Templates: the ones you get and the ones you build

Open the WhatsApp **Templates** page. It has two tabs.

**System** holds 13 templates DMLY ships and maintains — marked **Managed by DMLY**. They
cover appointment confirmations, updates and reminders, staff alerts, new conversations,
invoices, payment receipts, failed payments, renewal reminders, phone-number requests, review
requests and CSAT. They're all in Meta's `utility` category, which is what makes them
deliverable outside the 24-hour window once approved. They're created as drafts and submitted
to Meta automatically when you connect a live number.

**My Templates** is where you add your own with **Add template**. Two things to know:

* The template name is what Meta references: lowercase letters, numbers and underscores only.
* Media templates are reviewed against a sample you upload — JPG/PNG up to 5MB, MP4 up to
  16MB, PDF up to 100MB.

Every template moves through **Draft** → **Pending** → **Approved** or **Rejected**. Only
**Approved** templates can be sent; anything else fails at send time. Use **Refresh templates**
to pull the current status from Meta — the page shows when it was last synced.

<Warning>
  If a notification has no approved template and the contact's window is closed, DMLY sends
  nothing at all. That's deliberate — better a gap you can see in the logs than a customer who
  never got their appointment reminder while the app claimed it was sent. If reminders or
  receipts aren't arriving, check your `dmly_` templates are **Approved** first.
</Warning>

## Opening the window on purpose

Since a closed window is the default for anyone new, the useful move is to get them to message
you first:

* **Click-to-WhatsApp links and QR codes** from [Growth tools](/growth/overview) open a chat
  with a prefilled code. The flow starts when the contact sends that first message — which is
  also the moment your 24-hour window opens.
* **The Inbox and Contact pages** offer **Message on WhatsApp** wherever a reachable contact
  appears.
* **Store triggers** (Shopify, WooCommerce) almost always fire outside the window. Start those
  flows with an approved template.

## When things go wrong

<Accordion title="Connected, but nothing arrives in the Inbox">
  Two things must be true: your WhatsApp Business Account must be subscribed to the app, and
  the number must be **Registered**. Check the **Configuration** tab first.

  If both look right and messages still don't arrive, the remaining suspect is the webhook
  configuration in the Meta App Dashboard — the callback URL and the `messages` field. DMLY
  can't read or set that from here, so it has to be checked at Meta. Full walkthrough:
  [No inbound messages](/channels/no-inbound-messages).
</Accordion>

<Accordion title="The channel shows Unauthorized">
  This means the access token stopped working — **Access token has expired. Reconnect your
  account.** DMLY emails the workspace admin (subject: **We've Lost Connection - Action
  Required**) once per disconnect. While it's unauthorized, the profile, commerce,
  conversational and calling settings all go blank and nothing sends. Reconnect the number to
  fix it.
</Accordion>

<Accordion title="It says Connected but messages silently fail">
  DMLY marks a number **Unauthorized** when Meta returns an authentication error. Other kinds
  of Meta rejection — a policy block, a quality restriction, a disabled account — don't look
  like authentication errors, so the channel can keep showing **Connected** while sends fail.

  If sends are failing and the badge looks fine, check the number's status directly in your
  Meta Business Manager, then see
  [Account disabled](/channels/account-disabled) and
  [Logs](/troubleshooting/logs).
</Accordion>

<Accordion title="Nothing sends to one particular contact">
  Two likely causes, in this order: the contact has opted out (nothing is sent to an opted-out
  contact, ever), or their 24-hour window is closed and the message isn't a template.
</Accordion>

<Accordion title="You reconnected and now something points at the wrong number">
  Reconnecting to a different WhatsApp Business Account leaves the old connection behind
  alongside the new one. The newest is the one DMLY manages. If the number shown looks stale,
  disconnect the old one — see
  [Delete a WhatsApp number](/channels/delete-whatsapp-number).
</Accordion>

<Warning>
  Disconnecting removes the number and its Channel from your Workspace immediately, with no
  undo. Read [Delete a WhatsApp number](/channels/delete-whatsapp-number)
  before you do it.
</Warning>

## Next

<Columns cols={2}>
  <Card title="WhatsApp rules and limits" icon="triangle-exclamation" href="/broadcasts/whatsapp-rules-and-limits">
    What you can send, to whom, and how often.
  </Card>

  <Card title="Message templates" icon="file-lines" href="/broadcasts/message-templates">
    Build a template Meta will approve.
  </Card>

  <Card title="Set up your bot" icon="robot" href="/automation/bot-setup">
    Put a flow behind the number.
  </Card>

  <Card title="All channels" icon="plug" href="/channels/overview">
    Messenger, Instagram, Telegram, LiveChat and Google Business Profile.
  </Card>
</Columns>