Connect WhatsApp

Purpose

Connecting WhatsApp enables you to send and receive WhatsApp messages directly in SkyLight Chat. All conversations sync to the unified inbox, AI agents can respond automatically, and you can run campaigns to your WhatsApp contacts.

Who Can Access

Prerequisites

Before connecting WhatsApp, ensure:

1. WhatsApp installed — On your mobile phone (iOS or Android)
2. Active phone number — WhatsApp account must be active
3. Internet connection — Both phone and computer need internet
4. Plan includes WhatsApp — Check Settings → Subscription for whatsapp_access
5. Permission granted — Your user has manage_whatsapp permission

Full Walkthrough

Step 1: Navigate to WhatsApp

1. Log in to your SkyLight Chat dashboard
2. Click WhatsApp in the sidebar under Channels
3. If not connected, you'll see the connection screen

Step 2: Generate QR Code

1. Click Connect WhatsApp or Generate QR Code
2. A QR code appears on screen
3. The QR code is valid for approximately 60 seconds
4. A countdown timer shows remaining time

Step 3: Open WhatsApp on Your Phone

On iPhone:

1. Open WhatsApp
2. Tap Settings (gear icon, bottom right)
3. Tap Linked Devices
4. Tap Link a Device
5. Authenticate with Face ID, Touch ID, or passcode

On Android:

1. Open WhatsApp
2. Tap Menu (three dots, top right)
3. Tap Linked Devices
4. Tap Link a Device
5. Authenticate if prompted

Step 4: Scan the QR Code

1. Point your phone's camera at the QR code on screen
2. Hold steady until the code is recognized
3. WhatsApp will show "Logging in..."

Step 5: Wait for Connection

1. The dashboard shows "Connecting..." with a spinner
2. Connection typically takes 5-15 seconds
3. Once connected, you'll see a success message
4. Your WhatsApp number appears in the settings

Step 6: Initial Sync

After connection:

1. Recent conversations begin syncing
2. Contact names are imported
3. Profile photos are downloaded
4. This process may take 1-5 minutes depending on history

Field & Control Glossary

Connection Screen

Connected State

Statuses & Badges

Connection Status

Sync Status Values

Nested Screens

QR Expired Modal

When the QR code expires:

┌─────────────────────────────────────────────────────────────────┐
│ QR Code Expired                                             [X] │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  The QR code has expired. Generate a new one to continue.       │
│                                                                  │
│                    [Generate New QR Code]                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Connection Success Modal

After successful connection:

┌─────────────────────────────────────────────────────────────────┐
│ WhatsApp Connected! ✓                                       [X] │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Your WhatsApp account +966 50 123 4567 is now connected.       │
│                                                                  │
│  Your messages will start appearing in the inbox shortly.       │
│                                                                  │
│                [Go to Inbox]  [Configure Settings]               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Disconnect Confirmation Modal

When disconnecting WhatsApp:

┌─────────────────────────────────────────────────────────────────┐
│ Disconnect WhatsApp                                         [X] │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Are you sure you want to disconnect +966 50 123 4567?          │
│                                                                  │
│  What would you like to do with your contacts?                  │
│                                                                  │
│  ○ Keep contacts in SkyLight Chat                               │
│  ○ Remove contacts imported from this channel                   │
│                                                                  │
│  ⚠️ Active campaigns using this channel will be paused.         │
│                                                                  │
│                         [Cancel]  [Disconnect]                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

How It Connects

Limits & Plan Behavior

Plan Requirements

Channel Limits

What Happens Without whatsapp_access

If your plan doesn't include WhatsApp:

1. WhatsApp menu item shows a lock icon
2. Clicking it shows an upgrade prompt
3. You cannot generate QR codes
4. Existing connections (if any) become read-only

Troubleshooting

QR Code Won't Scan

Symptoms: WhatsApp doesn't recognize the QR code

Solutions:

1. Ensure QR code hasn't expired (check timer)
2. Click Refresh QR Code to generate new one
3. Clean your phone camera lens
4. Increase screen brightness
5. Move phone closer or further from screen
6. Try in a well-lit environment

"Link a Device" Not Appearing

Symptoms: Option missing in WhatsApp settings

Solutions:

1. Update WhatsApp to latest version
2. Restart WhatsApp app
3. Restart your phone
4. Ensure WhatsApp has camera permission

Connection Stuck on "Connecting"

Symptoms: Spinner shows indefinitely after scanning

Solutions:

1. Wait up to 60 seconds — first connection can be slow
2. Check phone has stable internet connection
3. Check computer has stable internet connection
4. Try on a different network (avoid VPNs)
5. Refresh the page and try again

"Already Connected" Error

Symptoms: Error says WhatsApp is already connected

Solutions:

1. Check if another team member connected this number
2. Go to WhatsApp Settings to see existing connection
3. Click Disconnect first, then reconnect
4. If connected elsewhere, unlink from WhatsApp app first:
   • WhatsApp → Linked Devices → Select device → Log Out

Connection Drops Frequently

Symptoms: WhatsApp disconnects repeatedly

Solutions:

1. Ensure phone stays connected to internet
2. Don't force-close WhatsApp on phone
3. Disable battery optimization for WhatsApp
4. Keep phone connected to Wi-Fi when possible
5. Check Settings → Linked Devices on phone for issues

Messages Not Syncing

Symptoms: Connected but messages don't appear

Solutions:

1. Wait 1-5 minutes for initial sync
2. Click Refresh Status in WhatsApp settings
3. Send a test message from your phone
4. Check connection status badge
5. Verify global_inbox permission or conversation assignment

Error: "Campaign Running"

Symptoms: Cannot disconnect WhatsApp

Solutions:

WhatsApp cannot be disconnected while campaigns are active:

1. Go to Campaigns
2. Find campaigns using WhatsApp
3. Pause or Cancel the campaigns
4. Return to WhatsApp settings
5. Disconnect should now work

Best Practices

Before Connecting

• Dedicated number recommended: Use a business phone number, not personal
• Backup important chats: Connection won't affect existing chats, but good practice
• Inform your team: Let colleagues know you're connecting

After Connecting

• Test with a message: Send yourself a test message
• Configure settings: Set up greeting messages and auto-replies
• Enable AI (optional): Configure AI agents for automated responses
• Set up notifications: Configure how you'll be notified of messages

Maintaining Connection

• Keep WhatsApp active: Don't uninstall or log out of WhatsApp
• Monitor status: Check connection status periodically
• Update WhatsApp: Keep the app updated for compatibility

Related Articles

• WhatsApp Settings
• Unified Inbox
• AI Agents
• Channels API