Connect your WhatsApp number

Before you start

You need:

• Admin access to your company's business portfolio at Meta (in Meta Business Suite), or the right to create one.
• A phone number your company owns that can receive an SMS or a voice call, and that is not in use on WhatsApp or the WhatsApp Business app. Meta does not accept a number that is still active on WhatsApp — delete it from WhatsApp first.
• For step 6 only, someone who can run one command (your developer, or walpio on a call with you). The command is written out in full below.

At the end you will have five values for walpio — three IDs and two secrets:

Meta has started calling the WhatsApp Business Account the Messaging account (it holds your templates, billing and webhooks). The ID is the same, and Meta says existing IDs and tokens keep working.

1. A business portfolio, verified

Your company's business portfolio (formerly Business Manager) owns the app, the WhatsApp account and the number. If your company already has one at business.facebook.com, use it.

Then verify the business — Meta's Help Centre page on business verification (linked at the bottom) lists what Meta asks for. You can connect a number before verification finishes, but it matters: a new portfolio can reach 250 customers in a moving 24 hours outside the customer-service window, and verifying the business is one of Meta's ways to raise that to 2,000. Replies to customers who wrote to you in the last 24 hours do not count toward the limit. Meta's review can take days, so start it first.

2. A Meta app with WhatsApp

walpio sends with an app that you own at Meta, so the WhatsApp account and its history stay yours.

1. Go to developers.facebook.com/apps and click Create App.
2. Enter the app's name (for example “Acme WhatsApp”) and your e-mail.
3. Choose the use case Connect with customers through WhatsApp, then Next.
4. Choose your business portfolio from step 1 and finish.
5. In the app, open WhatsApp → API Setup. It shows your WhatsApp Business Account ID. Note it.

API Setup also offers a test number and a Generate access token button. That token is temporary and expires quickly — do not send it to walpio. Step 4 makes the right one.

3. Your number and its display name

1. On WhatsApp → API Setup, add your phone number (you can also add it in WhatsApp Manager).
2. Enter the display name — the business name customers see. Meta reviews it against its display-name guidelines.
3. Choose SMS or voice call, and enter the code Meta sends to the number.
4. Note the number's Phone number ID, shown on API Setup. It is a long ID, not the phone number itself.

To change the display name later: WhatsApp Manager → Account tools → Phone numbers → your number → Profile → Display name → Edit. Meta allows 10 changes in 30 days. Once the number is connected, walpio shows the name's review status with each number.

4. A system user and a token that never expires

walpio sends as your business with a system-user token. A system user belongs to the business, not to a person, so the token keeps working when staff change.

1. Open Business settings → System users → Add. Give it a name such as “walpio”.
2. Assign it two assets: your app from step 2, with the permission to manage the app, and your WhatsApp account from step 2, with full control.
3. Click Generate token, choose the app, and set the expiry to Never.
4. Tick the permissions whatsapp_business_messaging and whatsapp_business_management (Meta's token page also lists business_management; tick it too).
5. Copy the token and keep it with your other secrets. Anyone who has it can send messages as your business.

Meta says some businesses must use tokens that expire after 60 days. walpio refuses a token that expires within 7 days, and it accepts a 60-day token — but it does not yet remind you before one expires, so if Meta makes you use one, put the renewal in your calendar and send us the new token in good time.

5. UAE local storage (optional — decide before step 6)

Meta can keep the content of your WhatsApp messages (text and media) at rest only in data centres in the United Arab Emirates (region AE). Bahrain (BH) is also offered; Saudi Arabia is not. Meta lets you switch local storage on or off only while the number is not registered — changing it later means deregistering the number and registering it again (Meta says that usually takes less than five minutes, and the number cannot send in between).

To switch it on, run this before step 6, with the token from step 4:

curl -X POST "https://graph.facebook.com/v25.0/<PHONE_NUMBER_ID>/settings" \
  -H "Authorization: Bearer <SYSTEM_USER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "storage_configuration": {
          "status": "IN_COUNTRY_STORAGE_ENABLED",
          "data_localization_region": "AE" } }'

This covers the copy Meta keeps. walpio keeps its own records — each message's status, the customer's number and a short preview — and this setting does not change where those are kept.

6. Register the number on the Cloud API

A verified number still has to be registered on the Cloud API before it can send. Meta allows this only through its API — not in WhatsApp Manager or the App Dashboard — so it is one command. Put in the Phone number ID (step 3), the token (step 4) and a six-digit PIN:

curl -X POST "https://graph.facebook.com/v25.0/<PHONE_NUMBER_ID>/register" \
  -H "Authorization: Bearer <SYSTEM_USER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "pin": "<SIX_DIGIT_PIN>" }'

Meta answers { "success": true }.

• The PIN is the number's two-step verification PIN. If the number has none yet, the six digits you choose here become it; if it already has one, use that PIN. Keep it with your other secrets — walpio does not need it.
• Meta accepts 10 register requests per number in a moving 72 hours (after that, error 133016), so check the IDs and the PIN before you try again.
• If walpio's check later says “the number is registered for NOT_APPLICABLE, not the Cloud API”, Meta does not report the number as a Cloud API number — most often because this step has not been done yet. Register it, then ask us to connect it again.

7. A payment method on the WhatsApp account — required from 1 October 2026

Meta bills its messaging charges directly to your own Meta account; walpio's plan does not include them. From 1 October 2026 Meta also charges for service messages — the free-form replies you send within 24 hours of a customer's message — after a free tier of 1,000 delivered per number per month, and utility templates sent inside that window are charged too.

Without a payment method, Meta delivers service messages only within the free tier and stops delivering them after it (Meta's pricing pages, as read on 25 September 2026). Add a card before 30 September 2026 by following Meta's Help Centre article “Add a credit card to your Messaging account on WhatsApp” (linked at the bottom).

8. The app ID and the app secret

In the app's dashboard open App settings → Basic. The App ID is at the top; the App secret is next to it behind Show (Meta asks for your password). walpio uses the app secret to check that every webhook really comes from Meta.

9. Send the details to walpio

Today a walpio operator connects your number for you. Send the five values from the table at the top to your walpio contact over a secure channel you agree on — for example a password manager's secure share or a one-time secret link — and never in a plain e-mail or chat message: the token and the app secret can send messages as your business. If you can, send the IDs and the two secrets separately.

What walpio does next

When the operator connects the number, walpio:

1. Checks everything with Meta before storing anything. The app ID and app secret belong together and to the token's app; the token is valid, carries both WhatsApp permissions for this WhatsApp account and does not expire within 7 days; the token can read the number; the number belongs to the WhatsApp account and is registered on the Cloud API. If anything fails, nothing is stored and every problem is listed in plain words (see below).
2. Points your app's WhatsApp webhooks at walpio (https://api.walpio.com/webhook). If your app already sends its WhatsApp webhooks somewhere else, walpio leaves that address in place and takes only this WhatsApp account's messages and delivery reports, through Meta's per-account override; template approvals are then read from Meta on a schedule. Either way, the other address stops receiving this number's messages and delivery reports — walpio sends them on to your own callback URL, signed, in walpio's format (see Callbacks).
3. Subscribes the WhatsApp account to your app's webhooks.
4. Reads the number's display name, quality rating, messaging limit and name review, and copies your message templates.
5. Checks the number again every day, and flags it on your dashboard if something breaks.

You then get a login to the dashboard and an API key, and the API reference shows how to send a first message.

If the check finds a problem

walpio lists each problem it finds. What they mean:

Questions? Email [email protected].