Connect WhatsApp

What it is

WhatsApp connects through Meta's WhatsApp Business Cloud API, using credentials from your own Meta app. Agentency does not resell WhatsApp numbers — you bring the number and the app, and you stay the owner of both.

The card asks for three values:

• Access token — a permanent Cloud API token. Not the temporary one Meta shows in the API Setup screen.
• Phone number ID — the numeric identifier Meta assigns to your WhatsApp number, shown in WhatsApp → API Setup. It is a long run of digits, not the phone number itself, and the form will reject anything that is not digits.
• App secret — from App Settings → Basic. Agentency uses it to prove each incoming message really came from Meta.

WhatsApp finishes with a verification handshake. Pressing Connect leaves the channel at Pending verification with a callback URL and a verify token for you to paste into your Meta app. Until Meta calls that URL back successfully, messages arriving on the number are received and thrown away — the customer sees no reply at all.

When you would use it

Use this when WhatsApp is where your customers already are, and you can either administer the Meta app yourself or get the person who does into the same conversation.

Where to find it

Open Dashboard → Chatbots → your chatbot → Integrations → Messaging and click the WhatsApp card.

Before you start

Four gates must be green: a plan with integrations, messaging enabled for this deployment, an Active chatbot, and a free slot under the cap on the Connected channels card. See Messaging channels availability. A paused chatbot connects perfectly and then answers nobody — activate it first, then chase the channel.

Steps

1. In Meta for Developers, open your app (or create one) and add the WhatsApp product.
2. Create a permanent access token. In practice this means generating it from a System User rather than copying the temporary token on the API Setup screen; the temporary one expires within hours and takes your channel down with it.
3. In WhatsApp → API Setup, copy the Phone number ID for the number you want to use.
4. In App Settings → Basic, copy the App secret.
5. In Agentency, open Integrations → Messaging → WhatsApp and paste all three values. The drawer repeats these steps, shows a note about permanent tokens, and links to Meta's Cloud API guide under View official setup guide.
6. Press Connect. Agentency checks the token against your number with Meta before saving anything.
7. Copy the Callback URL and Verify token from the pending panel into WhatsApp → Configuration in your Meta app, and save.
8. Subscribe to the messages field in that same configuration screen. Without it, verification can pass while your number still sends nothing.
9. Watch the drawer flip to Connected by itself, then send a real WhatsApp message to the business number and confirm the reply.
10. Check the thread in Conversations.

What you will see

The connect form has four numbered steps, the official-guide link, an information note about permanent tokens, and three fields — the access token and app secret masked, the phone number ID in plain text.

After connecting, the pending panel shows the callback URL, the verify token, copy buttons, a spinner reading Waiting for the webhook to be verified, and a plain statement that messages are received and ignored until verification finishes.

Once verified, the badge reads Connected and the panel shows Connected as followed by the business phone number Meta reports, plus lifetime message and user counts. Test connection only appears after the channel is connected, so during the pending stage the footer offers Disconnect only.

The public link on the Direct link card keeps working the whole time, so you always have a way to serve people while you fight with Meta.

How replies behave

WhatsApp allows generous message lengths, so most answers arrive in one piece; very long ones are split. Incoming text is trimmed after about 2,000 characters. Voice notes, images, documents, and location pins get a short reply saying the chatbot reads text only.

Each answer spends message credits at your chatbot's live model rate (1X = one credit; see Message credits), exactly like the website widget. Meta's own conversation pricing is billed to you by Meta and is not visible here. If your workspace runs out of credits, customers get a short out-of-credits message instead of an answer — see Out of credits.

Limits and plan notes

WhatsApp takes one of your connected-app slots for this chatbot. Reconnecting replaces the credentials without using a second slot.

All three values are stored encrypted and never shown again. There is no edit form: to change a value, reconnect with the full set.

Disconnecting stops replies immediately and clears the stored credentials, but Meta keeps the webhook configuration in your app — remove it yourself if you are done, or the number will keep posting to an address that no longer answers.

The website widget's allowed-domains list has nothing to do with WhatsApp; that setting only governs the browser widget (Widget allowed domains).

Common problems

Status stays at Pending verification.

Meta has not called back, or it called with a token that does not match. A new verify token is generated every time you connect, so copy both values from the drawer again rather than reusing an older note, and save the configuration in Meta again. The drawer stops watching after about five minutes; reload the page to pick up a late change.

Verified and Connected, but nobody gets answers.

The number is very likely not subscribed to the messages field in WhatsApp → Configuration. After that, check that the chatbot is Active.

Connect fails with a credential error.

Usually the phone number ID and the access token do not belong together, or the token has already expired. Re-copy both from WhatsApp → API Setup and try again.

It worked for a day and then went quiet.

A temporary token expired. Generate a permanent one and press Reconnect. This is the single most common WhatsApp failure.

Connect is disabled entirely.

Either the messaging grid is unavailable on this deployment, your plan does not include integrations, or you have hit the connected-app cap. Messaging channels availability explains which one you are looking at.

Can I use a number that is already on the WhatsApp phone app?

No. A number used with the Cloud API cannot also be in use in the consumer WhatsApp or WhatsApp Business app. Move to a dedicated number.