Connect WhatsApp Cloud API

Before you start

• A Meta Business account. Free, takes 5 minutes at business.facebook.com.
• A phone number you can use for WhatsApp. It must be able to receive an SMS or voice call once for verification. Mobile or landline both work. Cannot already be in use by the regular WhatsApp app — you'll have to delete that account first.
• Your Unit workspace owner / admin login on ctrunit.app. Agents can't connect channels.

Step 1 — Create a WhatsApp Business app on Meta

1. Go to developers.facebook.com/apps and click Create app.
2. Pick Other for use case, then Business for app type.
3. Name the app something like YourBrand WhatsApp and link it to your Meta Business account.
4. In the new app dashboard, find WhatsApp in the products list and click Set up.

Meta will offer a free test number while you're trying things out — it works fine for development but caps at 5 conversations per 24h. You'll add your real number in Step 3.

Step 2 — Generate a permanent access token

1. In your Meta Business account, open Business Settings → System users.
2. Click Add, name the system user something like unit-integration, and give it the Admin role.
3. With that system user selected, click Generate new token. Pick the WhatsApp app you created in Step 1 and tick:
   • whatsapp_business_messaging
   • whatsapp_business_management
4. Set token expiry to Never if Meta lets you (some accounts cap at 60 days; that's fine — you can rotate).
5. Copy the token somewhere safe (a password manager). Meta won't show it again. This is what Unit uses to send messages on your behalf.

Step 3 — Add and verify your phone number

1. Back in the WhatsApp product page, open Phone numbers → Add phone number.
2. Enter your business name and the phone number to connect. Pick Text message or Phone call for verification.
3. Enter the code Meta sends. The number is now live on WhatsApp Cloud.
4. In the same panel, copy the Phone number ID (a long number, not the phone itself) and the WhatsApp Business Account ID. You'll paste both into Unit in the next step.

Step 4 — Connect Unit

1. Open Unit at ctrunit.app → Channels → Add channel → WhatsApp.
2. Paste:
   • Access token from Step 2
   • Phone number ID from Step 3
   • Business account ID from Step 3
3. Click Connect. Unit verifies the credentials with Meta and shows your phone number on the channels list.
4. Unit shows a Webhook callback URL and a Verify token. Keep both visible — you'll paste them into Meta in Step 5.

Step 5 — Point Meta's webhook at Unit

1. Back in the WhatsApp product page on Meta, open Configuration → Webhook → Edit.
2. Paste the Webhook callback URL from Unit (Step 4) into Callback URL.
3. Paste the Verify token from Unit into Verify token. Click Verify and save.
4. Once verified, click Manage next to Webhook fields and subscribe to:
   • messages

Meta sometimes shows the webhook as "not verified" for 30 seconds after saving — that's fine, it'll clear. If it stays red after a minute, double-check the Verify token (no spaces) and the URL (must be the one Unit shows, including /whatsapp/<tenant> at the end).

Step 6 — Send a test message

1. From any phone, send a WhatsApp message to your business number.
2. Open Unit → Inbox. The conversation appears within a few seconds.
3. Reply from the inbox. The customer gets it on WhatsApp.

Reply ticks (✓ → ✓✓ → ✓✓ blue) update live as Meta acknowledges and the customer reads. If they stay grey, Meta hasn't actually received the outgoing message — usually a token issue.

Common issues

"The phone number is already in use by another account"

You have to delete the regular WhatsApp app account on that number first. Open WhatsApp on the device → Settings → Account → Delete my account. Wait 10 minutes and retry. The Cloud API account is separate and doesn't affect personal WhatsApp on other devices.

Webhook keeps showing as "not verified"

Three things to check:

• The Verify token in Meta has to match the token Unit shows exactly, including case. No leading or trailing spaces.
• The URL must include the tenant slug at the end (Unit copies the full URL when you click the copy button).
• Your Unit instance must be reachable from the public internet. If you're self-hosting and put Unit behind a VPN or a closed firewall, Meta's verifier can't reach it.

Messages arrive with delay or not at all

Unit logs every webhook delivery from Meta. Open Channels → click your WhatsApp channel → Recent webhook events. If you see events arriving but no inbox row, contact us — that's a bug. If you see no events at all, Meta isn't forwarding (the webhook itself isn't set up correctly).

Token expired

If Meta capped your token at 60 days, you'll see a 401 invalid_token error in Unit's Channels page. Generate a fresh token (Step 2) and paste it in. Unit picks up the new token without dropping any in-flight messages.

What changes after you go live

Meta's test number caps at 5 conversations per 24 hours and shows a "test" banner to recipients. Once you verify your business and pick a pricing category, those caps lift. The handover is on Meta's side — Unit doesn't need to know.

There's no per-message charge from Unit. Meta charges per conversation (free for the first 1,000 /month at the time of writing); see Meta's WhatsApp pricing for the latest.

Still stuck?

Send the symptom + a screenshot to [email protected]. If you mention the workspace slug we can usually resolve it the same day.