Why refresh a token

Meta access tokens are tied to the Meta Business Login session you completed when you first connected WhatsApp. Over time — or when Meta changes its permission model — a token can:

Expire after its validity window.
Lose scope if Meta updates the permissions required to manage WhatsApp Business Accounts (WABAs), phone numbers, or templates.
Get revoked if an admin on your Meta Business Portfolio removes Octopods’ access.

When any of these happen, Octopods can’t read fresh data from Meta for the affected WABA or send messages that require an up-to-date permission scope. Refreshing re-establishes the connection.

How you’ll notice

There is no single notification banner today. The most common signs that a token needs refreshing:

New phone numbers added in Meta Business Portfolio don’t appear after pressing Login with Facebook Business Manager in Octopods.
Sending fails with a permissions or auth-related error from Meta.
Template status changes from Meta stop syncing to Octopods.

If you suspect the token is the cause, run through the refresh flow below.

Refreshing the token

The refresh uses the same Meta Business Login flow as the initial connection:

Sign in to Octopods.
Open the workspace with the affected WABA.
Go to Channels and reopen the WhatsApp Setup page (via Add Channel → WhatsApp).
Press Login with Facebook Business Manager.
Complete the Meta login with an account that has admin access to the Business Portfolio.
Grant the permissions Octopods is requesting.
Confirm the selection — Meta redirects you back to Octopods and the token is refreshed.

What the scopes do

Two permissions carry most of the weight:

WhatsApp Business Messaging — required to send messages and receive delivery events. If this scope is missing, Octopods can’t send outbound messages.
WhatsApp Business Management — required to read and manage WABAs, phone numbers, and templates. If this scope is missing, Octopods can’t sync template status, apply display name changes, or register numbers on Cloud API.

When reconnecting, check both permissions are granted. Meta remembers your previous grants and pre-selects them for you, so the flow is usually a single confirmation click.

What stays the same after a refresh

Refreshing a token does not disrupt your existing setup:

Channels stay connected to their workspaces.
Message templates keep their status — nothing re-enters review.
Phone number configurations (welcome messages, signatures) are unchanged.
In-flight conversations continue normally.

The only thing that changes is the authorization Octopods uses to talk to Meta on your behalf.

Scope per WABA

Meta lets you grant access to specific WABAs rather than every WABA in your portfolio. When you reconnect, you can:

Keep the same WABAs you originally selected. Meta pre-selects them for you.
Add more WABAs that weren’t connected before. They appear in Octopods on return.
Remove WABAs you no longer want Octopods to manage. Deselecting a WABA during the flow revokes Octopods’ access to it.

If a reconnect fails

If the reconnect doesn’t succeed, Octopods displays an alert beginning with Unable to connect WhatsApp phone numbers. The most common causes:

Not an admin on the Business Portfolio. The Facebook account you’re signed in with needs admin access to the Meta Business Portfolio that owns the affected WABA. Sign in with an admin account.
Permission was not granted. One of the required scopes (whatsapp_business_messaging or whatsapp_business_management) was unchecked during the flow. Re-run and accept all requested permissions.
Business verification has lapsed. Messaging limits may be reduced until your WABA’s business verification is restored inside Meta Business Portfolio. See the verification statuses in What is a WhatsApp Business Account (WABA)?.

Refreshing Your WhatsApp Access Token