> ## Documentation Index
> Fetch the complete documentation index at: https://docs.typewise.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up WhatsApp

> Connect your WhatsApp Business number to Typewise.

Connect a WhatsApp Business phone number to Typewise so end customers can reach
your support team directly through WhatsApp.

<Note>
  Already connected? Configure how the AI handles WhatsApp conversations in the
  [WhatsApp Configuration](/documentation/behavior/whatsapp) page.
</Note>

***

## Choose a provider

The Installation page starts with **Pick a WhatsApp provider**. Choose how you
want to connect before entering any details:

| Provider                   | Best for                                                                                                        | What you need                                           |
| :------------------------- | :-------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ |
| **Twilio** *(Recommended)* | Keeping ownership of your account, billing, and number, and using the same WhatsApp number outside of Typewise. | An existing Twilio account with a live WhatsApp sender. |
| **Typewise**               | The simplest setup, where Typewise manages the number for you.                                                  | A Meta Business account and a phone number to verify.   |

<Note>
  Choosing **Twilio** keeps the WhatsApp number in your own Twilio account, so
  you can reuse it outside of Typewise. Choosing **Typewise** is simpler to set
  up but locks the number for use exclusively within Typewise.
</Note>

***

## Connect with Twilio

Use this path when you already run your own Twilio account. Typewise validates
your credentials, finds your WhatsApp sender, and points it at Typewise. Your
Twilio account, billing, and number stay yours.

### Prerequisites

Before you begin, make sure you have:

* A **Twilio account** with a **live WhatsApp sender** (account, WABA, and
  WhatsApp sender already set up in Twilio).
* Your **Account SID** (starts with `AC`) and the account's **primary Auth
  Token**, both from the [Twilio Console](https://console.twilio.com).

<Note>
  Only **one** WhatsApp sender per Twilio account is supported. Typewise does
  not create the Twilio account or register the sender for you on this path;
  bring one that is already set up.
</Note>

### Connect your Twilio account

<Steps>
  <Step title="Select Twilio as your provider">
    Go to the
    [Installation](https://platform.typewise.app/channels/whatsapp/installation)
    page (Behavior → Channels → WhatsApp → Installation tab) and, under **Pick a
    WhatsApp provider**, choose **Twilio**.
  </Step>

  <Step title="Enter your Twilio credentials">
    Paste your **Twilio SID** (your Account SID, starting with `AC`) and your
    primary **Auth Token** from the Twilio Console, then click **Connect**.
  </Step>

  <Step title="Wait for validation">
    Typewise validates the credentials and discovers the WhatsApp sender on your
    account. It automatically points that sender's inbound and status webhooks
    at Typewise, so no webhook configuration is required on your side.
  </Step>

  <Step title="Verify the connection">
    When your number shows a **Connected** badge, your WhatsApp channel is live
    and ready to receive messages.
  </Step>
</Steps>

### Manage your Twilio connection

Once connected, the Installation page shows your read-only credentials with a
**Connected** indicator, plus the tools to manage the number:

* **Connected numbers**: The number available to use within Typewise, with its
  current status:
  * **Connected**: The number is active and receiving messages.
  * **Inactive**: The sender is currently offline in Twilio. See
    [Troubleshooting](#troubleshooting).
  * **No WhatsApp number found**: No WhatsApp sender was found on the account.
    See [Troubleshooting](#troubleshooting).
* **Test your number**: Open a QR code to start a WhatsApp chat with the number
  and confirm it responds.
* **Manage in Twilio**: Open the [Twilio Console](https://console.twilio.com) to
  manage the sender directly.
* **Reconnect**: Re-run validation and sender discovery. Use this after you fix
  something in Twilio (for example, bringing an offline sender back online or
  adding a missing sender).

***

## Connect with Typewise

Use this path to let Typewise manage the WhatsApp number for you through Meta
Embedded Signup.

### Prerequisites

Before you begin, make sure you have:

* A **Meta Business account** (also known as a Facebook Business account)
* A **phone number** that can receive SMS or voice calls for verification. This
  number will become your WhatsApp Business number.

<Note>
  You can use a phone number that is already registered with WhatsApp or
  WhatsApp Business. It will be migrated during the setup process. Before you
  start, **delete the existing WhatsApp / WhatsApp Business account on the
  device** that owns the number; otherwise the OTP verification step will fail.
  We recommend against using a personal WhatsApp number, as it is difficult to
  revert.
</Note>

<Note>
  **Virtual or VoIP numbers are not supported.** WhatsApp requires a real mobile
  or landline number that can receive an OTP via SMS or voice call. Numbers from
  Twilio, Google Voice, or similar VoIP providers, and numbers behind an IVR or
  outbound-only systems, will fail OTP verification and cannot be registered.
</Note>

<Tip>
  For faster business verification, fewer initial messaging restrictions, and
  easier migration of an existing number, we recommend preparing the Meta side
  first. See [Set up WhatsApp on Meta](/guides/channels/setup-whatsapp-meta).
  Otherwise, Meta Embedded Signup (launched below) will create the Portfolio and
  WABA for you.
</Tip>

### Connect your WhatsApp number

<Steps>
  <Step title="Select Typewise as your provider">
    On the [Installation](https://platform.typewise.app/channels/whatsapp/installation)
    page (Behavior → Channels → WhatsApp → Installation tab), under **Pick a
    WhatsApp provider**, choose **Typewise**.
  </Step>

  <Step title="Enter your phone number">
    Enter the phone number you want to use in international format (e.g.,
    `+15017122661`).
  </Step>

  <Step title="Acknowledge number portability">
    Click **Connect business number**. A **Number portability** notice explains
    that the number will be linked to a dedicated account for security and
    routing, and that moving it to another provider later requires a release
    process that may take up to 24 hours. Click **Continue**.
  </Step>

  <Step title="Complete Meta Embedded Signup">
    A popup window will guide you through:

    * Logging in to your Meta Business account
    * Creating or selecting a WhatsApp Business Account (WABA)
    * Verifying your phone number via SMS or voice OTP
  </Step>

  <Step title="Wait for registration">
    After completing the signup, Typewise registers your phone number as a
    WhatsApp sender. Registration usually completes within **a few minutes**;
    the page refreshes automatically and shows the current status.

    If the status hasn't moved to **Online** after about 30 minutes, the
    registration is considered stuck. See the **Stuck** state under
    [Connection status](#connection-status) for next steps.
  </Step>

  <Step title="Verify the connection">
    Once the status shows **Online**, your WhatsApp channel is fully connected
    and ready to receive messages.
  </Step>
</Steps>

### Connection status

For Typewise-managed numbers, the Installation page shows the current state of
your WhatsApp integration:

* **Not configured**: No phone number has been connected yet. Follow the setup
  process above.
* **Connecting**: Registration is in progress. The page refreshes automatically
  until it resolves to **Online** or one of the states below.
* **Online**: Your WhatsApp channel is active and receiving messages. The
  connected phone number is displayed.
* **Online (updating)**: The channel stays online while the underlying sender
  configuration is being synced. No action required.
* **Offline**: The sender is registered but currently unable to deliver
  messages. The page shows a reason code from the upstream provider; usually
  transient. Use **Retry registration** to refresh, or **Disconnect** to start
  over.
* **Action needed**: Manual verification of the WhatsApp sender is required.
  Copy the displayed Sender ID and contact support. We will complete
  verification on your behalf.
* **Stuck**: Registration didn't complete within \~30 minutes. Use **Retry** to
  attempt again, or **Disconnect** to release the number and start a fresh
  setup.
* **Disconnected**: The integration was previously active but is no longer
  connected. Re-run the setup process to reconnect.

***

## Switch providers

To move a connected number between **Twilio** and **Typewise**, disconnect the
current provider first. If you pick the other provider while a number is still
connected, Typewise shows a **Switch provider** notice asking you to disconnect
before moving. This ensures you don't lose access to your existing number.

***

## Disconnect a WhatsApp number

How you disconnect depends on the provider you connected with.

### Twilio

Disconnecting detaches the number from Typewise. Your Twilio account, WhatsApp
sender, and number are left untouched; only Typewise stops sending and receiving
WhatsApp messages.

<Steps>
  <Step title="Open the Disconnect account section">
    On the Installation page, find the **Disconnect account** section and click
    **Disconnect**.
  </Step>

  <Step title="Confirm the disconnection">
    In the confirmation dialog, type **delete** to confirm, then click
    **Disconnect**.
  </Step>
</Steps>

<Tip>
  You can reconnect at any time by selecting **Twilio** again and re-entering
  your credentials.
</Tip>

### Typewise

Disconnecting a Typewise-managed number removes its registration from Typewise
and stops message delivery through this channel. Before you disconnect, you
**must** disable two-step verification (2FA) for the number in Meta Business
Suite. Otherwise the number stays locked to the WhatsApp Business Account and
cannot be re-registered (with Typewise or any other provider).

<Note>
  ⚠️ If you skip the 2FA step, re-registering the number will fail with Meta
  error **63110: "Already Registered"**, and the number will be stuck in a stale
  state until 2FA is manually disabled.
</Note>

<Steps>
  <Step title="Disable two-step verification in Meta Business Suite">
    Open [WhatsApp Manager → Phone
    numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers),
    select the number you want to release, then go to **Settings → Two-step
    verification** and click **Disable**.
  </Step>

  <Step title="Confirm in the Release modal">
    On the Installation page, click the **Disconnect** (trash) icon next to the
    number. In the confirmation modal, tick **"I have disabled two-step
    verification for this number"**. The Release button stays disabled until
    this checkbox is checked.
  </Step>

  <Step title="Release the number">
    Click **Release** to remove the phone number registration from Typewise. The
    channel will move to the **Disconnected** state.
  </Step>
</Steps>

<Tip>
  After disconnecting, you can reconnect at any time by going through the setup
  process again with the same or a different phone number.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: We couldn't validate these credentials">
    The Account SID or Auth Token is wrong. Double-check both values in the
    Twilio Console, and make sure you are using the account's **primary Auth
    Token** (scoped API keys can't be used on this path).
  </Accordion>

  <Accordion title="Error: This Twilio account has more than one WhatsApp sender">
    Only a single WhatsApp number per Twilio account is supported. Contact
    Typewise Support to connect an account with multiple senders.
  </Accordion>

  <Accordion title="Error: This Twilio account is already connected to another workspace">
    The Twilio account is in use by a different workspace. Disconnect it there
    first, or use a different Twilio account.
  </Accordion>

  <Accordion title="Error: A WhatsApp number is already connected">
    A number is already connected through another provider. Disconnect it first,
    then connect your Twilio account. See [Switch providers](#switch-providers).
  </Accordion>

  <Accordion title="No WhatsApp number found">
    Typewise validated your credentials but found no WhatsApp sender on the
    account. Add a WhatsApp sender in Twilio, then click **Reconnect**.
  </Accordion>

  <Accordion title="Number shows Inactive">
    The sender is currently offline in Twilio. Typewise does not auto-detect the
    sender's health, so fix it in the [Twilio
    Console](https://console.twilio.com) first, then click **Reconnect** to
    refresh the status.
  </Accordion>
</AccordionGroup>

***

Contact **Typewise Support** for help.