Connect WhatsApp Business app to API and a team inbox, step by step

Put the laptop and the phone side by side. The phone is the one with the WhatsApp Business app on it, signed in, with the number you want to keep using. That's most of the preparation.

This walkthrough shows how to connect WhatsApp Business app to API access and a shared team inbox, using Avox. You'll spend most of the time in a window Meta runs, and a minute or two on the phone. Nothing on your number changes until the very end, so you can close the window and start over at any point.

What to have ready

• An Avox account with a plan. You can't connect a number without one. Plans start at US$24 a month, and the pricing page lists them all.
• The phone with the WhatsApp Business app. Not the regular WhatsApp app. Meta requires version 2.24.17 or higher.
• A Facebook account that's an admin of your Meta business portfolio (and of the WhatsApp Business Account, if you already have one). Meta's window asks you to sign in with it.
• Pop-ups allowed for the Avox dashboard, and the dashboard opened at its normal https:// address. Meta only opens its window on a secure page.
• A number that isn't connected somewhere else. One number can sit in one Avox Switchboard at a time. If another WhatsApp provider still holds it, remove it from there first.

If the number isn't in the WhatsApp Business app at all, you want the other route in the wizard, "New number (Bot only)", which is simpler and has no phone step. This page is about the number that's already in the app.

Connect WhatsApp Business app to API, step by step

1. Open the connection wizard

In the dashboard, click Connections in the sidebar. With no numbers yet you'll see Connect a WhatsApp number. If you already have one, use Connect another number. A half-finished attempt appears as a Setup in progress card with Resume setup.

2. Choose "Existing number (Coexistence)"

Step 1 is Number type. Pick Existing number (Coexistence), which is the default, and click Next. This is what tells Meta to share the number with the app instead of moving it off. If you want the background first, our explainer covers it.

3. Name it and say how messages are handled

Step 2 is Webhook setup. Give the connection a Connection name your team will recognise, such as "Shop main line" (up to 60 characters). Then choose Use Avox for everything. That's the recommended option, and you need no server of your own. The other option, Also send messages to my own server, is for developers and needs an Admin.

4. Continue to Meta

Step 3 is Connect with Meta. It shows a short preview of Meta's screens, with a Desktop tab and a Mobile tab, so skim it once. Then click Continue to Meta. Keep the Avox tab open behind Meta's window.

5. Follow Meta's window on your computer

The screens come in this order:

1. 1An overview of what connecting enables. Click Continue.
2. 2Choose your number. If it's listed with a "Registered" badge, select it. Otherwise pick "Enter a new phone number" and type it. Meta's "new" means new to the platform, not new to you.
3. 3Check what Meta shows next. You should see your WhatsApp Business app's business profile. That tells you you're on the Coexistence route.
4. 4Choose the business portfolio that should own the account. Use an existing one if you have it, because Meta often restricts portfolios created inside the window.
5. 5Scan the QR code (next step).
6. 6Confirm the WhatsApp Business Account and choose your time zone.
7. 7Review what you're sharing with Avox and click Confirm.
8. 8Wait while Meta connects the account, then click Finish.

6. Confirm on your phone

At the QR step, open WhatsApp Business on the phone and scan the code. Meta also sends the same link to your number as a WhatsApp message, in case scanning is awkward. Then, on the phone:

1. 1Open the message from Facebook Business and tap Connect.
2. 2Read Meta's explanation of how the app and the platform work together.
3. 3Choose whether to share your chat history. Share your existing chats, or start fresh with new threads. You get one go at this, so pick the one you want to live with. Meta's documentation says shared history covers about the last six months and leaves out group chats.
4. 4You'll see the connected platform confirmed.

Go back to the computer. The Next button in Meta's window becomes available by itself once the phone side is done, then carry on to Finish.

7. Let Avox finish

Meta closes the window and Avox takes you back to Connections. The number shows Connecting, then Connected. Every Admin on the Switchboard also gets an email saying the number is connected.

Check that it works

Don't skip this. It takes two minutes.

1. 1From another phone, send a message to your business number. It should appear in the phone app and in the Avox Inbox.
2. 2Reply from the phone app. The reply should appear in the Avox inbox too.
3. 3If you shared history, open the Inbox after a short while. Past conversations arrive in batches, so give it time.

If all three pass, you're connected. The details of what moves between the app and Avox are on the Coexistence sync page.

When it doesn't go through

Avox shows a red panel, "The connection didn't go through", with a Try this list and a Retry connection button. A failed attempt changes nothing on your number, so retrying is safe. The usual causes:

• You closed Meta's window early. Retry, and leave it open until it closes by itself.
• The window never appeared. Your browser blocked the pop-up. Allow pop-ups for the dashboard and click Continue to Meta again.
• Next stays locked after the QR code. You haven't tapped Connect on the phone yet.
• "Already connected to an Avox account." Another Switchboard holds the number. Delete it there, then connect it here.
• You aren't an admin of the WhatsApp Business Account you're connecting. Ask whoever is.

Stuck on something not listed? The setup reference lists every message and what to do. Meta's overview of the sign-up flow is in its Embedded Signup documentation.

Bring your team in

A shared inbox needs more than one person in it. Go to Settings, Switchboard, Invitations, click Invite, enter an email address and choose a role. Managers handle the day-to-day work (inbox, contacts, templates, automations) and Admins also control connections, billing and the team. How to split the work once everyone's in is the subject of our post on running a WhatsApp shared inbox.

Questions people ask

Do I need a developer or my own server?

No. Choose Use Avox for everything and Avox sets up the connection with Meta for you. A server is only needed if you also want incoming messages forwarded to your own system.

Will my phone app stop working?

Not when you follow the Coexistence route. Keep the app signed in and open it regularly, because Meta can disconnect a shared number when the phone goes quiet for long. The limitations article lists the details.

Can I connect more than one number?

Yes. Each number is its own connection, up to the limit your plan sets.

What if I picked the wrong history option?

It can't be changed afterwards, because it's a one-time choice made on the phone. To redo it you'd disconnect the number and run the setup again.

Your next step: open Connections and read the preview on the last wizard step once before you click Continue to Meta. Knowing what each screen looks like removes most of the nerves.