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.

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.

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

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:

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:

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

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:

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

Connection Status Reference

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

• 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.