Skip to main content

Setting Up WhatsApp Cloud API

Connect a WhatsApp Business number to your Intercom workspace through Meta's Cloud API for inbound messages and replies.

Written by Tarek Khalil

Before you start

You need:

  • A Facebook Business Manager account with admin access.

  • An approved WhatsApp Business Account (WABA) inside that Business Manager, or the ability to create one during setup.

  • A phone number that is not currently registered on the consumer WhatsApp app, can receive an SMS or voice verification code, and is owned by your business. Mobile and landline numbers are both supported.

  • Business verification started or completed on Facebook Business Manager. Unverified businesses are limited to a small message volume until verification finishes.

  • Admin access to the Octopods workspace.

Step 1: Open the WhatsApp Setup page

  1. In your workspace, click the option to add a new channel.

  2. In the Add a Channel modal, select WhatsApp under Popular Channels.

  3. The WhatsApp Setup page opens with a WhatsApp Phone Numbers card showing any numbers you’ve already connected.

Step 2: Log in with Facebook Business Manager

  1. Click Login with Facebook Business Manager.

  2. A Facebook sign-in window opens. Sign in with a Facebook user that has admin access on the Business Manager containing your WABA.

  3. Facebook shows an embedded signup flow that walks you through selecting the Business Manager to use, selecting or creating the WhatsApp Business Account, selecting or adding the phone number you want to use, and verifying that phone number via a code sent by SMS or voice call.

  4. Review the permissions Facebook asks for (messaging and WhatsApp Business management) and approve them.

When the flow finishes, Facebook redirects back to Octopods.

Step 3: Review your phone number

Back on the WhatsApp Setup page, the phone number you just onboarded appears in the WhatsApp Phone Numbers card. Each row shows:

  • The display name and phone number.

  • Verification status (for example, Verified).

  • Platform label (CLOUD_API).

  • Registration status — if the number is not yet registered on Cloud API, a Register on Cloud API action is available.

Step 4: Register on Cloud API (if needed)

If the number was just added and not yet registered:

  1. Click Register on Cloud API in the row for your number.

  2. Octopods sends the registration request to Meta. After a few seconds the row updates to show the number as registered.

If the number was already registered on another Cloud API connection, you’ll see a warning that it belongs to a different workspace. You cannot activate the same number in two Octopods workspaces at once — deactivate it in the other workspace first.

Step 5: Activate the channel

  1. Click Activate Channel in the row for your number.

  2. Octopods subscribes to the webhook events on Meta’s side so inbound messages start flowing.

  3. The number’s row updates to show the channel as active, and a new channel appears in your workspace’s channel list with a Connected status.

Step 6: Send a test message

  1. From a personal WhatsApp account, send a message to the number you just connected.

  2. Open the Intercom Inbox for this workspace. A new conversation appears with your message.

  3. Reply to the conversation from Intercom.

  4. The reply arrives on WhatsApp from your business number.

If the test fails, open the channel’s detail page and use the Sync action to re-confirm the connection with Meta. See Channel Statuses and Troubleshooting for more diagnosis steps.

After activation

  • Use the Sync action on the number’s row to refresh Meta-side metadata (display name, verification state, quality rating) at any time.

  • Use Deactivate to stop the channel while keeping the WABA and number intact. You can re-activate later without re-running Facebook login.

  • Outbound messages outside of an active 24-hour conversation window must use an approved WhatsApp template. See Managing WhatsApp Message Templates.

Common issues

  • “Phone number is already in use” — the number is registered on Cloud API in another Business Manager or another Octopods workspace. Migrate it on Meta’s side first, or pick a different number.

  • “Business not verified” — your Facebook Business Manager has not completed verification. You can still send a small volume of messages, but production traffic requires verification. Complete the verification inside Business Manager and retry.

  • Messages aren’t delivering — check the quality rating on the number in WhatsApp Manager. A low rating can throttle sending until it recovers.

What’s next

Did this answer your question?