Getting Started: Connect WhatsApp

Connecting your WhatsApp number to Avox takes a few minutes and doesn't interrupt anything your team is doing on WhatsApp today. This page walks you from sign-up to your first conversation. Each step of the connection wizard has its own section below - the Docs for this step link in your dashboard opens the matching one.

Create your account#

Sign up at Avox sign-up with your email address, or continue with Google or Facebook. Avox creates your account and your first Switchboard - your team's workspace.

A short welcome chat runs before your dashboard opens ("Quick chat before your dashboard's ready. About a minute, promise."). It asks a few questions about you, your business, and how you plan to use WhatsApp, and lets you name your Switchboard. The kind of user you say you are (for example a developer or a business owner) also sets the shape of your Avox Avatar. At the end you can connect your number straight away from the chat, or choose to do it later from the dashboard ("All good. You're in. Connect whenever, straight from the dashboard."). If you leave halfway, the chat picks up where you left off.

Choose a plan#

Connecting a number needs an active plan. Until you have one, Overview shows "No active plan - subscribe to unlock connections, templates, and Flows." with a See plans link. Compare plans on Plans and subscribe on Billing.

Your plan also sets how many numbers you can connect. See How the connection limit works.

Open the connection wizard#

Open Connections in the sidebar. With no numbers connected yet, the wizard starts straight away; otherwise click Connect another number. Any member of your Switchboard - Admin or Manager - can run it. When every connection your plan allows is in use, Connect another number is greyed out and the page reads "You've used every connection your plan allows." (AVX-3009).

The wizard has three steps: 1. Number type, 2. Webhook setup and 3. Connect with Meta. If you also forward messages to your own server, a Send test event step comes before Connect with Meta. The step bar turns a step green with a tick once it's done, and red when it needs fixing. Every step has a Docs for this step link to its section on this page, and the current step is part of the page address, so reloading keeps your place.

If you started a setup earlier and left after Webhook setup, Connections shows a Setup in progress card ("Your choices are saved") with a Resume setup button. The wizard then opens with "Welcome back - continuing your setup" where you left off. An Admin can also Delete a setup in progress, after confirming; nothing on WhatsApp changes.

Connection type#

The first step asks what kind of number you're connecting. This decides which Meta signup path you get.

• Existing number (Coexistence) - the number is already active in the WhatsApp Business app on your or your team's phone. Avox connects alongside it: the app keeps working as before, and Avox adds the shared inbox, automation, and everything else on top. This is the right choice for almost every existing business. See Coexistence, explained.
• New number (Bot only) - the number isn't used in the WhatsApp Business app. It's dedicated to Avox's bot and API. The setup is simpler, since there's nothing existing to keep in sync.

Click Next.

Webhook config#

The second step, Webhook setup, asks for a Connection name - a label your team will recognize, such as "Acme Support EU" (up to 60 characters) - and how this number's messages are handled:

• Use Avox for everything (recommended) - Avox receives all of the number's WhatsApp events from Meta and powers the shared inbox, templates, Flows, automation, Avox AI, calls, analytics, health and logs. Avox sets up the webhook with Meta and checks it with its own verify token, so you don't need a server and there's nothing else to fill in.
• Also send messages to my own server - everything above, plus Avox forwards each new incoming customer message to your own HTTPS endpoint. Only incoming customer messages are forwarded - not delivery statuses, calls, or messages your team sends. Admins only.

Message forwarding#

If you choose Also send messages to my own server, enter Your endpoint URL. It must start with https://, use the standard port and be reachable from the public internet. When you click Next, Avox checks the address and creates a signing secret. It's shown once, with a copy button - copy it into your server's settings now, then click I've saved it, continue. After that it's only shown masked. Avox signs every forwarded message with it (the Avox-Signature header), retries if your server doesn't answer, and lists every delivery under Recent deliveries on the connection's page. Forwarding switches on by itself when the connection completes, and your conversations still appear in the Inbox. See Message forwarding for the request format and how to check the signature, and Meta webhooks for everything Meta tells Avox about your number.

Click Next. Avox saves your choices as a draft, so a Setup in progress card brings you back if you leave. If a field needs fixing, the wizard shows the problem under that field, for example "The endpoint URL must start with https://" (AVX-3006).

Webhook test#

This step only appears when you forward messages to your own server. Click Send test event: Avox sends a sample message marked "test": true to your endpoint, signed exactly like a real one.

• "Delivered - your endpoint answered 200." (in green) - your server accepted it. Any 2xx status counts.
• A red message - your server didn't answer, or answered with an error. The most common causes are that it isn't deployed yet, isn't served over HTTPS, or rejected the signature (AVX-3101).

Next is available once you've sent a test. A failed test doesn't block you - you can fix your server later and send another test from the connection's page. Lost the secret? Make a new secret replaces it and shows the new one once.

Meta Embedded Signup#

The last step, Review & connect with Meta, hands you over to Meta's own secure window - Meta Embedded Signup - where you authorize Avox on your WhatsApp Business Account. This is the step that creates the connection.

On this step you'll see a summary of your choice from Webhook setup (with Change this to go back), and an illustrated What to expect during setup walkthrough of Meta's screens, with Desktop and Mobile tabs. When you're ready:

1. 1

   Click Continue to Meta

   Meta's window opens. By continuing, you confirm you're authorized to connect this WhatsApp Business Account and agree to Avox's Terms of Service, and you acknowledge the Privacy Policy.

2. 2

   Follow Meta's screens

   The screens below show what to expect. Keep Meta's window open until it closes by itself.

3. 3

   Click Finish

   While Meta's window is open, the walkthrough's status reads Connecting. When it finishes, you're returned to Connections, where your number shows Connected.

Coexistence vs. new number in Meta's window#

• On the Coexistence path, Meta detects that your number is registered to the WhatsApp Business app and shows your existing business profile for you to confirm. Partway through, you scan a QR code with the WhatsApp Business app on your phone and choose whether to share your chat history.
• On the new number path, there's no existing profile. Meta verifies the number itself with an SMS or voice code, and there's no phone-side step.

On your computer - 9 screens, in order#

On your phone (Coexistence only) - 4 screens#

If you're on the Coexistence path, the WhatsApp Business app on your phone walks you through its own side of the signup, alongside the screens above:

If it doesn't go through#

When Meta's window doesn't finish, a red panel titled "The connection didn't go through" explains why (AVX-3002), lists what to check under Try this, and offers Retry connection and View troubleshooting docs. When Meta itself reported the problem, the panel shows Meta's own message and error number. The most common causes:

• Meta's window was closed early. Retry and keep it open until it closes by itself. Make sure pop-ups are allowed for the dashboard.
• You're not an admin on the WhatsApp Business Account. Ask its admin to run the setup, or to give you admin access in Meta Business Suite.
• For Coexistence, the phone step wasn't finished. Tap Connect in the WhatsApp Business app when Meta's prompt arrives.
• No plan or no free connection slot. Subscribe or free a slot, then retry.

Every cause and fix is listed on Setup.

After you connect#

• Chat history and contacts. With Coexistence, the chat history you chose to share and your WhatsApp Business app contacts arrive in Avox. See Coexistence sync.
• New messages. Every new message - whether it arrives through Avox or is sent from the phone app - appears in your shared Inbox.
• The rest of the dashboard unlocks - Inbox, Calls, Contacts, Templates, Flows, Automation, Health, Logs, and Analytics on plans that include it.
• A confirmation email goes to every Admin of the Switchboard.

Connection management#

Once a number is connected, its Manage menu on Connections offers three actions (Admins only):

• Pause - an Avox setting; nothing changes on Meta's side. Sending from Avox stops, and the number stops counting toward your plan's connection limit.
• Resume - turns it back on, after checking your plan still has a free connection slot. A number paused because of a billing issue comes back once the billing issue is resolved on Billing.
• Delete - confirmed with a 6-digit code emailed to the Switchboard's Owner. The connection is kept for 6 days in case it was a mistake, then removed for good.

See Managing a connection for every detail.

Next steps#

• Set a WhatsApp username for your number, so customers can find you by name - subject to Meta's availability in your country and account. See Connections.
• Invite your team - see Invites.
• Create your first template to start conversations outside the 24-hour window.
• Set up an automation to answer common questions.
• Turn on Calling.
• Send messages from your own systems with an API key.

Need help?#

If anything about connecting doesn't go as expected, open Support in your dashboard and we'll help you sort it out.