Connect WhatsApp with your own Meta app

Before you start#

This guide connects a WhatsApp number to Officely through your own Meta app on the WhatsApp Business API (Meta Cloud API). You copy a few IDs and a token from Meta into Officely, and point your app's webhook at Officely.

You need:

• A Meta Business account (business.facebook.com) where you're an admin.
• A Meta app with the WhatsApp product, in that business. You create it in step 1 if you don't have one.
• A phone number added to your WhatsApp Business account, and not in use on the WhatsApp app on a phone.
• Your Officely account, as its owner or an admin.
• About 20 minutes.

Here's the whole path:

1. Create or choose your Meta app#

1. 1

   Open Meta for Developers

   Go to developers.facebook.com/apps and sign in with the Facebook account that's an admin of your Meta Business account.

2. 2

   Pick an app, or create one

   If you already have an app with WhatsApp, click it and skip to step 2. Otherwise click Create app.

3. 3

   Choose the WhatsApp use case

   When Meta asks what the app is for, choose the option to connect with customers through WhatsApp. Give the app a name (for example Officely WhatsApp) and a contact email.

4. 4

   Connect it to your business

   Choose your Meta Business account (business portfolio) when asked. The app must belong to the same business as your WhatsApp account.

5. 5

   Finish creating it

   Click through to create the app. You land on the app's dashboard, with WhatsApp in the left menu.

2. Create a permanent token#

Officely sends every message with the access token you paste in. Use a permanent System User token. The temporary token on the app's API Setup page expires after about 24 hours: the bot answers for a day, then stops.

1. 1

   Open Business Settings

   Go to business.facebook.com/settings and choose the business that owns the app and the WhatsApp account.

2. 2

   Add a system user

   Open Users → System users and click Add. Name it (for example officely-bot), set the role to Admin, and create it.

3. 3

   Give it the app

   With the system user selected, click Assign assets. Choose Apps, tick your app, turn on Full control, and save.

4. 4

   Give it the WhatsApp account

   Click Assign assets again. Choose WhatsApp accounts, tick your WhatsApp Business account, turn on Full control, and save.

5. 5

   Generate the token

   Click Generate new token and choose your app.

6. 6

   Set it to never expire

   Under Token expiration, choose Never.

7. 7

   Pick the permissions

   Tick whatsapp_business_messaging and whatsapp_business_management. Then click Generate.

8. 8

   Copy it now

   Meta shows the token once. Copy it to a password manager. You paste it into Officely in step 6.

3. Find your Phone number ID and WhatsApp Business Account ID#

1. 1

   Open API Setup

   In developers.facebook.com/apps, open your app and click WhatsApp → API Setup in the left menu.

2. 2

   Pick your number

   In the From list, choose the real phone number you want to connect (not Meta's test number, unless you're only testing).

3. 3

   Copy the Phone number ID

   Under the number, copy Phone number ID. It's a long number, for example 106540352242922.

4. 4

   Copy the WhatsApp Business Account ID

   Copy WhatsApp Business Account ID (the WABA ID). It's also a long number, and it's different from the Phone number ID.

4. Subscribe your app to your WhatsApp account#

Meta only sends a WhatsApp account's messages to apps that are subscribed to it. Officely doesn't do this for your own app, so do it once yourself. Run this in a terminal, with your WABA ID and the permanent token from step 2:

curl -X POST "https://graph.facebook.com/v21.0/YOUR_WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer YOUR_PERMANENT_TOKEN"

Meta answers {"success":true}. To check it worked, list the subscribed apps and look for your app's name:

curl "https://graph.facebook.com/v21.0/YOUR_WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer YOUR_PERMANENT_TOKEN"

5. Set the webhook in your Meta app#

First copy your verify token: in Officely open Channels > WhatsApp · Official > Open settings > Connect manually. Under Webhook, the Verify token field has a copy button. It is your Officely account token (hidden on screen for safety; the copy button copies the full value).

1. 1

   Copy the Callback URL and Verify token

   In the Officely drawer, under Webhook, click the copy button next to Callback URL, then next to Verify token. (The same token is also under Developers > API > Keys > Legacy token.)

2. 2

   Open the webhook settings in Meta

   In your app on developers.facebook.com, click WhatsApp → Configuration. In the Webhook card, click Edit.

3. 3

   Fill in the two fields

   Callback URL: https://api.officely.ai/meta. Verify token: paste your Officely account token.

4. 4

   Verify and save

   Click Verify and save. Meta calls Officely, Officely confirms the token, and the dialog closes.

5. 5

   Subscribe to webhook fields

   Under Webhook fields, click Manage and Subscribe to messages. Without it, no customer message reaches Officely.

6. 6

   Add the recommended fields

   Also subscribe to message_template_status_update, message_template_quality_update, template_category_update, phone_number_quality_update, account_update and business_capability_update. Officely uses them to warn you when a template is paused or your number's quality drops.

6. Paste the details in Officely#

1. 1

   Open Channels

   In Officely, click Channels in the sidebar.

2. 2

   Open the official card

   On the WhatsApp · Official card (subtitle Meta Cloud API), click Open settings.

3. 3

   Open the manual form

   If the drawer shows Connect with Meta at the top, turn on Connect manually (Already have your own Meta app? Enter its IDs and token.). Otherwise the form is already open.

4. 4

   Check the webhook URL

   The Webhook section shows https://api.officely.ai/meta with a copy icon. It's the same URL you used in step 5.

5. 5

   Fill in Meta credentials

   Under Meta credentials: WhatsApp Business Account ID = your WABA ID. Phone number ID = your Phone number ID (digits only, required). Access token = your permanent token. Each field shows where to find its value in Meta.

6. 6

   Save

   Click Save. You see Channel saved, and the card shows the Configured pill.

If you see We couldn't save this channel, check that Phone number ID contains only digits, then try again.

Under Logging, Log Callback is optional: a URL of yours that also receives each message log, for example to keep your own copy.

7. Add your App secret (optional)#

The App secret lets Officely confirm that every message really comes from Meta, not from someone faking a webhook call.

1. 1

   Copy the App secret

   In developers.facebook.com, open your app, then App settings → Basic. Next to App secret, click Show, confirm your password, and copy it.

2. 2

   Paste it in Officely

   In the same Officely drawer, under Webhook security (optional), paste it in App secret, then click Save. It's stored encrypted.

8. Test it#

1. 1

   Publish a chatbot

   Make sure a chatbot is live: open it and click Publish. See Publish.

2. 2

   Message your number

   From a different phone, send hi to the WhatsApp number you connected.

3. 3

   Check the reply

   Your bot should answer within a few seconds.

4. 4

   Check Logs

   In Officely, open Logs in the sidebar. The conversation shows at the top, with the customer's message and the bot's reply. If a step went wrong, a notice under the message says why.

No conversation in Logs at all? The message never reached Officely: see Messages don't arrive below.

Common problems#

Meta says the webhook couldn't be verified

• The Verify token must be your Officely account token from Developers → API → Keys → Legacy token, exactly, with no spaces. An ofl_live_ API key doesn't work.
• The Callback URL must be exactly https://api.officely.ai/meta.
• After 10 tries in 10 minutes, Officely stops answering verification attempts for a while. Wait 10 minutes, then try once more with the right token.

Messages don't arrive

The customer writes, nothing shows in Logs, and the bot doesn't answer. Check, in this order:

1. WhatsApp Business Account ID in Officely is your WhatsApp Business Account ID, not your Business ID or app ID (step 3). This is the most common cause.
2. Phone number ID is the Phone number ID of the same number the customer writes to.
3. Your app is subscribed to your WhatsApp account (step 4).
4. The webhook field messages is subscribed (step 5).
5. If you added an App secret, it's the secret of this same app (step 7).

The bot answered for a day, then stopped

Almost always an expired token: the temporary token from API Setup lasts about 24 hours. In Logs, the conversation shows a notice that your Meta token expired or is no longer valid. Create a permanent token, paste it in Token in Officely, and click Save.

The bot answers some customers, but a message to a customer fails

If more than 24 hours passed since the customer's last message, WhatsApp only allows an approved template. Logs shows Not delivered with more than 24 hours passed since the customer's last message. Send a template to restart the conversation.

Still stuck?

Go through My bot didn't answer, or look up the notice in Delivery errors in Logs.