# Connecting a Channel

## Overview

A workspace cannot send or receive a single WhatsApp message until a channel is connected. WaDesk works with WhatsApp through three interchangeable channels, and the whole product — inbox, broadcasts, campaigns, flows, templates, auto-replies, the AI agent — adapts to whichever one your workspace is on.

Channel | How it connects | Approval needed?
--- | --- | ---
Unofficial API | Scan a QR code (or enter a pairing code) like WhatsApp Web. | None
WhatsApp Cloud API (Meta) | Connect a verified WhatsApp Business Account with its Phone Number ID, Access Token and WABA ID. | Meta business verification
Twilio | Paste a Twilio Account SID, Auth Token and WhatsApp sender number (sandbox or paid). | Twilio sender approval (or sandbox)

> One channel is active platform-wide, chosen by the admin at Admin → Settings → System Message Setting (Active messaging engine). Each workspace then connects its own credentials for that channel under Devices. The Devices screen detects the active channel and shows only the matching connector, so you never send through the wrong one.

This page walks through all three channels end to end: every credential, exactly where to get it, exactly where to paste it in WaDesk, and the exact webhook URLs.

## Which Channel Should I Choose?

If you are not sure, this table is the short version. The rest of the page assumes you have picked one.

| Unofficial API | Cloud API (Meta) | Twilio
--- | --- | --- | ---
Setup time | Minutes — scan a QR | Hours to days (Meta review) | Minutes (sandbox) / days (paid sender)
Meta approval | Not required | Required (verified business) | Required for production sender
Hosting | You run the helper service + the linked phone | You run the helper service + Meta hosts the Cloud API | You run the helper service + Twilio hosts the sender
Ban / suspension risk | Higher — unofficial, against WhatsApp terms for bulk | Low — official, quality-rated | Low — official via Twilio
Template messages | No formal approval; free-form only | Yes — official, approved templates | Yes — via Twilio Content / approved templates
Cost | Free (you pay only for hosting) | Meta conversation pricing | Twilio per-message + Meta pass-through
Best for | Fastest start, any number, low volume, internal use | Official trust, high volume, native Forms / catalog | Teams already standardised on Twilio

> Take the ban risk on the Unofficial API seriously. Linking a number via QR is WhatsApp Web technology; high-volume marketing through it can get the number banned. Use a dedicated phone number, warm it up slowly, and prefer the Cloud API for bulk.

## The Devices Screen

Everything channel-related lives at Devices in the top navigation. It is the single hub for every connection a workspace owns, and what it shows depends on the workspace's active channel:

- Unofficial API: a left sidebar of status filters (All, Connected, Disconnected, Needs re-pair, Failed) plus region filters, and a grid of paired phone cards on the right. The page title reads My devices.
- WhatsApp Cloud API: a full-width grid of connected WABA numbers with an Add WABA account button; an empty state prompts you to connect your first number. The page title reads My WABA accounts.
- Twilio: either the connect form (when nothing is connected yet) or a single account card showing the connected sender.

A small counter near the page title shows how many numbers are currently connected. Below, each channel has its own walkthrough.

## 1. Unofficial API — QR / Pairing Code

The Unofficial API links any WhatsApp number as a device, exactly like WhatsApp Web. Pairing is handled by a small bundled helper service (the Node bridge) that ships in the `node/` folder and stays connected to WhatsApp on your behalf.

### 1a. Admin: point WaDesk at the helper service

The helper service address is platform-level and is set once by the admin.

1. Start the service. From the `node/` directory run `npm install` then `node index.js`. By default it listens on the port set by `PORT` in `node/.env` (default `8888`).
2. In `node/.env`, set `APP_DOMAIN_NAME` to your WaDesk URL (e.g. `https://your-domain.com`) and set `NODE_WEBHOOK_TOKEN` to a shared secret password.
3. In WaDesk, enter the same shared secret in the matching admin setting. The two values must be identical or WaDesk rejects the service's status updates.
4. Go to Admin → Settings → System Message Setting, select the Unofficial API card, and paste the service address into Server URL (e.g. `http://localhost:8888`). Save.

> No webhook to configure. For the Unofficial API you do not need to set up any inbound webhook by hand — the helper service already knows your WaDesk URL from `APP_DOMAIN_NAME` and sends pairing and connection updates back automatically.

### 1b. Workspace: pair a number

1. On the Devices screen open the Add device flow (a QR slot on the left, a short form on the right).
2. Enter the WhatsApp number (with its country code) you want to link. Optionally add a Device label (e.g. "Sales line"); you can also override the helper service address for this one device, but normally leave it blank to use the platform default.
3. Click Generate QR. WaDesk starts a pairing session and shows the QR.
4. On your phone open WhatsApp → Settings → Linked Devices → Link a Device and scan the QR shown. If you prefer, request the 8-digit pairing code and type it into your phone instead.
5. The page checks every couple of seconds and walks through QR generated → Syncing data → Ready. Once the number connects, the device flips to Connected automatically.

### 1c. Relink & disconnect behavior

- Relink: if WhatsApp drops the link (or you unlink it from your phone's Linked Devices screen), the device shows as disconnected. Open it and pair again.
- Disconnect: disconnecting ends the session cleanly, so the next connect attempt re-pairs from scratch.
- Multiple numbers: pair more than one. WaDesk balances sends across every active device, so a banned device or a flat battery on one phone does not stall the whole queue.

> Keep the paired phone reachable. A linked device stays online when the phone is off, but the phone must open WhatsApp at least once every 14 days or WhatsApp drops the link. Use a dedicated phone for the number.

> Pros: instant, no approval, any number, free. Cons: you host the bridge, higher ban risk, no native template approval, against WhatsApp ToS for bulk marketing.

#### Field reference — Unofficial API

Value | Where to get it | Where to paste it in WaDesk
--- | --- | ---
Server URL | The address your helper service listens on (e.g. `http://localhost:8888`) | Admin → Settings → System Message Setting → Unofficial API → Server URL
Shared secret | `NODE_WEBHOOK_TOKEN` in `node/.env` | The matching admin setting in WaDesk (must be identical to the service)
WhatsApp number | The number on the phone you will scan with | Devices → Add device → WhatsApp number

## 2. WhatsApp Cloud API (Meta)

The Cloud API is Meta's official WhatsApp API. It is the right choice for high volume, native templates, catalogs and Forms. Setup has a Meta side (create an app, gather credentials) and a WaDesk side (paste them and wire the webhook). A workspace can connect multiple numbers — one card per phone number — and mark one as the primary sender.

### 2a. Meta side — step by step

1. Create or choose a Meta app. Go to developers.facebook.com/apps and create an app (type Business), or open an existing one.
2. Add the WhatsApp product. In the app dashboard, add the WhatsApp product.
3. Copy the IDs and temporary token. Open WhatsApp → API Setup. From there copy the Phone Number ID (the ID of the number, not the phone number itself), the WhatsApp Business Account (WABA) ID, and the temporary Access Token (good for 24 hours — fine for a first test, useless for production).
4. Create a System User and a permanent token. In Business Settings → Users → System Users, create a System User, assign it to your app/WABA, then Generate new token. Select your app and grant the scopes `whatsapp_business_messaging` and `whatsapp_business_management`. This permanent token never expires — use it for production.
5. Copy the App ID and App Secret. In the app dashboard go to Settings → Basic and copy the App ID and App Secret.

> Token scopes matter. A token missing `whatsapp_business_management` is rejected by WaDesk with a clear message. A 24-hour token connects but stops sending tomorrow. Always use a permanent System User token with both WhatsApp scopes for production.

### 2b. WaDesk side — admin app credentials

The platform-level Meta App credentials are entered once by the admin at Admin → Settings → System Message Setting → Business API card:

Field on screen | Value to paste
--- | ---
Meta App ID | App ID from Settings → Basic
App Secret | App Secret from Settings → Basic (hidden after save; re-paste only to change it)
Webhook verify token | Any random string you choose — you will paste the same value into Meta
Graph API version | Defaults to `v23.0`; change only after confirming compatibility
Embedded Signup Config ID (optional) | Meta Business Suite → Login Configurations. Enables the 1-click "Continue with Facebook" flow. Leave blank for manual paste only.

> The App Secret also secures inbound webhooks — WaDesk uses it to confirm each incoming Meta message is genuine and rejects anything that does not match, so forged messages cannot get in.

### 2c. WaDesk side — connect a number (per workspace)

Per-workspace credentials (the Phone Number ID, WABA ID and Access Token) are entered by each tenant on the Devices screen via Add WABA account. There are two paths:

#### Option A — Embedded Signup (Continue with Facebook)

If the admin filled in the App ID and Config ID, the button reads Continue with Facebook and opens Meta's signup dialog. You pick the WABA and phone number inside the dialog; WaDesk exchanges the returned code for a token, subscribes your WABA to webhooks, registers the number and links a catalog — no copy-pasting. For this flow the admin must also add the OAuth redirect URI `https://YOUR-DOMAIN/connect/wa-store/waba` in the Meta app under Facebook Login → Valid OAuth redirect URIs.

#### Option B — Manual paste

Otherwise (or by choosing switch to manual mode), open the manual modal and fill it from Meta Business Suite → WhatsApp Manager → API Setup:

Field | Required | Where to get it
--- | --- | ---
Phone Number ID | Yes | WhatsApp → API Setup. The ID of the number (not the phone number).
WABA ID | Yes | WhatsApp → API Setup. The WhatsApp Business Account ID.
Access Token | Yes | Your permanent System User token (starts with `EAA…`) with both WhatsApp scopes.
Business Manager ID | No | Business Settings → Business Info. Leave blank to auto-resolve.
Display label | No | A friendly name; defaults to the verified business name.

On submit, WaDesk checks with Meta to confirm the token works, pulls the number's details (verified name, quality rating, messaging limit tier), subscribes your WABA to webhooks, and saves the connection securely (credentials are stored encrypted). The first WABA in the workspace becomes the primary sender; use Set as default on any card to change that.

### 2d. Webhook configuration (Meta dashboard)

This is the step that makes inbound messages and delivery receipts flow in. In the Meta app go to WhatsApp → Configuration:

1. Callback URL: `https://YOUR-DOMAIN/webhooks/whatsapp/inbound`
2. Verify Token: the exact value you stored in WaDesk's Webhook verify token field. Meta sends a verification request; WaDesk confirms it only when the token matches.
3. Verify and save. Then under Webhook fields, Subscribe to the `messages` field (and `message_status` for delivery/read receipts). Template status updates are handled too if you enable Templates v2.
4. For WhatsApp calling (optional), set a second callback for the `calls` field at `https://YOUR-DOMAIN/webhooks/wa-calling`, using the same verify token.

> Tip: the same verify token works for both the messages webhook and the calling webhook. You only set it once in WaDesk.

#### Field reference — Cloud API

Value | Where to get it (Meta) | Where to paste it (WaDesk)
--- | --- | ---
App ID | App → Settings → Basic | Admin → System Message Setting → Business API → Meta App ID
App Secret | App → Settings → Basic | Admin → System Message Setting → Business API → App Secret
Phone Number ID | WhatsApp → API Setup | Devices → Add WABA account → Phone Number ID
WABA ID | WhatsApp → API Setup | Devices → Add WABA account → WABA ID
Access Token (permanent) | Business Settings → System Users → Generate token | Devices → Add WABA account → Access Token
Business Manager ID | Business Settings → Business Info | Devices → Add WABA account → Business Manager ID (optional)
Callback URL | You provide this to Meta | `https://YOUR-DOMAIN/webhooks/whatsapp/inbound` (Meta → WhatsApp → Configuration)
Verify Token | You choose it | Admin → Webhook verify token; paste the same value into Meta
Calling Callback URL | You provide this to Meta | `https://YOUR-DOMAIN/webhooks/wa-calling` (subscribe to `calls`)

## 3. Twilio

If your team already runs on Twilio, connect a Twilio WhatsApp sender. A workspace holds one Twilio account at a time.

### 3a. Twilio side

1. Open console.twilio.com. On the dashboard copy your Account SID (starts with `AC…`) and Auth Token.
2. Get a WhatsApp sender: either activate the WhatsApp Sandbox (Messaging → Try it out → WhatsApp; the default sandbox number is `+14155238886`) for testing, or request an approved WhatsApp sender under Messaging → Senders for production.

### 3b. WaDesk side

Admin defaults (Account SID, Auth Token, and WhatsApp number) can be set at Admin → Settings → System Message Setting → Twilio service card. Each workspace then connects on the Devices screen with the connect form:

Field | Required | Notes
--- | --- | ---
Account SID | Yes | Starts with `AC…`. Leave blank to inherit the admin default.
Auth Token | Yes | From the Twilio console. Encrypted at rest; used only to call api.twilio.com on your behalf.
From number | Yes | E.164 format. Sandbox default `+14155238886`; otherwise your paid Twilio sender.
Mode | — | Sandbox (testing) while your number is in WhatsApp Sandbox; Production once Twilio approves a paid sender.

Click Save & test. WaDesk verifies the credentials with Twilio before marking the connection live, then shows a card with the from-number, a masked SID, the connection time and Sandbox/Production mode. All broadcasts, campaigns, scheduled sends, auto-replies and Team Inbox replies on the workspace then route through Twilio.

### 3c. Inbound / status webhook (Twilio console)

Sending works as soon as you connect, but to receive replies and status updates you must point Twilio's webhooks at WaDesk:

- Inbound message webhook (and Status callback): `https://YOUR-DOMAIN/webhooks/whatsapp/inbound`
- Set it on your sender, or in Messaging Service → Integration tab. For the sandbox, set the same URL under "When a message comes in".

> WaDesk uses one endpoint for both Meta and Twilio and detects which provider sent each message automatically. Twilio messages are checked against your Auth Token to confirm they are genuine; without it WaDesk refuses the webhook.

#### Field reference — Twilio

Value | Where to get it | Where to paste it in WaDesk
--- | --- | ---
Account SID | console.twilio.com dashboard | Devices → Twilio connect form → Account SID (or the admin Twilio default)
Auth Token | console.twilio.com dashboard | Devices → Twilio connect form → Auth Token (or the admin Twilio default)
From number | Twilio sandbox or approved sender | Devices → Twilio connect form → From number (or the admin Twilio default)
Inbound / Status webhook | You provide this to Twilio | `https://YOUR-DOMAIN/webhooks/whatsapp/inbound` (Twilio sender / Messaging Service)

## Connection Status Reference

Every connection shows a live status. WaDesk simplifies each channel's signals into a small set of states:

Status | Meaning
--- | ---
Connected | Online and able to send/receive.
Pending / Needs re-pair | Awaiting a QR scan or first connection.
Disconnected | Not currently linked. Re-pair (Unofficial API) or reconnect (Cloud API / Twilio).
Failed | The connection attempt errored — check credentials, permissions, or the helper service.

- Unofficial API: the helper service reports in regularly; a device not heard from for about 90 seconds is marked disconnected so the screen matches reality.
- Cloud API: each WABA card shows Meta's quality rating and messaging-limit tier; reconnect a card with a fresh token if it expires.
- Twilio: use Reconnect / rotate to replace credentials, e.g. when changing the Auth Token or moving from Sandbox to a production sender.

## Troubleshooting

### QR will not scan / pairing never completes

- Confirm the helper service is running and reachable at the Server URL. Open that address in a browser; you should reach the service, not a connection error.
- The QR expires fast — let WaDesk regenerate it (the page refreshes every couple of seconds) rather than scanning a stale image.
- Make sure the phone has internet and you are scanning under Linked Devices → Link a Device, not a normal chat.
- If the status reads "Mismatch" or "Pair failed", disconnect (which ends the session) and pair again from scratch.

### Helper service offline / sends not going out (Unofficial API)

- Restart the service (`node index.js` in `node/`) and check its console for errors.
- Verify the shared secret matches on both sides: `NODE_WEBHOOK_TOKEN` in `node/.env` must equal the matching admin setting in WaDesk. A mismatch makes WaDesk reject every status update, so connections never update.
- Confirm `APP_DOMAIN_NAME` in `node/.env` points at your WaDesk URL so the service can reach back.
- Remember the 14-day rule: if the paired phone has not opened WhatsApp in two weeks, the link is dropped and you must re-pair.

### Webhook verification fails (Cloud API / calling)

- The Verify Token in the Meta dashboard must exactly equal WaDesk's Webhook verify token (Admin → System Message Setting). No leading or trailing spaces.
- The Callback URL must be the exact path `https://YOUR-DOMAIN/webhooks/whatsapp/inbound` (or `/webhooks/wa-calling` for calls) and must be publicly reachable over HTTPS.
- If the token field in WaDesk is empty, verification always fails — set a value first, save, then verify in Meta.

### Token expired / invalid (Cloud API)

- A 24-hour temporary token stops working the next day. Replace it with a permanent System User token and reconnect the WABA card.
- The token must carry both the `whatsapp_business_messaging` and `whatsapp_business_management` permissions; a token missing the management permission is rejected on connect with a clear message.
- If the App Secret was changed, update the admin App Secret field too, or inbound webhooks will fail their genuineness check.

### Messages not arriving (any channel)

- Cloud API: in Meta → WhatsApp → Configuration, confirm you subscribed to the `messages` field (and `message_status`). Subscribing, not just verifying, is what delivers events.
- Twilio: confirm the sender's inbound webhook points at `https://YOUR-DOMAIN/webhooks/whatsapp/inbound`. Without it you can send but not receive; make sure the Auth Token is set so messages pass their genuineness check.
- Unofficial API: ensure the device shows Connected and the helper service is running; incoming messages are delivered by the service, no manual webhook needed.
- Wrong channel: if a workspace was switched between channels, leftover devices from the old channel can appear in pickers. Reconnect on the correct channel if sends silently fail.

## Next Steps

With a channel connected, head to the Dashboard to confirm messages are flowing and read your KPIs. To understand limits and gating, see Plans & Free Trial.