# Connect WhatsApp

## What you are connecting

Iris replies to customers who message your connected WhatsApp business number. You authorize the number through Meta’s own signup window, opened from **Connections** in your Flowlith dashboard. You do not need to build a webhook, obtain a developer token or send Flowlith your Meta password.

Three separate steps matter: **connect your number**, **launch Iris**, and **test a real conversation**. A Connected badge is not proof that a customer has received a reply.

## Before you begin

- Sign in to the Flowlith account that owns the business and select the correct workspace.
- Have access to the Meta business and WhatsApp account you intend to connect. If you cannot select them in Meta, ask the person who manages those assets to complete the connection.
- Have access to the business phone number and the verification method Meta offers. Finish phone ownership and display-name requirements inside Meta.
- If this number already has a two-step verification PIN, have that PIN available. Keep it private.
- Allow the Meta popup and keep the original dashboard tab open until setup finishes.
- Check the number’s current use before changing anything. A number already used in a WhatsApp app or another provider may need a different Meta setup or migration path.

**Do not delete an existing WhatsApp account or disconnect another provider just to experiment.** Confirm the migration or eligible Business app connection path with Meta and your current provider first. This guide does not promise that every existing number can move without interruption.

The WhatsApp number you supply as your **contact method during Flowlith signup** is for contacting you. Entering it does not connect a messaging channel. The channel connection happens separately in the dashboard.

## Connect the number

1. Open **Dashboard → Connections → Connect WhatsApp**.
2. Sign in inside the Meta popup using an account with access to the intended business assets.
3. Follow Meta’s steps to choose or create the business portfolio and WhatsApp Business Account offered to you.
4. Choose the exact business phone number customers should message. Complete any phone verification or business details Meta requests. Selecting only an account without a phone does not finish setup.
5. Review and grant the requested WhatsApp messaging and account-management access. Flowlith needs this to connect the selected number and receive and answer messages.
6. Finish the Meta window and return to Flowlith. Wait while the dashboard verifies the selection. If a choice is shown, select the intended account rather than accepting an unfamiliar one.
7. Complete **Finish WhatsApp setup** if Flowlith asks for it, as described below.
8. Wait for the dashboard to reload. Confirm the correct number is displayed as **Connected**, without an incomplete-setup warning.

Never paste Meta access tokens, authorization codes, verification codes or PINs into Iris chat, an LLM prompt, a support report or these documentation examples.

## The six-digit PIN step

For a new phone that is ready to activate, Flowlith may show **Finish WhatsApp setup**:

- Choose a six-digit **two-step verification PIN** for a new phone, or enter the existing PIN for that phone.
- Enter it only in the protected PIN field and select **Activate phone**.
- This is **not** the temporary SMS or voice-call code used to prove ownership of the number.
- Flowlith does not save this PIN. Keep it in your own password manager for future Meta recovery or registration.
- A number that is already ready may not need this step. The absence of a PIN prompt is not itself an error.

If activation is unconfirmed, keep the same PIN and reconnect to check the number’s status before trying another activation. Do not invent a new PIN to work around an uncertain result. If Meta reports that ownership or the display name is not ready, finish that step in WhatsApp Manager first.

Cancelling the PIN dialog does not complete activation and leaves your saved connection unchanged.

## Numbers already using the WhatsApp Business app

Where available, Meta may offer a Business app connection that lets an eligible number continue using the phone app. Availability depends on the number, Meta’s setup options and the connection flow available to your workspace. Do not assume that an ordinary personal WhatsApp account or a number with another provider is eligible.

If Meta offers this path, complete all of its Business app steps before returning to Flowlith. This path may not need Flowlith’s separate PIN dialog. If the option is missing or setup is incomplete, contact Flowlith instead of deleting the app account.

For a workspace with Business app coexistence enabled, when WhatsApp reports that you replied from the phone app, Iris pauses new automatic replies in **that customer’s WhatsApp chat for 30 minutes**. Other customer chats and channels are unaffected. A reply already in progress may still finish. This is not a promise of instantaneous handover, a complete shared inbox or an import of your old app history.

## Launch Iris separately

Return to **Home**. If your account is under review, wait for approval. Review **About business**, save your business details, then select **Launch Iris** when available. Memory is optional.

Connecting a number does not launch an inactive Iris. If Iris is already launched, a newly connected channel can start receiving customer messages. Make sure the business instructions are ready before adding a production number.

## Verify the whole conversation

Use a separate customer WhatsApp account to message the connected business number. Start with a harmless question that does not ask Iris to change data in another system. Normal reply credits apply.

```text
Customer: What are your opening hours?
[Check that the reply matches the hours saved in About business.]

Customer: And are you open on Saturday?
[Check that the follow-up stays in the same conversation.]
```

Your checks should distinguish these outcomes:

| Check | What it proves |
| --- | --- |
| Correct number shown as Connected | The number’s connection was confirmed during setup. |
| Iris launched on Home | Launch was confirmed; this is not a continuous uptime indicator. |
| Customer’s text receives an actual WhatsApp reply | This customer-to-Iris-to-WhatsApp path worked for that test. |
| Follow-up receives a relevant answer | Conversation continuity worked for that thread. |
| Voice note or photo receives a useful reply | That media path worked; a text test alone does not prove it. |

The dashboard customer preview is useful for reviewing Iris’s answers, but it does **not** send a WhatsApp message or prove delivery to a phone. Test any [Actions](https://docs.flowlith.com/actions) separately with permission: they can contact real external systems.

## Common setup problems

| What you see | What to do |
| --- | --- |
| Meta does not open | Allow popups, wait for Meta to load, and retry from Connections. Check browser blocking if it still fails. |
| Your business or number is missing | Check which Meta account is signed in and whether it has access. Finish selecting a number, not only the business account. |
| Phone ownership or name is not ready | Complete the outstanding step in WhatsApp Manager, then connect again. |
| PIN rejected or activation unconfirmed | Check the existing two-step PIN. Reconnect to check status before attempting activation again. |
| Setup incomplete | Follow the dashboard instruction to disconnect the incomplete saved connection, then reconnect. This is not an instruction to delete the WhatsApp account itself. |
| Number is linked to another Flowlith business | Confirm the intended workspace and contact Flowlith; do not create duplicate workspaces to bypass the conflict. |
| Connected but no reply | Check approval, saved business details, launch and credits. Send a fresh customer text. If using Business app coexistence, account for the temporary pause after your manual reply. |
| Account access saved but message setup unconfirmed | Do not treat it as ready. Reconnect as directed or report the issue. |

## Change or disconnect a number

Use **Connections → WhatsApp → Disconnect**, review the confirmation, then connect the replacement. Flowlith does not silently replace a saved account during another login.

Disconnecting removes the saved connection from Flowlith; it does not delete your WhatsApp account. Other connected channels, business details and conversations remain. A reply already in progress may finish. If you also need to remove permissions in Meta, review them in your Meta account separately.

## Share a safe support report

Use **Home → Report an issue**. Include the failing step, time and timezone, and the visible status with private details removed. The report form accepts text; describe what you see. Do not include PINs, tokens, verification codes or private customer conversations.

```text
Channel: WhatsApp
Step: Returned from Meta; number did not show Connected
Time and timezone: [when it happened]
Expected: [what you expected]
Observed: [visible message, with private details removed]
Checks already tried: [popup allowed / correct workspace / status rechecked]
```

Continue with [channels and media](https://docs.flowlith.com/channels), [how Iris works](https://docs.flowlith.com/how-iris-works), or [troubleshooting](https://docs.flowlith.com/troubleshooting).