Connecting a number#
You need a connected number before kenari can proxy Cloud API calls or forward webhooks for it. Open Numbers in the dashboard and choose Connect a number. There are three ways to connect:
| Option in the dashboard | Method | Best for |
|---|---|---|
| Bring your own account | Your Meta app's credentials | You already have a Meta app with WhatsApp set up |
| Connect a dedicated phone number | Meta Embedded Signup | A number used only through the API |
| Keep using the WhatsApp Business app | Embedded Signup, coexistence variant | A number that stays in the WhatsApp Business app as well (Coexistence) |
Before you connect#
- Active subscription. Your account must be trialing, active, or
past_duewithin its 3-day grace period. Otherwise connecting fails with402 billing_inactive. - Room in your quota. Each plan allows a fixed number of connected numbers. Connecting past it fails with
409 quota_reached.
| Plan | Numbers | Price |
|---|---|---|
| Starter | 1 | $3 / month |
| Basic | 2 | $5 / month |
| Pro | 5 | $8 / month |
New accounts start with a 7-day trial. The Numbers page shows how many numbers you've used out of your limit.
A WhatsApp Business account (WABA) can be bound to only one kenari account at a time. Connecting a WABA that another kenari account already holds fails with 409 waba_owned_elsewhere.
Bring your own account (BYO)#
Use this when you already run your own Meta app with the WhatsApp product. kenari calls Meta with your credentials. Meta sends webhooks to your app's callback URL, and you point that URL at kenari.
1. Gather five values#
| Field | Where to find it | Notes |
|---|---|---|
| WABA ID | WhatsApp Manager or your app's WhatsApp → API Setup page | Digits only |
| Phone number ID | API Setup, next to the number | The number's Meta ID, not the phone number itself |
| Access token | A system user token for your app | Must include both whatsapp_business_management and whatsapp_business_messaging, and must be granted access to this WABA. Meta tokens start with EAA. |
| App ID | App settings → Basic | Digits only |
| App secret | App settings → Basic | 32 hexadecimal characters. kenari uses it to verify the webhooks Meta sends for this number. |
The access token and app secret are encrypted before they're stored. They're never shown again or sent back to the browser.
2. Submit the form#
Choose Connect a number → Bring your own account, fill in the five fields and choose Connect. Before storing anything, kenari checks the credentials with Meta:
- The token is valid and was issued for your App ID. This call also proves the app secret is correct.
- The token has both WhatsApp permissions.
- The token can access the WABA.
- The phone number exists and belongs to that WABA.
- kenari subscribes your app to the WABA's webhooks.
If a check fails, nothing is saved. The response is 400 byo_invalid, with the failing field marked:
| Field | Reason | Meaning |
|---|---|---|
app_secret | app_credentials_rejected | Meta rejected the app ID and secret pair |
access_token | token_invalid | The token is expired or invalid |
app_id | token_app_mismatch | The token belongs to a different app |
access_token | scope_missing | The token lacks a WhatsApp permission |
waba_id | waba_not_granted | The token hasn't been granted this WABA |
phone_number_id | phone_not_found | Meta can't find this phone number ID |
waba_id | waba_unreadable | kenari couldn't list the WABA's numbers |
phone_number_id | phone_not_in_waba | The number isn't in this WABA |
waba_id | subscribe_failed | Meta wouldn't subscribe your app to the WABA |
3. Point your Meta app's webhook at kenari#
When the connection succeeds, the dashboard shows a Callback URL and a Verify token. In your Meta app, go to WhatsApp → Configuration → Webhook, paste both and save.
Callback URL: https://<kenari api host>/webhook/byo/<your-inbound-token>
Verify token: <shown in the dashboard>When you save, Meta sends a verification request to this URL. kenari answers it with your verify token and marks the webhook as verified. In the same Meta screen, subscribe to the webhook fields you want forwarded, such as messages. kenari can only forward what Meta sends.
To see these values again later, open the number's ⋯ menu. The Meta webhook settings panel shows the callback URL and verify token, when the webhook was verified, and when kenari last received an event for it.
kenari checks every event on this URL against your app secret (X-Hub-Signature-256) and rejects any that fail. Each callback URL accepts up to 600 requests per minute. Above that, it answers 429.
Rotating BYO credentials#
If you rotate the token or app secret at Meta, choose Update credentials in the number's ⋯ menu. You can replace the access token, the app secret or both. kenari runs the same checks with Meta before saving.
Embedded Signup (dedicated number)#
- Choose Connect a number → Connect a dedicated phone number, then Continue with Facebook.
- In Meta's popup, sign in, then pick or create a business, a WABA and a phone number. Grant both WhatsApp permissions (management and messaging).
- kenari exchanges the code Meta returns, subscribes the WABA to webhooks and registers the number.
If you create a WABA in the popup but don't add a number, kenari saves the WABA and lists the numbers it finds so you can choose one.
If registration doesn't finish, the number shows Registration pending. Choose Register number in its ⋯ menu, then Retry registration. If the number already has a two-step verification PIN, Meta rejects kenari's PIN, and the dashboard asks for your existing 6-digit PIN (pin_required).
Connection errors#
| Code | Status | Meaning |
|---|---|---|
billing_inactive | 402 | No active or trialing subscription |
quota_reached | 409 | Your plan's number limit is full |
waba_owned_elsewhere | 409 | The WABA is connected to another kenari account |
embedded_signup_restricted | 403 | Embedded Signup isn't enabled for your account |
byo_invalid | 400 | BYO credentials failed a check (see the field table above) |
token_invalid | 400 | Meta rejected the credentials, or the token doesn't grant this WABA |
scope_missing | 400 | A WhatsApp permission wasn't granted in the popup |
subscribe_failed | 502 | Meta couldn't subscribe the WABA to webhooks |
meta_unreachable | 503 | Meta didn't respond. Try again. |
pin_required | 409 | Registration needs the number's existing two-step verification PIN |
Number status#
Each number on the Numbers page shows one of these statuses:
| Status | What it means |
|---|---|
| Connected | Ready to send |
| Registration pending | Meta registration didn't finish. Retry it. |
| Access revoked | The token expired or was revoked. Reconnect, or update BYO credentials. |
| Disconnected by Meta | Meta ended the connection (for example, partner removal or a ban). Reconnect to resume. |
| Restricted | Meta restricted the number |
| Flagged | Meta temporarily blocked the number |
kenari updates a number's quality rating, throughput and messaging tier when Meta sends a phone_number_quality_update or phone_number_name_update event. To pull fresh details from Meta now, choose Refresh from Meta in the number's ⋯ menu (at most once every 10 seconds per number).
Disconnecting#
Open a number's ⋯ menu and choose Disconnect. kenari then:
- deregisters the number with Meta (best effort; the local disconnect goes ahead even if Meta is down)
- stops proxying and forwarding events for it immediately
- if it was the last number on its WABA, unsubscribes the WABA from webhooks and deletes the stored token
- frees a slot in your quota
You can connect the number again later.
Downgrading below your number count#
If you move to a plan with fewer numbers than you have connected, the dashboard shows You're over your number allowance. Choose which numbers to disconnect and confirm.