Connect WhatsApp

Protodesk supports two ways to connect a WhatsApp number. Both produce the same experience inside the inbox — messages arrive as tickets, your agents reply, customers see them in WhatsApp.

When to use which

	Official API	QR scan
Source	Official WhatsApp Business API	Device linking via QR code
Setup	~30 min, requires WhatsApp Business account	~60 seconds, scan from your phone
Number type	Business API number (can't be used in the WhatsApp mobile app)	Your regular WhatsApp number
Rate limits	Generous, paid by conversation tier	Subject to WhatsApp's unofficial limits (ban risk if abused)
Best for	Production, high volume, compliance-sensitive	Testing, small teams, personal-scale support

Recommendation: start with QR scan to get a feel for the product. Move to the official API before you go to production at any meaningful scale.

Option A — Official WhatsApp API

Prerequisites

• A WhatsApp Business account
• A phone number not currently in use by the WhatsApp mobile app (API numbers are separate)
• A verified WhatsApp Business Platform account

Steps

1. In WhatsApp Business Manager, create a WhatsApp Business app and phone number
2. Generate a permanent access token (System User with messaging + management permissions)
3. In Protodesk: Settings → WhatsApp → "Configure WhatsApp API"
4. Paste your phone number ID, business account ID, and access token
5. Copy the webhook URL Protodesk shows (https://api.protodesk.io/api/webhooks/whatsapp) and the verify token
6. Back in WhatsApp Business Manager, register that webhook under your app, subscribe to the messages field
7. Send a test WhatsApp to your business number. It should arrive as a ticket within 2–3 seconds

Common pitfalls:

• Phone number not verified for calling/messaging — blocks inbound
• Webhook URL uses wrong domain (test vs production) — double-check
• Access token is a short-lived User token instead of a permanent System User token — rotate to System User

Option B — QR scan

1. In Protodesk: Settings → WhatsApp → "Connect with QR scan"
2. A QR code appears on screen
3. On your phone: WhatsApp → Settings → Linked Devices → Link a device
4. Scan the QR code
5. The Protodesk workspace is now a linked device. Messages to your number arrive in Protodesk and can be replied to from both Protodesk and your phone

Once connected, the session runs persistently server-side. If it disconnects (phone offline for an extended period, session invalidated by WhatsApp), we surface a "re-scan" prompt and the QR code in Settings → WhatsApp.

Important limits:

• WhatsApp's unofficial linked-device limits apply. Don't blast thousands of outbound messages — you'll get the account banned.
• If your phone is offline for a week+, the linked session may expire and require re-scan.
• Don't use QR scan for cold outreach or unsolicited messages. Inbound + replies to customers who messaged you is fine.

Outbound message templates

Official API only. WhatsApp requires pre-approved templates for any message sent outside a 24-hour window from the customer's last message. Submit templates in WhatsApp Business Manager; they typically approve within an hour.

Inside the 24-hour window, both the official API and QR scan allow free-form replies.

Media attachments

Both modes support inbound images, documents, audio, and video up to WhatsApp's 100 MB per file cap. Outbound media works the same — upload in the reply composer.

Troubleshooting

• No QR code appearing? Check Settings → WhatsApp → Logs. Often a "session expired" error; click "Reset session" to generate a fresh QR.
• Messages arriving with no ticket? Check the customer's phone number — if they're on your per-workspace block list (Settings → Customers → Blocked), we drop silently.
• Outbound replies failing (official API)? Usually template approval — check WhatsApp Business Manager. Free-form replies outside the 24-hour window always require a template.

Summary

• Official API: production-ready, more setup
• QR scan: fast, unofficial, good for testing
• You can run both simultaneously on different workspaces; not both on the same number