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

# Connect Your WhatsApp Number to Soneka — Three Ways

> Link a WhatsApp number to your Soneka workspace using the Cloud API, Twilio, or a QR code scan. All three methods connect to the same shared inbox.

Before your team can send or receive WhatsApp messages through Soneka, you need to connect at least one WhatsApp number to your workspace. Soneka supports three connection methods, each suited to a different situation — a Meta-managed Cloud API integration for full production capability, a Twilio bridge for teams already on that platform, and a fast QR-based connection for exploration and testing. All three methods route messages into the same shared inbox, broadcast engine, and Flow Builder once connected.

## Choosing the right method

Use this table to pick the method that fits your situation before you start setup.

|                            | **WhatsApp Cloud API**              | **Twilio**              | **Unofficial API (QR)** |
| -------------------------- | ----------------------------------- | ----------------------- | ----------------------- |
| **Setup time**             | \~4 minutes                         | \~2 minutes             | \~30 seconds            |
| **Meta approval required** | Yes (embedded signup)               | Via Twilio's WABA       | No                      |
| **Rate limits**            | Tiered (scales with quality rating) | Twilio tier applies     | Low (single device)     |
| **Green tick eligible**    | Yes                                 | Yes (via Twilio)        | No                      |
| **Sandbox available**      | No                                  | Yes                     | N/A                     |
| **Recommended for**        | All production use                  | Teams already on Twilio | Testing & demos only    |
| **Supports broadcasts**    | Yes                                 | Yes                     | Limited                 |
| **Supports templates**     | Yes                                 | Yes                     | No                      |

<Warning>
  The Unofficial API (QR) method is not approved by Meta. It works by linking Soneka to a real WhatsApp or WhatsApp Business app on your phone, the same way WhatsApp Web does. WhatsApp may disconnect the session or ban the number without notice. **Do not use it for customer-facing production traffic.**
</Warning>

***

## Setup instructions

<Tabs>
  <Tab title="WhatsApp Cloud API (Recommended)">
    The WhatsApp Cloud API is the official Meta-managed connection method. It gives your number access to the full WhatsApp Business Platform feature set: approved message templates, broadcasting at scale, green tick (verified business) eligibility, and the highest reliability tier. Setup uses Meta's embedded signup flow, which means you complete Meta's verification steps inside the Soneka interface — you never need to leave the app.

    **What you'll need before you start:**

    * A Facebook account with admin access to a Meta Business Manager (you can create a new Business Manager during signup if you don't have one).
    * A phone number that is **not** currently registered on WhatsApp Personal or WhatsApp Business. If your number is registered, you'll need to delete the existing WhatsApp account on that number first.
    * Your business display name and a brief business description.

    <Steps>
      <Step title="Open the channel setup wizard">
        In your Soneka workspace, go to **Settings → Channels** and click **Add channel**. Select **WhatsApp Cloud API**. Soneka will open the Meta embedded signup flow in a modal window.
      </Step>

      <Step title="Log in with Facebook and select your Business Manager">
        Click **Continue with Facebook**. Log in with the Facebook account that has admin access to your Meta Business Manager. If you're creating a new Business Manager, enter your business name, your name, and your business email, then click **Next**.
      </Step>

      <Step title="Create or select a WhatsApp Business Account (WABA)">
        Meta will ask you to create a new WABA or connect an existing one. For most new users, choose **Create a new WhatsApp Business Account**. Enter your business display name — this is what customers see as the sender name in WhatsApp — and select your business category and timezone.
      </Step>

      <Step title="Add your phone number">
        Enter the phone number you want to connect. Choose your verification method: **SMS** or **Voice call**. Meta sends a six-digit code to that number. Enter the code in the verification field to confirm ownership.

        <Note>
          If you receive an error saying the number is already registered with WhatsApp, you must first open WhatsApp on the device using that number, go to **Settings → Account → Delete my account**, and complete the deletion. Wait a few minutes before retrying the verification step.
        </Note>
      </Step>

      <Step title="Complete setup in Soneka">
        Once Meta confirms the number, the embedded signup modal closes and Soneka automatically stores your WABA credentials. Your new channel appears in **Settings → Channels** with a green **Connected** status. The number is now live — inbound messages will appear in your shared inbox within seconds.
      </Step>
    </Steps>

    <Tip>
      To apply for the green verification tick (the verified business checkmark next to your display name), go to **Settings → Channels**, click your connected number, and select **Apply for green tick**. Soneka submits the request to Meta on your behalf. Approval typically takes 2–7 business days and requires your Meta Business Manager to be verified.
    </Tip>
  </Tab>

  <Tab title="Twilio">
    Twilio is a communications platform that acts as a bridge between your phone number and the WhatsApp Business API. If your team already uses Twilio for SMS or voice, connecting via Twilio lets you manage billing and number provisioning in one place. Soneka connects to Twilio using your Account SID and Auth Token — no additional OAuth flow required.

    **What you'll need before you start:**

    * An active Twilio account at [twilio.com](https://www.twilio.com).
    * A Twilio phone number with WhatsApp enabled (or access to the Twilio WhatsApp Sandbox for testing).
    * Your Twilio **Account SID** and **Auth Token** from the Twilio Console dashboard.

    <Steps>
      <Step title="Enable WhatsApp on your Twilio number">
        Log in to the Twilio Console and navigate to **Messaging → Senders → WhatsApp Senders**. If you're using the sandbox, it's already enabled. For a production number, follow Twilio's WhatsApp approval process to enable WhatsApp on your number before proceeding.
      </Step>

      <Step title="Copy your Twilio credentials">
        From the Twilio Console home page, copy your **Account SID** (starts with `AC`) and your **Auth Token**. Keep these values ready — you'll paste them into Soneka in the next step.
      </Step>

      <Step title="Add the channel in Soneka">
        In Soneka, go to **Settings → Channels** and click **Add channel**. Select **Twilio**. A form appears with three fields:

        * **Account SID** — paste the value starting with `AC`.
        * **Auth Token** — paste your auth token.
        * **Twilio WhatsApp number** — enter the number in E.164 format, e.g. `+12025551234`.

        Click **Connect**.
      </Step>

      <Step title="Point Twilio's webhook to Soneka">
        Soneka generates a unique webhook URL after you click **Connect**. Copy this URL and paste it into your Twilio Console:

        1. Go to **Phone Numbers → Manage → Active Numbers** and click your WhatsApp number.
        2. Under **Messaging Configuration**, set the **A message comes in** webhook to **HTTP POST** and paste Soneka's webhook URL.
        3. Save your changes in the Twilio Console.

        Soneka will now receive all inbound messages from that Twilio number.

        <Note>
          If you're using the Twilio Sandbox rather than a production number, update the webhook under **Messaging → Try it out → Send a WhatsApp message → Sandbox settings** instead.
        </Note>
      </Step>

      <Step title="Verify the connection">
        Send a WhatsApp message to your Twilio number from a personal phone. The message should appear in Soneka's shared inbox within a few seconds. If it doesn't arrive, double-check that the webhook URL in Twilio exactly matches what Soneka provided — extra slashes or query parameters will cause the connection to fail.
      </Step>
    </Steps>

    <Tip>
      Twilio's sandbox number is shared with other Twilio users. When testing, your contacts must first send the sandbox join phrase (e.g., "join bright-sky") to the sandbox number before they can receive messages. Switch to a dedicated production number before going live with customers.
    </Tip>
  </Tab>

  <Tab title="Unofficial API (QR)">
    The Unofficial API method links Soneka to an existing WhatsApp or WhatsApp Business app on your phone by scanning a QR code — the same mechanism WhatsApp Web uses. No Meta approval, no credentials, no waiting. It's the fastest way to see Soneka working with real WhatsApp messages.

    <Warning>
      This method violates WhatsApp's Terms of Service. Meta may disconnect the session, temporarily restrict the number, or permanently ban it without warning. **Never use this method for customer-facing production workflows.** It is intended solely for internal testing, demos, and platform evaluation.
    </Warning>

    **What you'll need:**

    * A phone with WhatsApp or WhatsApp Business installed and an active number.
    * The WhatsApp app open and accessible during setup.

    <Steps>
      <Step title="Open the channel setup in Soneka">
        Go to **Settings → Channels**, click **Add channel**, and select **Unofficial API (QR scan)**. Soneka generates a QR code and displays it on screen. The QR code expires after 60 seconds — if it expires, click **Regenerate** to get a fresh one.
      </Step>

      <Step title="Scan the QR code from your phone">
        On your phone, open WhatsApp (or WhatsApp Business) and navigate to **Linked devices → Link a device**. Point your phone's camera at the QR code on your screen. WhatsApp will confirm the link with a brief connecting animation.
      </Step>

      <Step title="Confirm the connection in Soneka">
        Once the QR code is scanned, Soneka automatically detects the link and shows your number as **Connected** in **Settings → Channels**. Send a test message to your number from a different phone — it should appear in the Soneka inbox within a few seconds.
      </Step>

      <Step title="Keep the connection alive">
        Unlike the Cloud API, the QR connection depends on your phone being online and connected to the internet. If your phone runs out of battery, loses signal, or WhatsApp is force-closed, the Soneka session will drop. You'll need to re-scan the QR code to reconnect.

        <Note>
          Soneka will send you an in-app notification and email if your QR session disconnects unexpectedly. You can re-scan from **Settings → Channels** without losing any contact or conversation history already stored in Soneka.
        </Note>
      </Step>
    </Steps>

    <Warning>
      You cannot use the Unofficial API to send Meta-approved templates or run large broadcasts. For anything beyond basic testing, migrate to the WhatsApp Cloud API. Follow the [Cloud API setup steps](#whatsapp-cloud-api-recommended) above — the same phone number can be migrated once you delete the WhatsApp account on device and re-register it through Meta's embedded signup.
    </Warning>
  </Tab>
</Tabs>

***

## After connecting your number

Once your number is connected by any method, these are the recommended next steps to get it production-ready.

<CardGroup cols={2}>
  <Card title="Create message templates" icon="file-lines" href="/features/templates">
    Submit your first Meta-approved template so you can initiate outbound conversations and broadcasts.
  </Card>

  <Card title="Set up Auto-Reply" icon="reply" href="/features/team-inbox">
    Configure welcome messages and out-of-hours responses so inbound contacts always get an immediate reply.
  </Card>

  <Card title="Invite your team" icon="users" href="/account/plans-billing">
    Add agents to your shared inbox and set up assignment rules so conversations reach the right person automatically.
  </Card>

  <Card title="Build your first flow" icon="diagram-project" href="/features/flow-builder">
    Automate your most common conversation patterns — lead capture, appointment booking, order status — in the Flow Builder.
  </Card>
</CardGroup>

<Note>
  If you run into issues during number connection, contact Soneka support at [connect@soneka.africa](mailto:connect@soneka.africa) or WhatsApp +254 722 685 776. Include your workspace name and the connection method you're using, and a support engineer will help you troubleshoot.
</Note>