> ## 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 WhatsApp via QR Code Scan (Unofficial API)

> Pair any WhatsApp number with Soneka by scanning a QR code — no Meta approval needed. Best for testing and demos; not recommended for production use.

The Unofficial API connection lets you pair any existing WhatsApp number with Soneka in about 30 seconds by scanning a QR code — the same mechanism WhatsApp Web uses. There's no Meta approval, no business account required, and no waiting. It's a fast way to explore Soneka's interface, run internal demos, or test automation flows before committing to an official channel. That said, it comes with serious limitations for business use, and you should understand the trade-offs before relying on it beyond a sandbox environment.

<Warning>
  Using the Unofficial API for commercial messaging violates Meta's Terms of Service. Numbers used this way risk being temporarily restricted or permanently banned by WhatsApp. **Do not use this connection method for customer-facing production traffic.**
</Warning>

## When to Use the Unofficial API

<CardGroup cols={2}>
  <Card title="✅ Good Use Cases" icon="circle-check">
    * Exploring Soneka features before going live
    * Internal team demos and training
    * Personal number testing during development
    * Quick proof-of-concept automations
  </Card>

  <Card title="❌ Not Suitable For" icon="circle-xmark">
    * Customer communications at any scale
    * Marketing broadcasts or campaigns
    * Production chatbot or automation flows
    * Any commercial messaging activity
  </Card>
</CardGroup>

## How to Pair via QR Scan

<Steps>
  <Step title="Open Integrations">
    In Soneka, go to **Settings → Integrations → Unofficial API** and click **Connect via QR Code**.
  </Step>

  <Step title="QR Code Appears">
    Soneka generates a QR code on screen. This code is valid for 60 seconds. If it expires before you scan, click **Refresh** to generate a new one.
  </Step>

  <Step title="Open WhatsApp on Your Phone">
    On the phone whose number you want to pair, open WhatsApp and navigate to **Linked Devices** (tap the three-dot menu on Android, or go to Settings on iOS).
  </Step>

  <Step title="Scan the Code">
    Tap **Link a Device** and point your phone's camera at the QR code on your Soneka screen. The pairing completes within a few seconds.
  </Step>

  <Step title="Confirm Connection">
    Soneka will show a green **Connected** status next to the paired number. The number will appear as a channel in your inbox immediately.
  </Step>
</Steps>

<Note>
  Your phone must stay connected to the internet (Wi-Fi or mobile data) for the Soneka session to remain active. Unlike WhatsApp Cloud API, this connection runs through your phone, not Meta's servers.
</Note>

## Keeping the Session Alive

Because this connection mirrors WhatsApp Web, the session can drop if:

* Your phone loses internet connectivity for an extended period.
* WhatsApp logs out the linked device (this can happen after several weeks of inactivity).
* Meta detects unusual activity and terminates the session.

**To maintain the session:**

* Keep your phone charged and connected to the internet.
* Open WhatsApp on your phone at least once every few days.
* Check the session status in **Soneka → Settings → Integrations → Unofficial API** — a yellow **Reconnect** button means the session has ended and you need to scan a new QR code.

<Tip>
  Set a Soneka notification alert for session disconnections so you're aware immediately if the pairing drops during a demo or test.
</Tip>

## Limitations and Warnings

Understanding what this connection cannot do will save you frustration and protect the phone number you're using.

<Accordion title="No message templates (HSM)">
  Template messages (used for notifications and broadcasts outside the 24-hour customer service window) require a Meta-approved WABA. The Unofficial API cannot submit or send templates.
</Accordion>

<Accordion title="Risk of number ban">
  Meta actively detects and restricts numbers that use unauthorized clients at scale. Sending bulk messages, broadcast campaigns, or automated high-volume messages from an unofficial connection significantly increases the risk of a temporary or permanent ban on that phone number.
</Accordion>

<Accordion title="No green tick eligibility">
  Official Business Account (OBA) status and the green verified checkmark are only available to WhatsApp Cloud API users. Unofficial connections will never display business verification.
</Accordion>

<Accordion title="Session instability">
  Sessions can drop without warning. Unlike Cloud API — which has Meta's 99.9% uptime SLA — an unofficial session depends on your phone's connectivity and WhatsApp's tolerance for linked devices.
</Accordion>

<Accordion title="Not suitable for team inboxes at scale">
  While multiple Soneka team members can respond from a single connected number, the underlying session is tied to one physical phone. If that phone is unavailable, the entire channel goes offline.
</Accordion>

## When to Upgrade to Cloud API

You should migrate to the **WhatsApp Cloud API** as soon as:

* You're ready to send messages to real customers.
* You need to send template messages or broadcast campaigns.
* You want stable uptime guarantees and don't want a session tied to a phone.
* You plan to apply for the green tick verified badge.
* Your message volume exceeds casual testing.

Upgrading takes about four minutes using Meta's embedded signup built into Soneka. Your conversation history in Soneka is preserved when you switch channels.

<CardGroup cols={1}>
  <Card title="Set Up WhatsApp Cloud API →" icon="arrow-right" href="/integrations/whatsapp-cloud-api">
    Connect the official Cloud API channel in about four minutes — no developer credentials required.
  </Card>
</CardGroup>