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

# WhatsApp assistant

> Let customers check their data and buy plans by messaging your business on WhatsApp.

Connect your own WhatsApp business number and your customers can check their balance, renew a plan and get a payment link without opening the WiFi portal. Useful when someone has run out of data and can no longer load the portal page.

Go to **Settings → Email & messaging → WhatsApp Cloud bot**.

<Note>
  Only the workspace **owner** can save these credentials. Managers and operators can see the section but not change it.
</Note>

## What your customers can do

Once connected, a customer messages your number and replies with a number:

| Reply | What they get                                       |
| ----- | --------------------------------------------------- |
| **1** | Their active plan — what it is, and when it expires |
| **2** | Data remaining on the current plan                  |
| **3** | The plans they can buy, and a payment link          |
| **4** | Their account and wallet balance                    |
| **5** | Your support contact details                        |

Plain words work too — *buy*, *renew*, *plans*, *data*, *balance*, *wallet*, *help*. Sending **menu** or **0** always returns to the main menu.

Paid plans come back as a checkout link. When the payment succeeds the plan activates on its own — the customer does not have to come back to the chat.

## What you need from Meta

This uses Meta's WhatsApp Cloud API, so you need a Meta app with WhatsApp added and a phone number registered to it. From the Meta App Dashboard, collect four values:

| Value                            | Where it comes from                                                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Phone number ID**              | WhatsApp → API Setup, next to your number. This is not the phone number itself.                                                                           |
| **WhatsApp Business Account ID** | WhatsApp → API Setup, shown as the WABA ID.                                                                                                               |
| **Permanent access token**       | A system user token from Meta Business Settings. Use a permanent one — a temporary test token expires in 24 hours and the bot goes quiet with no warning. |
| **Meta app secret**              | App Settings → Basic. Used to verify that incoming messages really came from Meta.                                                                        |

<Warning>
  The number you connect must not be attached to the WhatsApp Business **app** on a phone. Meta only allows a number to be used in one place — moving it to the Cloud API signs it out of the app.
</Warning>

## Connect it

<Steps>
  <Step title="Paste the four values">
    Fill in **Phone number ID**, **WhatsApp Business Account ID**, **Permanent access token** and **Meta app secret**.

    **Business phone (for display only)** is what your team sees in the dashboard. It does not affect routing.
  </Step>

  <Step title="Save">
    Click **Save Cloud API**. The callback URL and verify token appear underneath once saved.

    Saved secrets show as `••••••`. Leaving those fields blank keeps the existing value — you only retype a secret when you are replacing it.
  </Step>

  <Step title="Point Meta at your webhook">
    In the Meta App Dashboard, go to **WhatsApp → Configuration** and paste in the **Callback URL** and **Verify token** shown on the settings page.

    Then subscribe to the **messages** field. Without that subscription Meta accepts the webhook but never sends anything to it, and the bot stays silent.
  </Step>

  <Step title="Turn it on">
    Tick **Enable this tenant's purchase bot** and save again. The card header reads **Connected** once the number, token, app secret and the enabled tick are all in place.
  </Step>

  <Step title="Send a test message">
    Message your business number from a phone that is registered as one of your customers. You should get the menu back.
  </Step>
</Steps>

## Free-plan activation

If you offer a free plan, choose how the bot hands it out.

| Setting                                              | What happens                                                                                                                        |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **WiFi portal only — identify the current device**   | The bot refuses and tells the customer to activate it from the WiFi portal. Choose this when the free plan is meant for one device. |
| **Activate remotely — attach a device on reconnect** | The bot activates it straight away and the device attaches when they reconnect.                                                     |

A free plan is still once per person either way. Someone who has already claimed it is told so and offered the paid list instead — the bot is not a way around a limit the portal enforces.

## Who the bot will talk to

The bot answers people it can identify. A customer is matched by the phone number they message from, against the number on their account.

Anyone it cannot match gets:

> I couldn't find an account for this WhatsApp number. Please message us from the phone number used during registration.

Two things cause that on an account that does exist:

* **The number differs from the one they registered with.** A second SIM, or a number saved in a different format.
* **Two customers share one phone number.** The bot refuses rather than guess, because guessing would show one person another person's wallet.

Fix either from **Customers**, by correcting the phone number on the account.

## Prices follow the customer's site

If you run more than one site, the bot offers the plans sold at **that customer's site** — not every price list you have.

The portal knows the site because the guest is standing on its gateway. WhatsApp only has a phone number, so the site recorded on the customer's account stands in for it. A customer with no site recorded sees your business-wide plans.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens when I message the number">
    Check the **messages** subscription in Meta → WhatsApp → Configuration. An unsubscribed webhook is the most common cause: Meta verified the URL, so it looks correctly configured, but no message is ever delivered.

    Then confirm **Enable this tenant's purchase bot** is ticked and the header reads Connected.
  </Accordion>

  <Accordion title="It worked, then stopped after a day">
    You saved a temporary access token. Replace it with a permanent system user token from Meta Business Settings.
  </Accordion>

  <Accordion title="Customers get the 'couldn't find an account' reply">
    The number they messaged from does not match the number on their account, or two accounts share that number. Correct it on the customer's profile.
  </Accordion>

  <Accordion title="A customer sees the wrong prices">
    Plans follow the site recorded on their account. Check that field on the customer, and that the plan is on sale at that site.
  </Accordion>

  <Accordion title="The chat header shows a name that is not mine">
    Meta controls the WhatsApp chat header, not WifiPadi. It shows the business name on the Meta account that owns the number. Replies themselves use your workspace name.
  </Accordion>
</AccordionGroup>

<Note>
  The bot handles buying and account questions. It is not a support inbox — reply **5** gives the customer your support contact details so a person can take over.
</Note>