# Managing WhatsApp Connections > Everything on the Connections page and each connection's own page - statuses, renaming, WhatsApp usernames, pause, resume, OTP-confirmed delete, and per-number settings. Source: https://docs.theavoxai.com/connections A **connection** is a WhatsApp number linked to your Switchboard. The Connections page lists every connection, and each connection has its own page for its settings. This page covers managing a number you've already connected. To connect one, see [Setup](https://docs.theavoxai.com/connections/setup) or [Getting started](https://docs.theavoxai.com/getting-started). ## Who can do what | Action | Admin | Manager | | --- | --- | --- | | View connections, their settings and the message forwarding log | Yes | Yes | | Connect a new number (the setup wizard) | Yes | Yes | | Choose "Also send messages to my own server" in the wizard, or delete a setup in progress | Yes | No | | Run **Check health now** on [Health](https://docs.theavoxai.com/health) | Yes | Yes | | Rename a connection | Yes | No | | Set the WhatsApp username | Yes | No | | Turn Calling or Identity-Key Check on or off | Yes | No | | Change message forwarding (switch, URL, secret, test event, resend) | Yes | No | | Create, rotate or revoke API keys | Yes | No | | Pause, resume or delete a connection | Yes | No | The **Owner** is the Switchboard's first Admin - normally whoever created it. The Owner has every Admin permission, and a few account emails go only to the Owner, including the [delete confirmation code](#delete). The Manager column shows the defaults: an Admin can give a Manager the **Manage connections** permission (rename, pause, resume, delete, forwarding, calling and username) or the **Manage API keys** permission, person by person. A change the person isn't allowed to make doesn't save, and where a section is read-only it says so - for example "Only an Admin can change message forwarding." See [Permissions](https://docs.theavoxai.com/switchboard/members#permissions). ## The Connections page The header reads "Manage the WhatsApp Business Account connected to your number." Below it, a strip shows: - **Your Switchboard's name**, next to the [Avox Avatar](https://docs.theavoxai.com/avox-avatar). Hover the avatar to see how many more numbers you can connect (for example "Room for 2 more."). - **The usage chip** - for example `1/3` **connections used**. The bar fills as you use your plan's connections. - **View setup docs** - opens [Getting started](https://docs.theavoxai.com/getting-started). - **Connect another number** - opens the [setup wizard](https://docs.theavoxai.com/connections/setup). When every connection your plan allows is in use, **Connect another number** is turned off and the strip reads "You've used every connection your plan allows." ([AVX-3009](https://docs.theavoxai.com/error-codes/avx-3009)). Pause or delete a connection, or upgrade on [Change plan](https://docs.theavoxai.com/billing/change-plan), to free a slot. Below the strip you'll find: - **A Setup in progress card** when you finished step 2 of the wizard but didn't connect with Meta. It shows the connection name you typed (or "New connection"), when you started, and your choice ("Avox handles everything." or "Avox, plus forwarding to your server."). Click **Resume setup** to reopen the wizard where you left off. Admins also see **Delete**, which asks you to confirm, then removes the saved setup (name, choice, endpoint URL and signing secret). Nothing on WhatsApp changes, and the deletion is recorded in the audit log. - **One card per connection**, newest first. - **Related docs** - quick links to setup, webhook setup, Meta Embedded Signup, and managing a connection. A Switchboard with no connections and no saved setup opens straight into the setup wizard. ### How the connection limit works Your plan sets how many numbers you can connect (see [Plans](https://docs.theavoxai.com/plans)). The limit is one shared pool across every Switchboard you own on that plan, not a separate limit per Switchboard. Spend it however you like: several numbers in one Switchboard, or one each across several. Only connections with the **Connected** status count toward the pool. A paused connection doesn't, so pausing a number frees its slot. ## Connection cards Each card shows: - **The name** - hover it and click the pencil to rename it. See [Renaming a connection](#renaming-a-connection). - **The phone number.** - **The status** - see [Connection statuses](#connection-statuses). - **The forwarding Endpoint URL**, when one is saved. See [Message forwarding](https://docs.theavoxai.com/connections/webhook-override). For a **Connected** or **Paused** connection, the card also shows: - **Connected** - the date you connected it - and **Active** - how long ago Avox last received an event for this number ("Just now", "5m ago", "3h ago", "2d ago", or "Never"). - **Calling** - a switch. See [Calling](https://docs.theavoxai.com/connections/calling). - **The WhatsApp username** - see [Your WhatsApp username](#your-whatsapp-username). At the bottom are the **Manage** menu, **Settings** and **Open in Meta**. **Settings** opens the [connection's own page](#the-connection-page). **Open in Meta** opens this number's WhatsApp Business Account in Meta's WhatsApp Manager in a new tab. ## Connection statuses | Status | Meaning | | --- | --- | | **Connected** | The number is live. Messages, statuses and calls flow through Avox. | | **Connecting** | Avox is finishing the setup with Meta. This normally takes seconds. | | **Disconnected** | The number is no longer linked. Connect it again with the setup wizard. | | **Error** | Setup didn't complete, or Meta reported a problem. See [Troubleshooting](#troubleshooting-a-connection). | | **Paused** | Paused from the **Manage** menu (or by Avox support). Sending stops until it's resumed. | | **Paused - billing issue** | Paused because the Switchboard's subscription was canceled. The card reads "This Switchboard's subscription was canceled - every connection is paused until payment resumes." with a **Review billing** link. | ## Renaming a connection The name is a label for your team - it shows across the dashboard and in emails about the connection. It isn't sent to Meta and customers never see it. Admins only. **1. Click the pencil** Hover the connection's name on its card or its own page, then click the pencil. **2. Type a name and save** Type 1 to 60 characters and click the check mark. The [Avox Avatar](https://docs.theavoxai.com/avox-avatar) says "Renamed." | Message | What it means | | --- | --- | | Give this connection a name / Keep it under 60 characters | The name is empty or longer than 60 characters. | | Couldn't rename that connection. Try again. | The name didn't save - try again ([AVX-3019](https://docs.theavoxai.com/error-codes/avx-3019)). A Manager sees this too, because renaming is Admin-only. | ## Your WhatsApp username A WhatsApp username lets customers find and message your business by a name such as `@acme_support` instead of only your phone number, and open a chat with a short link like `wa.me/acme_support`. Avox sets it through Meta's Username API. It needs an Admin (or the **Manage connections** permission), and the connection must be **Connected**. > **Note** > > Usernames are Meta's feature, and Meta decides which names are available. Meta is opening them up > country by country and account by account, and each name is unique across all of WhatsApp - so a > name that's taken or protected (for example, a well-known brand) goes to its owner. Meta's own > suggestions for your number are the most likely to be approved. **1. Open the username row** On the connection's card, or in the **WhatsApp username** section of its own page, click **Set a WhatsApp username** (or your current `@username` to change it). **2. Pick a name** Type one, or click one of **Suggested by Meta for this number** - names Meta proposes for your number, which Meta says are more likely to be approved. A checklist under the field turns green as each rule is met: - 3 to 35 characters - only letters, numbers, periods (`.`) and underscores (`_`) - capitals become lowercase - at least one letter - no period at the start or end, and no two periods in a row - doesn't start with `www` - doesn't end like a web address (`.com`, `.org` and so on) **3. Save** Click **Save**. Avox sends the name to Meta and shows Meta's answer: - **Live** - approved, and WhatsApp users can see it. - **Reserved** - approved, but not shown yet because usernames aren't live in that region. It turns on automatically once they are. If Meta doesn't return username details for your number, the editor says so: usernames may not be open to it yet, but you can still try saving one. | Message | What it means | | --- | --- | | Username rule not met: ... | One of the rules above isn't met yet ([AVX-3017](https://docs.theavoxai.com/error-codes/avx-3017)). | | Meta didn't accept that username. It may be taken, protected, or not available for this number yet. | Usernames are unique across all of WhatsApp, not only Avox. Try another, or one of Meta's suggestions ([AVX-3018](https://docs.theavoxai.com/error-codes/avx-3018)). | | This number needs to be connected first. | Usernames can only be set on a **Connected** number. | ## Managing a connection The **Manage** menu on each card (and in the summary at the top of the connection's own page) holds **Pause**, **Resume** and **Delete**. Admins only. ### Pause Available when the connection is **Connected**. Pausing is an Avox setting - nothing changes on Meta's side, and your number stays registered with WhatsApp. While a connection is paused: - It stops counting toward your plan's connection pool, so you can use that slot elsewhere. The avatar says "Paused - this frees up a slot in your plan." - Sending from Avox stops: Inbox replies, [automations](https://docs.theavoxai.com/automation), and the [Avox API](https://docs.theavoxai.com/avox-api) (requests return `connection_paused` - see [API errors](https://docs.theavoxai.com/api/errors#connection_paused)). - The **Calling** and **Identity-Key Check** switches are turned off for editing. If the pause fails, you see "Couldn't pause that connection" with "Couldn't pause that connection. Try again." ([AVX-3020](https://docs.theavoxai.com/error-codes/avx-3020)). ### Resume Available when the connection is **Paused**. Resuming takes a slot in your plan's connection pool again, so Avox checks you still have room first. The avatar says "Back and connected." | Message | What to do | | --- | --- | | Resuming this would put you over your plan's connection limit. | Pause or delete another connection, or upgrade your plan ([AVX-3021](https://docs.theavoxai.com/error-codes/avx-3021)). | | This connection is paused because this Switchboard's subscription was canceled - resolve it on the Billing page first. | Fix the subscription on [Billing](https://docs.theavoxai.com/billing). The connection resumes automatically once payment is back in good standing ([AVX-3082](https://docs.theavoxai.com/error-codes/avx-3082)). | | Couldn't pause that connection. Try again. | Shown under "Couldn't resume that connection" for any other problem ([AVX-3020](https://docs.theavoxai.com/error-codes/avx-3020)). Try again. | A connection paused for billing doesn't show **Resume** in its menu at all - it resumes by itself when the payment is resolved. A connection paused by Avox support is resumed by Avox support: contact [Support](https://docs.theavoxai.com/support). ### Delete Deleting removes the connection from your Switchboard. Because it's permanent after a short grace period, Avox confirms it with a one-time code sent to the Owner. **1. Click Delete** Choose **Delete** in the **Manage** menu. A red box opens under the menu and reads "Sending a code to the Switchboard owner's email...". Avox emails a 6-digit code to the Switchboard's Owner - even when another Admin clicked Delete. **2. Get the code** The box now reads "Enter the 6-digit code emailed to the Switchboard owner to confirm deleting this connection." The code is valid for 10 minutes. If you're not the Owner, ask them for it. Requesting a new code cancels the previous one. **3. Enter it and confirm** Type the code and click **Confirm delete**, on the same account that clicked Delete. You see "Connection deleted - It's kept for 6 days before being permanently removed." Click **Cancel** instead to stop. What happens next: - The connection disappears from your dashboard straight away and stops counting toward your plan. - Every Admin gets an email saying who removed which number, and the date it can be recovered until. - The connection is kept for **6 days** in case it was a mistake, then removed permanently. > **Warning** > > Need a deleted connection back? Contact [Support](https://docs.theavoxai.com/support) within the 6 days. After that, connect > the number again from scratch with the [setup wizard](https://docs.theavoxai.com/connections/setup). | Message | What to do | | --- | --- | | Couldn't start the delete request - Couldn't send the delete confirmation code. Try again. | Try again shortly ([AVX-3022](https://docs.theavoxai.com/error-codes/avx-3022)). | | That code is invalid or expired. | Check the code, or click **Delete** again for a new one if 10 minutes have passed ([AVX-3023](https://docs.theavoxai.com/error-codes/avx-3023)). | | Enter the 6-digit code from your email. | The code must be exactly 6 digits. | After 5 wrong attempts the code stops working; click **Delete** again to get a new one. ## The connection page Click **Settings** on a card to open the connection's own page. Its title is the connection's name, with "Everything about this WhatsApp connection - status, message forwarding, and Meta-side management." and a **Docs** button. **Back to connections** returns to the list. The page has these sections, top to bottom: 1. **Summary** - the [Avox Avatar](https://docs.theavoxai.com/avox-avatar), name (with the rename pencil), phone number, status, Connected date, Active time, the **Manage** menu and **Open in Meta**. 2. **Meta identifiers** - **WABA ID**, **Phone Number ID**, **Business ID** and your **Plan**. You may need these when working in Meta's tools or talking to [Support](https://docs.theavoxai.com/support). 3. **Message forwarding** - see [Message forwarding](#message-forwarding). 4. **Outbound API keys** - see [Outbound API key](#outbound-api-key). 5. **Calling** - see [Calling](https://docs.theavoxai.com/connections/calling). 6. **Identity-Key Check** - see [Identity-Key Check](#identity-key-check). 7. **WhatsApp username** - see [Your WhatsApp username](#your-whatsapp-username). ## Message forwarding Sends each new incoming customer message on this number to your own HTTPS endpoint, signed by Avox (this section used to be called **Webhook Override**). It has an on/off switch, the **Endpoint URL** with **Save URL**, the **Signing secret** with **Rotate secret** (or **Create secret** before the first one exists), **Send test event**, and **Recent deliveries** with **Payload** and **Resend**. Admins can change it; everyone can see it and the delivery log. Only customer messages are forwarded - delivery statuses, calls and messages your team sends stay in Avox. The full guide is on [Message forwarding](https://docs.theavoxai.com/connections/webhook-override). ## Outbound API key The **Outbound API keys** section lets your own server send WhatsApp messages from this connection through the [Avox API](https://docs.theavoxai.com/avox-api), without ever holding Meta's access token: ``` POST https://api.avox.com/api/messages/send Authorization: Bearer avx_live_... ``` - Each key belongs to exactly one connection. - Admins choose **Live key** (sends real messages) or **Test key** (never sends anything), then click **Create live key** or **Create test key**. The full key is shown **once**, in "Your new API key" - copy it then, because it can't be shown again. - Active keys are listed with their first characters, a **Live** or **Test** badge, the key's name, and when it was created and last used. **Rotate** swaps a key for a new one with a grace period, and the bin button revokes a key immediately. A rotated key shows "Expires in ..." until its grace period ends. - With no keys, the section reads "No key yet - create one when your server is ready to send through Avox." Managers see "Only an Admin of this Switchboard can create, rotate or revoke keys." - Under the list, **API logs** opens every request made with this connection's keys, and **Settings > API keys** opens every key across all your connections, with **Test** and each key's recent requests. See [API keys](https://docs.theavoxai.com/connections/api-keys) for every step, and [Authentication](https://docs.theavoxai.com/avox-api/authentication) for how to send the key. ## Identity-Key Check A switch for WhatsApp's recipient identity protection. When it's on, Meta blocks a message with error `137000` if the WhatsApp account behind the recipient's phone number has changed since you last messaged them - for example a recycled phone number or a customer moving to a new account. It's recommended for sensitive messages such as login codes and payment details. Admins only, and the connection must be **Connected**. Turning it on or off asks Meta to change the setting first; the switch stays only when Meta confirms, and the avatar says "Identity checks are on." or "Identity checks are off." If it fails, the switch goes back and you see "Couldn't update identity-check settings. Try again." ([AVX-3052](https://docs.theavoxai.com/error-codes/avx-3052)). The switch is turned off for editing while the connection is paused. See [Meta error codes](https://docs.theavoxai.com/meta-error-codes) for `137000`. ## Emails about your connections | Email | Who gets it | When | | --- | --- | --- | | Your number is connected | Every Admin | A new connection finishes setup. | | A number was removed | Every Admin | A connection is deleted. Includes who deleted it and the recovery date. | | Delete confirmation code | The Owner | Someone clicks **Delete** on a connection. | | Access expiring | Every Admin | Meta's access for a connection is about to expire. | | Message forwarding paused | Every Admin | Your endpoint failed 5 forwarded messages in a row. See [Message forwarding](https://docs.theavoxai.com/connections/webhook-override#retries-and-auto-pause). | | API key created, revoked, or flagged | Every Admin | See [API keys](https://docs.theavoxai.com/connections/api-keys#emails-about-api-keys). | | Critical account alert | The Owner | Meta sends an alert about your account. Controlled by **WhatsApp account alerts** on [Compliance](https://docs.theavoxai.com/compliance). | See [Emails](https://docs.theavoxai.com/emails) for every email Avox sends. ## Troubleshooting a connection - **Messages aren't sending.** Open [Health](https://docs.theavoxai.com/health) and click **Check health now** for Meta's own answer. If a check row is red, follow its suggested fix. For a specific Meta error number, see [Meta error codes](https://docs.theavoxai.com/meta-error-codes). - **Status is Error or Disconnected.** Use **Open in Meta** to look at the number in WhatsApp Manager, then connect it again with the [setup wizard](https://docs.theavoxai.com/connections/setup). - **The setup popup didn't finish.** See [If the connection doesn't go through](https://docs.theavoxai.com/connections/setup#if-the-connection-doesnt-go-through). Closing the popup early changes nothing - you can safely try again. - **"Choose a plan before connecting a WhatsApp number".** Subscribe on [Billing](https://docs.theavoxai.com/billing) first. - **Your server isn't receiving messages.** Check **Recent deliveries** in [Message forwarding](https://docs.theavoxai.com/connections/webhook-override#recent-deliveries), or the **Received** tab of [API logs](https://docs.theavoxai.com/connections/api-keys#api-logs). - **Still stuck?** Contact [Support](https://docs.theavoxai.com/support) with the connection's Phone Number ID from the connection page.