Connect WhatsApp

Connect your own WhatsApp number via Meta embedded signup. Bring a brand-new number or one you already run on the WhatsApp Business app. What you need, what happens during the popup, and what you get back.

Prerequisites

  • A HookMyApp account. Sign in with hookmyapp login.
  • A Facebook Business Manager you control. Meta embedded signup runs through it.
  • A phone number to connect. It can be a brand-new number that is not yet on WhatsApp, or a number you already use in the WhatsApp Business app (connected through Coexistence, see below).

Run the connect command

Start the embedded-signup flow with the CLI.

The CLI opens a browser tab running Meta's embedded-signup flow. You sign into Facebook, pick a Business Manager, create or select a WhatsApp Business Account, pick a phone number, and verify it.

For the underlying mechanism see Meta's embedded-signup docs.

hookmyapp channels connect

Connection options

Two kinds of number work, and you pick between them inside the same embedded-signup flow.

OptionBest forWhat it needs
New WhatsApp numberStarting fresh on a number that is not on WhatsApp yetA phone number you can verify by SMS or voice
WhatsApp Business app numberKeeping the WhatsApp Business app while you also send at scaleA number already active in the WhatsApp Business app and access to that phone

New WhatsApp number

Add or pick the number during embedded signup and verify it with the SMS or voice code Meta sends. This is the standard path for a number that is not on WhatsApp yet.

WhatsApp Business app number

Connect the number you already use in the WhatsApp Business app, and keep using the app at the same time. During signup Meta walks you through confirming the connection from inside the WhatsApp Business app and choosing whether to share your chat history. Once it connects, you keep replying one to one from the app while sending at scale through the API, and your messaging history stays in sync across both.

The number must be on WhatsApp Business app version 2.24.17 or newer. Because it stays compatible with the app, this kind of number sends at up to 20 messages per second. For the full Meta walkthrough see Onboard WhatsApp Business app users.

What you get back

  • WHATSAPP_WABA_ID: your WhatsApp Business Account ID. The channel's Channel ID (ch_xxxxxxxx) is what you pass to per-channel commands like hookmyapp channels env <channel>, hookmyapp channels webhook set <channel>, and hookmyapp channels health <channel>. Find it with hookmyapp channels list.
  • WHATSAPP_ACCESS_TOKEN: a HookMyApp gateway access token (hmat_…), scoped to this one channel. Pull it with hookmyapp channels env <channel> or hookmyapp channels token <channel>, or copy it from the channel page in the dashboard. Your app sends it as Authorization: Bearer; the gateway swaps it for the real Meta token server-side, so the Meta token never leaves HookMyApp.
  • WHATSAPP_PHONE_NUMBER_ID: the ID Meta assigns to your verified phone. Used in the send URL.

One number, one workspace. A WhatsApp number can only be connected in one workspace at a time. If another workspace already owns it, the connect fails with "This WhatsApp number is already connected in another workspace. Disconnect it there first to use it here." Disconnect it there, then retry. Other numbers on the same WhatsApp Business Account are independent: each connects as its own channel, in whichever workspace you choose.

Token lifetimes and rotation

Your hmat_ gateway token does not expire. The long-lived Meta token behind it refreshes automatically inside HookMyApp; you never handle Meta token rotation yourself. If a background refresh ever fails, the channel's health shows it and re-running hookmyapp channels connect re-links the account.

If your gateway token leaks, rotate it: hookmyapp channels token <channel> --rotate, or the Rotate button on the channel page. The old token stops working immediately and the new one is shown once.

Next steps