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

# WhatsApp

> Connect a WhatsApp Business number to Callivox — quick connect with Meta or your own Meta app — and manage message templates.

WhatsApp is the busiest channel for most Callivox workspaces. Once connected, every message sent to your WhatsApp Business number arrives in the inbox, and your team and AI agents reply from there.

There are two ways to connect. **Quick connect with Meta** handles everything in one popup and is the right choice for almost everyone. The advanced route uses your own Meta developer app and is for teams who already run one.

<Frame caption="The WhatsApp connect dialog, with quick connect at the top and the advanced route behind a disclosure.">
  <img src="https://mintcdn.com/haconsultancy/8jQZZfLAZM_xjJe7/images/channels/whatsapp-connect.png?fit=max&auto=format&n=8jQZZfLAZM_xjJe7&q=85&s=ff32137ed9712191b3fe8c8b21999435" alt="The Connect channel dialog with WhatsApp selected, showing the Connect with Meta button" width="2880" height="1800" data-path="images/channels/whatsapp-connect.png" />
</Frame>

## Before you start

You need:

* A verified Meta Business Portfolio.
* A phone number that can receive an SMS or a call for verification.
* Admin access to that business in Meta's tools.

<Warning>
  If you are moving a number fully onto Callivox, it must **not** already be registered on the WhatsApp consumer app or the WhatsApp Business app. If the number is in use on the WhatsApp Business app and you want to keep using it there, choose the coexistence option described below instead.
</Warning>

## Connecting

<Tabs>
  <Tab title="Quick connect with Meta">
    This is the fastest route and the one to use unless you have a reason not to. Callivox handles the webhook wiring for you, so there is no callback URL or verify token to copy anywhere.

    <Note>
      Quick connect appears in the dialog only when it is enabled for your workspace. If you do not see the **⚡ Connect with Meta** button, use the advanced route below, or contact support. Trying to use it when it is switched off returns "WhatsApp quick connect is not enabled for this workspace."
    </Note>

    ### Choose how to connect

    If your workspace supports it, the dialog first asks **How to connect WhatsApp** and offers two options.

    <AccordionGroup>
      <Accordion title="Keep using the WhatsApp Business app (recommended if the number is already live)">
        "Connect a number you still use on your phone. Your recent chats come across, and Callivox's AI works alongside you — it steps back whenever you reply from the app."

        Pick this when the number is already in daily use on the WhatsApp Business app and you do not want to give that up. You scan a QR code with the number you already use — there is no migration, and the app keeps working exactly as before.

        Your recent chat history is imported once, so the inbox is not empty on day one. From then on, both routes stay in sync: Callivox's AI answers when nobody is handling the chat, and steps back the moment somebody replies from the phone.
      </Accordion>

      <Accordion title="Move my number to Callivox">
        "Your number moves fully onto Callivox. You'll stop using the WhatsApp Business app for this number."

        Pick this for a number that will be handled entirely by your team in Callivox. After the move, the WhatsApp Business app no longer receives messages for that number.
      </Accordion>
    </AccordionGroup>

    ### Run the connection

    <Steps>
      <Step title="Open the dialog">
        Go to **Settings → Channels**, click **+ Connect channel** and pick **WhatsApp**. Give the channel a **Display name**.
      </Step>

      <Step title="Click Connect with Meta">
        The button reads **⚡ Connect with Meta**. A Meta popup opens: "Log in with Facebook, pick your WhatsApp Business Account and verify your business phone number — all in one popup. Takes about 2 minutes."
      </Step>

      <Step title="Complete Meta's steps">
        Log in with the Facebook account that administers your business, choose the WhatsApp Business Account, and either verify the phone number or scan the QR code, depending on the mode you picked.
      </Step>

      <Step title="Wait for Callivox to finish">
        Back in the dialog the progress reads **Waiting for Meta…**, then **Linking your WhatsApp number…**, then **Connected!** You will see the toast "WhatsApp connected" and the channel appears in your list as **Active**.
      </Step>
    </Steps>

    ### If it does not work

    | What you see                                                         | What it means                                                                     |
    | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
    | "WhatsApp quick connect is not enabled for this workspace."          | Quick connect is switched off for you. Use the advanced route or contact support. |
    | "This WhatsApp number is already connected to a Callivox workspace." | The number is in use on another workspace. Disconnect it there first.             |
    | The number is not offered in the popup                               | The number is not part of the WhatsApp Business Account you selected.             |

    Reconnecting the same number on the same workspace updates the existing channel rather than creating a duplicate.
  </Tab>

  <Tab title="Advanced: use your own Meta app">
    Use this route if your business already runs its own Meta developer app and you want WhatsApp to go through it. It takes about 15 minutes and involves copying four values out of Meta's console and two values back into it.

    Open the disclosure **▸ Advanced: use my own Meta app** in the connect dialog. Before you start, open the built-in setup guide — it shows exactly where each value comes from.

    ### Prerequisites

    * A verified Meta Business Portfolio.
    * A phone number that is **not** registered on the WhatsApp consumer app or the WhatsApp Business app.
    * Admin access to `developers.facebook.com`.

    ### Step 1 — collect the four values

    <Steps>
      <Step title="Create a Business app and add the WhatsApp product">
        In Meta's developer console, create an app of type **Business** and add the **WhatsApp** product to it.
      </Step>

      <Step title="Copy the Phone number ID and WABA ID">
        The WhatsApp **API Setup** screen shows both. **Phone number ID** looks like `1234567890`; **WABA ID** is the business account ID.
      </Step>

      <Step title="Create a permanent access token">
        Create a **System User** in Meta Business settings, give it access to your app and WhatsApp Business Account, and generate a token. It starts with `EAA`.

        <Warning>
          Do not use the temporary token shown on the API Setup screen — it expires after 24 hours and your channel will stop working the next day.
        </Warning>
      </Step>

      <Step title="Copy the App Secret">
        In the app, go to **App settings → Basic** and reveal the **App Secret**.
      </Step>
    </Steps>

    ### Step 2 — fill in the Callivox fields

    | Field               | What to paste                                       |
    | ------------------- | --------------------------------------------------- |
    | **Display name**    | How the channel appears in your inbox and settings. |
    | **Phone number ID** | From WhatsApp → API Setup.                          |
    | **WABA ID**         | Your WhatsApp Business Account ID.                  |
    | **Access token**    | The permanent System User token.                    |
    | **App secret**      | From App settings → Basic.                          |

    All four are required — leaving one out returns "All fields are required."

    Click **Connect**.

    ### Step 3 — wire up the webhook

    After connecting, Callivox shows an **Almost done!** panel: "Add these to your Meta App → Webhooks (callback URL + verify token), then save."

    <Steps>
      <Step title="Copy the callback URL and verify token">
        Both are on the panel, each with a **Copy** button.
      </Step>

      <Step title="Paste them into Meta">
        In your Meta app, go to **WhatsApp → Configuration → Webhook**, click Edit, paste the callback URL and the verify token, and save.
      </Step>

      <Step title="Subscribe to the messages field">
        On the same screen, subscribe to the `messages` webhook field. Without it, nothing reaches your inbox.
      </Step>

      <Step title="Check the permissions">
        Your app needs the `whatsapp_business_messaging` and `whatsapp_business_management` permissions. The **Required Meta permissions** panel in the dialog lists them.
      </Step>

      <Step title="Test it">
        Click **Done**, then send a message to your WhatsApp number from another phone. It should appear in the inbox within seconds.
      </Step>
    </Steps>

    <Tip>
      You can reopen the callback URL and verify token any time from the channel row — see [viewing webhook details](/channels/managing-channels).
    </Tip>
  </Tab>
</Tabs>

## WhatsApp templates

WhatsApp does not let businesses message people freely. You can reply in plain text for **24 hours** after a customer's last message. Outside that window — a follow-up two days later, a campaign to a list, an order update to somebody who has not written in — you must send a **template** that Meta has approved in advance.

Templates are managed per channel: on the channel row for your WhatsApp channel, click **Templates**.

The page title says it plainly: "Message templates must be approved by Meta before use in campaigns."

* **Refresh** pulls the current list and the current statuses straight from Meta. Use it after submitting something, or if a colleague created a template outside Callivox.
* **+ New template** opens the creation form.

If the list is empty you will see "No templates found. Create one above or refresh to sync from Meta."

### Creating a template

<Steps>
  <Step title="Name it">
    **Template name** takes lowercase letters, numbers and underscores only — `order_update`, not "Order Update". Anything else returns "Use lowercase letters, numbers and underscores only — no spaces or capitals." The name cannot be changed after creation.
  </Step>

  <Step title="Pick a language and category">
    Choose the **Language** the template is written in, then a **Category**:

    * **Utility** — transactional messages about something the customer already did: order confirmations, delivery updates, appointment reminders. This is the default and the safest choice.
    * **Marketing** — promotions, offers, re-engagement, anything selling.
    * **Authentication** — one-time passcodes and verification codes.

    Categorising a promotion as Utility is one of the most common reasons Meta rejects a template.
  </Step>

  <Step title="Add a header (optional)">
    **Header** can be **None**, **Text**, **Image**, **Video**, **Document** or **Location**. A text header is capped at 60 characters and may contain at most one variable.

    Media headers need a sample: "Meta needs one sample file to approve a media header." Sample files are capped at 16 MB. Location headers need no sample.
  </Step>

  <Step title="Write the body">
    The **Body text** is the message itself. Insert placeholders with **+ Insert variable**, which adds `{{1}}`, `{{2}}` and so on in order — for example `Hi {{1}}, your order {{2}} is ready.`

    The rules Meta enforces:

    * Variables must be numbered in sequence starting at `{{1}}`.
    * The body cannot start or end with a variable.
    * Two variables cannot sit next to each other — put words between them.
  </Step>

  <Step title="Fill in the variable samples">
    **Variable samples (required by Meta)** is where you show a realistic value for each placeholder. Meta reviews the template as a reader would see it, so give it a real-looking name and order number, not "xxx".
  </Step>

  <Step title="Add a footer (optional)">
    **Footer (optional)** is capped at 60 characters and cannot contain variables.
  </Step>

  <Step title="Submit">
    A "Before you can submit:" checklist lists anything still missing. When it is clear, click **Submit for approval**. You will see "Template submitted for approval".
  </Step>
</Steps>

### Approval statuses

| Badge        | Meaning                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------- |
| **Pending**  | With Meta for review. Reviews usually finish quickly, but can take longer for marketing templates. |
| **Approved** | Ready to send, including in [campaigns](/campaigns/overview).                                      |
| **Rejected** | Meta declined it. The row shows Meta's own reason.                                                 |

To fix a rejected template, click **Edit**, change what Meta objected to, and use **Save & resubmit**. The name stays fixed — everything else can change. **Edit** is unavailable for templates that have never reached Meta.

### Why Meta rejects templates

The reason is shown on the row, but the usual causes are:

* The category is wrong — a promotional message submitted as Utility.
* The variable samples are placeholders rather than realistic values.
* The message reads as unsolicited marketing to people who did not opt in.
* The wording is vague enough that a reviewer cannot tell what the message is for.

<Tip>
  Write the template as though the reviewer is the recipient: say who you are, why you are writing, and what the customer should do next.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Campaigns" icon="paper-plane" href="/campaigns/overview">
    Send approved templates to a list of contacts.
  </Card>

  <Card title="Managing channels" icon="sliders" href="/channels/managing-channels">
    Rename, reconnect and delete channels.
  </Card>
</CardGroup>