Skip to main content

Setting Up WhatsApp Cloud API for HubSpot

Connect a WhatsApp Business number to a HubSpot workspace, pick which HubSpot inbox receives the messages, and activate it.

Written by Tarek Khalil

Before you start

You need:

  • A HubSpot workspace already connected to Octopods.

  • 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.

  • Business verification started or completed on Facebook Business Manager.

  • Admin access to the HubSpot portal with permission to grant additional HubSpot permissions.

  • At least one inbox already configured inside HubSpot.

Step 1: Open the WhatsApp setup

  1. Sign in to Octopods and open the HubSpot workspace.

  2. Click the option to add a new channel.

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

  4. If this is the first channel on the workspace that needs HubSpot’s Custom Channels permissions, Octopods shows a Re-authorize HubSpot prompt.

Step 2: Re-authorize HubSpot (if prompted)

  1. Click the re-authorize button. HubSpot opens in a new window.

  2. Sign in to HubSpot if you’re not already.

  3. HubSpot shows the additional permissions Octopods is requesting — the ones that let Octopods create and manage custom channels inside your inbox, plus the standard conversation and contact permissions.

  4. Approve.

  5. HubSpot redirects back to Octopods, and the WhatsApp setup continues.

You only need to do this once per workspace. If you add another custom-channel-based channel (SMS, Telegram, Slack) later, HubSpot won’t ask again.

Step 3: Log in with Facebook Business Manager

  1. On the WhatsApp Setup page inside Octopods, click Login with Facebook Business Manager.

  2. Sign in with a Facebook user that has admin access on the Business Manager containing your WABA.

  3. Facebook runs an embedded signup flow where you pick the Business Manager, pick or create the WhatsApp Business Account, pick or add the phone number, and verify the number via SMS or voice call.

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

Facebook redirects back to Octopods.

Step 4: Register the number on Cloud API

Back on the WhatsApp Setup page, the phone number appears in the WhatsApp Phone Numbers card. If it isn’t yet registered on Cloud API:

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

  2. Octopods sends the registration request to Meta. The row updates to show the number as registered.

Step 5: Pick a HubSpot inbox and activate

  1. On the number’s row, click Activate Channel.

  2. The channel detail page opens with a Select HubSpot Inbox dropdown and an Activate button that is disabled until you pick an inbox.

  3. Pick the inbox where WhatsApp conversations should appear. The dropdown lists every inbox on your HubSpot portal.

  4. Click Activate.

  5. Octopods registers the channel as a custom channel inside HubSpot and subscribes to webhook events on Meta’s side so inbound messages start flowing.

  6. The channel status changes to Connected, and the channel appears in the workspace’s channel list.

Step 6: Send a test message

  1. From a personal WhatsApp account, send a message to your business number.

  2. Open the HubSpot inbox you selected. A new conversation appears with the message.

  3. Reply from HubSpot.

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

What’s different from Intercom

Compared to Setting Up WhatsApp Cloud API on an Intercom workspace, the HubSpot setup adds two steps:

  • Re-authorizing HubSpot for Custom Channels permissions the first time.

  • Selecting a HubSpot inbox to route messages to before activating.

Everything else — the Facebook login, the WABA selection, the number registration — is identical.

Managing the channel

  • Change the inbox — open the channel detail page and pick a different inbox from the dropdown. New messages route to the new inbox; existing conversations stay where they are.

  • Sync — refresh Meta-side metadata (display name, verification state, quality rating) at any time.

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

  • Outbound messaging windows and templates work the same as on Intercom. See Managing WhatsApp Message Templates.

Common issues

  • “HubSpot re-authorization required” — HubSpot hasn’t granted the Custom Channels permissions. Follow the prompt.

  • Inbox dropdown is empty — your HubSpot portal has no inboxes configured. Create one in HubSpot first.

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

  • Messages aren’t reaching HubSpot — confirm the inbox is still assigned on the channel detail page, and that the HubSpot custom channel is still active in HubSpot’s inbox settings.

What’s next

Did this answer your question?