> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Connect WhatsApp accounts to ZappWay and enable your AI Employees to automatically respond to incoming messages. Manage multiple sessions with ease.

> **Important:**
> The WhatsApp integration allows you to connect one or multiple WhatsApp accounts to ZappWay, enabling your AI Employees to automatically respond to incoming messages. Each WhatsApp connection is called a "Session" and can be managed independently.

***

## 🔢 Table of Contents

1. [Overview](#1-overview)
2. [Prerequisites](#2-prerequisites)
3. [Getting Started](#3-getting-started)
4. [Available Features](#4-available-features)
5. [Common Use Cases](#5-common-use-cases)
6. [Advanced Configuration](#6-advanced-configuration)
7. [Troubleshooting](#7-troubleshooting)
8. [Best Practices](#8-best-practices)

***

## 1. Overview

### What is WhatsApp Integration?

The WhatsApp integration connects your WhatsApp Business accounts to ZappWay, allowing AI Employees to automatically handle incoming messages. Each connection is managed as an independent session with its own configuration.

### Key Features

* **Multiple Sessions**: Connect unlimited WhatsApp numbers (based on your plan)
* **QR Code Pairing**: Quick and secure connection via QR Code scanning
* **AI Employee Assignment**: Assign specific AI Employees to each session
* **Knowledge Base Integration**: Connect datastores and datasources for enhanced responses
* **Real-time Status Monitoring**: Track connection health and session activity
* **Flexible Management**: Create, connect, disconnect, and delete sessions as needed

### What is a Session?

A **Session** represents a single WhatsApp account connection. Each session:

* Has a unique identifier
* Connects to one WhatsApp number
* Has its own AI Employee assignment
* Can be independently managed (connected/disconnected/deleted)
* Maintains its own knowledge base configuration

### How It Works

```
Create Session → Generate QR Code → Scan with Phone → Connected → Configure AI → Auto-respond to Messages
```

***

## 2. Prerequisites

### Before You Begin

**Required:**

* Active ZappWay account with premium subscription
* WhatsApp installed on your mobile device
* Stable internet connection on both mobile and computer
* At least one AI Employee created in your organization

**Recommended:**

* Prepared knowledge base (datastores/datasources) for your AI
* Clear use case and workflow planned
* Test WhatsApp number for initial setup

### Checking Your Subscription

**To verify your plan and session limits:**

1. Log in to ZappWay dashboard
2. Navigate to **Settings → Billing**
3. Check your current plan tier
4. Note your session limit (e.g., 3/10 sessions used)

**Session Limits by Plan:**

| Plan       | Sessions | Best For                        |
| ---------- | -------- | ------------------------------- |
| Free       | 0        | Not available (premium feature) |
| Growth     | 2        | Small teams                     |
| Pro        | 10       | Growing businesses              |
| Business   | 50       | Mid-size companies              |
| Enterprise | 100      | Large organizations             |

***

## 3. Getting Started

### Quick Setup (5 Minutes)

Follow these steps to get your first WhatsApp session running:

#### Step 1: Access WhatsApp Integration

1. Log in to your ZappWay dashboard
2. Navigate to **Integrations → WhatsApp**
3. Or go directly to `/integrations/whatsapp`

#### Step 2: Create New Session

1. Click the **"New Session"** button
2. Fill in the session details:
   * **Session Name** (required): Descriptive name (e.g., "Support Team", "Sales Dept")
   * **Device Name** (optional, default: "ZappWay"): How it appears in WhatsApp
3. Click **"Create Session"**
4. A QR Code modal opens automatically

**Naming Tips:**

* Use clear, descriptive names: "Customer Support - EN" ✓
* Include department or purpose: "Sales - Main Office" ✓
* Avoid generic names: "Session 1", "Test" ✗

#### Step 3: Scan QR Code

1. A QR Code appears on your screen
2. Open WhatsApp on your mobile phone
3. Go to **Menu (⋮) → Linked Devices** (or Settings → Linked Devices)
4. Tap **"Link a Device"**
5. Point your camera at the QR Code on screen
6. Wait for the "Connected!" confirmation

**Important Notes:**

* QR Code expires in 60 seconds
* Have WhatsApp open before generating the code
* Ensure good screen lighting for scanning
* Click "Generate New QR Code" if expired

#### Step 4: Configure AI Employee

After successful connection, the configuration panel appears automatically:

1. **Select AI Employee:**
   * Choose from existing AI Employees in your organization
   * Or click **"+ Create New AI Employee"** to create one now

2. **Add Knowledge (Optional):**
   * Click the knowledge selector (folder icon)
   * Search and select relevant datastores or datasources
   * Multiple items can be selected

3. **Save Configuration:**
   * Click the **"Select"** button
   * Configuration saves immediately
   * AI Employee is now active for this session

#### Step 5: Start Receiving Messages

Your WhatsApp is now connected and ready!

**What Happens Next:**

* Messages sent to your WhatsApp are automatically received
* Your AI Employee processes each message
* Responses are generated using connected knowledge bases
* Replies are sent back automatically

**Testing Your Setup:**

1. Send a test message from another WhatsApp account
2. Wait 5-10 seconds for the AI response
3. Verify the response is appropriate
4. Adjust AI configuration if needed

***

## 4. Available Features

### Feature 1: Session Management

Create, view, and manage multiple WhatsApp sessions from a centralized dashboard.

**What You Can Do:**

**Create Sessions:**

* Add new WhatsApp connections
* Set custom names and device identifiers
* Generate QR codes for instant pairing

**View Sessions:**

* See all sessions at a glance
* Check connection status (Connected/Disconnected)
* Monitor last activity timestamps

**Manage Sessions:**

* Update AI Employee assignments
* Modify knowledge base connections
* Reconnect disconnected sessions
* Delete unused sessions

**Session Card Information:**

Each session displays:

* **Session Name**: Your custom identifier
* **Status Badge**: Connection state (green/yellow/blue/red)
* **Device Name**: Device identification in WhatsApp
* **Last Update**: Most recent activity timestamp
* **Action Buttons**: Available actions based on status
* **Profile Settings**: AI Employee and knowledge configuration

### Feature 2: QR Code Pairing

Secure and fast connection using WhatsApp's official QR Code pairing system.

**How It Works:**

1. **Automatic Generation:**
   * QR Code generated when you create a session
   * Or when you click "Connect" on a disconnected session

2. **60-Second Validity:**
   * Each QR Code is valid for 60 seconds
   * Countdown timer shows remaining time
   * Security measure to prevent unauthorized access

3. **Real-time Status Updates:**
   * "Pending" → Waiting for scan
   * "Pairing" → Scan detected, connecting
   * "Connected" → Successfully paired
   * "Expired" → Code timeout, regenerate needed

4. **Easy Regeneration:**
   * Click "Generate New QR Code" anytime
   * Fresh code appears immediately
   * Previous code is invalidated

**QR Code Modal Features:**

* **Visual Instructions:** Step-by-step guidance
* **Countdown Timer:** Shows time remaining
* **Status Indicator:** Real-time connection state
* **Regenerate Button:** Create new code if needed
* **Auto-configuration:** Opens AI setup on success

### Feature 3: AI Employee Assignment

Connect specialized AI Employees to handle conversations for each session.

**Why Assign AI Employees:**

Each session needs an AI Employee to:

* Process incoming messages
* Generate appropriate responses
* Access knowledge bases
* Maintain conversation context
* Apply business logic and rules

**Assignment Options:**

**Option 1: Select Existing AI Employee**

* Choose from your organization's AI Employees
* Instantly active after selection
* Can be changed anytime

**Option 2: Create New AI Employee (In-Modal)**

* Don't leave the WhatsApp flow
* Fill comprehensive creation form
* Automatically assigned after creation

**Configuration Panel:**

Located in the "Manage" modal, includes:

* **AI Employee Dropdown:** Search and select
* **Knowledge Selector:** Add datastores/datasources
* **Select Button:** Save configuration

**Creating AI Employee In-Modal:**

When you select "+ Create New AI Employee", a detailed form opens:

**1. General Settings:**

* **Name**: Display name (e.g., "Customer Support Bot")
* **Description**: Brief purpose description
* **Instructions**: Detailed behavior guidelines
* **Avatar**: Optional image/icon

**2. Tools Configuration:**

* Enable/disable available tools
* Select integrations (Forms, HTTP, Datastore Search)
* Configure tool-specific settings

**3. Model & Prompt Settings:**

* **Model Selection**: Choose AI model (GPT-4, Claude, etc.)
* **Temperature**: Control creativity (0-1)
* **System Prompt**: Advanced customization
* **Max Tokens**: Response length limit

**Best Practices for WhatsApp AI:**

```
Name: WhatsApp Support Bot

Instructions:
You are a friendly customer support assistant on WhatsApp.

Response Guidelines:
- Keep messages concise (2-3 sentences max)
- Use emojis appropriately 😊
- Be conversational and warm
- Respond in the user's language
- Break long answers into multiple messages

WhatsApp Etiquette:
- Don't send walls of text
- Use bullet points for lists
- Respond quickly
- Be patient with typos
- Ask clarifying questions when needed

Knowledge Usage:
- Search knowledge base before responding
- Cite sources when providing information
- Admit when you don't know something
```

### Feature 4: Knowledge Base Integration

Connect datastores and datasources to provide your AI with context and information.

**What is Knowledge?**

**Datastores:**

* Collections of multiple documents
* Organized by topic or category
* Examples: Help docs, FAQ database, product manuals

**Datasources:**

* Individual documents or data sources
* More focused and specific
* Examples: Single PDF, text file, webpage

**Why Add Knowledge:**

Benefits include:

* **Accuracy**: Responses based on actual documentation
* **Consistency**: All agents give the same information
* **Currency**: Update knowledge to reflect changes
* **Expertise**: AI becomes domain expert
* **Reduced Errors**: Less hallucination and mistakes

**How to Add Knowledge:**

1. Click **"Manage"** on a connected session
2. In the modal, find the **Knowledge selector** (folder icon)
3. Click to open the knowledge picker
4. Search for datastores or datasources by name
5. Select one or multiple items
6. Selected items appear as chips
7. Click **"Select"** to save

**Selector Features:**

* **Multi-select**: Choose multiple items
* **Search functionality**: Type to filter
* **Grouped by type**: Datastores and datasources separated
* **Visual feedback**: Selected items shown as colored chips
* **Remove option**: Click X on chip to remove

**Knowledge Display:**

After saving, the session card shows:

```
Profile Settings
─────────────────────────────
Session Name: Support Team
AI Employee: Customer Support Bot
Agent ID: cla1b2c3d4e5f6g7h8
Datastores: Help Docs, FAQ, Policies
Datasources: Product Manual v2.0
```

**Editing Knowledge:**

1. Click **"Manage"** on the session
2. Configuration modal opens with current selections
3. Click knowledge selector to modify
4. Add or remove items
5. Click **"Select"** to save
6. AI immediately uses updated knowledge

### Feature 5: Session Status Monitoring

Track the health and activity of all your WhatsApp sessions in real-time.

**Connection States:**

| Status           | Badge     | Meaning            | Actions Available          |
| ---------------- | --------- | ------------------ | -------------------------- |
| **Connected**    | 🟢 Green  | Active and working | Manage, Disconnect, Delete |
| **Disconnected** | 🟡 Yellow | Not connected      | Connect, Delete            |
| **Pairing**      | 🔵 Blue   | Connecting now     | Wait (automatic)           |
| **Error**        | 🔴 Red    | Connection failed  | Regenerate QR, Try Again   |

**Monitoring Features:**

**Last Update Timestamp:**

* Shows when session was last active
* Format: `MM/DD/YYYY, HH:MM AM/PM`
* Updates on any activity:
  * Message received
  * Configuration changed
  * Connection status changed

**Connection Persistence:**

* Sessions remain connected indefinitely
* No automatic timeout
* Survives platform restarts
* Only disconnects if:
  * Manually disconnected by you
  * Device removed in WhatsApp app
  * Phone offline for extended period

**Real-time Updates:**

Updates happen automatically when:

* Creating a new session
* Connecting or disconnecting
* Changing AI configuration
* Scanning QR Code
* Deleting a session

**Manual Refresh:**

* Click **"Update"** button (top-right of page)
* Refreshes all session statuses
* Useful to verify connection health
* Recommended if status seems incorrect

***

## 5. Common Use Cases

### Use Case 1: Customer Support Automation

**Scenario:** Provide 24/7 automated customer support via WhatsApp.

**Setup:**

1. **Create Session:**
   * Name: "Customer Support - 24/7"
   * Device: "Company Support"

2. **Configure AI Employee:**
   ```
   Name: Support Bot

   Instructions:
   You are a helpful customer support representative.

   Guidelines:
   - Greet customers warmly
   - Answer product questions using the knowledge base
   - Troubleshoot common issues
   - Escalate complex problems to human agents
   - Provide order status updates
   - Handle refund/return inquiries

   Tone: Friendly, patient, professional
   Response Length: 2-3 sentences
   ```

3. **Add Knowledge:**
   * Datastore: "Help Documentation"
   * Datastore: "FAQ Database"
   * Datastore: "Troubleshooting Guides"
   * Datasource: "Product Manual"
   * Datasource: "Return Policy"

**Benefits:**

* Instant responses to customer inquiries
* 24/7 availability
* Consistent, accurate information
* Reduced support team workload
* Better customer satisfaction

### Use Case 2: Lead Qualification

**Scenario:** Automatically qualify and route sales leads from WhatsApp.

**Setup:**

1. **Create Session:**
   * Name: "Sales - Lead Qualification"
   * Device: "Sales Team"

2. **Configure AI Employee:**
   ```
   Name: Lead Qualifier

   Instructions:
   You help qualify sales leads on WhatsApp.

   Process:
   1. Greet prospect warmly
   2. Ask about their business needs
   3. Inquire about budget and timeline
   4. Determine decision-making authority
   5. Score lead: Hot (9-10), Warm (6-8), Cold (1-5)
   6. Schedule demo for qualified leads

   Qualification Criteria:
   - Budget: $5,000+ monthly
   - Timeline: Within 3 months
   - Authority: Decision maker or influencer
   - Need: Clear pain point we can solve

   Tone: Professional, consultative, enthusiastic
   ```

3. **Add Knowledge:**
   * Datastore: "Product Catalog"
   * Datastore: "Pricing Information"
   * Datastore: "Case Studies"
   * Datasource: "Sales Scripts"

**Benefits:**

* Fast lead response time
* Consistent qualification process
* Better lead prioritization
* More efficient sales team
* Higher conversion rates

### Use Case 3: Appointment Scheduling

**Scenario:** Allow customers to book appointments via WhatsApp.

**Setup:**

1. **Create Session:**
   * Name: "Appointments - Booking"
   * Device: "Booking Assistant"

2. **Configure AI Employee:**
   ```
   Name: Booking Assistant

   Instructions:
   You help customers schedule appointments on WhatsApp.

   Booking Process:
   1. Ask for preferred service type
   2. Check availability in calendar
   3. Offer 3 available time slots
   4. Confirm customer's choice
   5. Collect contact information
   6. Send confirmation with details
   7. Offer to add to customer's calendar

   Services Available:
   - Consultation (30 min)
   - Standard Appointment (1 hour)
   - Extended Session (2 hours)

   Business Hours: Mon-Fri, 9 AM - 6 PM

   Tone: Helpful, efficient, friendly
   ```

3. **Add Knowledge:**
   * Datastore: "Services Catalog"
   * Datastore: "Practitioner Bios"
   * Datasource: "Booking Policies"
   * Datasource: "Cancellation Policy"

**Required Integration:**

* Connect calendar tool (Google Calendar, Calendly)
* Enable calendar checking in AI tools

**Benefits:**

* 24/7 booking availability
* Reduced no-shows (immediate confirmation)
* Less administrative work
* Better customer convenience
* Improved schedule efficiency

### Use Case 4: Order Status Updates

**Scenario:** Provide automated order tracking and status updates.

**Setup:**

1. **Create Session:**
   * Name: "Order Updates"
   * Device: "Order Tracking"

2. **Configure AI Employee:**
   ```
   Name: Order Tracker

   Instructions:
   You help customers track their orders on WhatsApp.

   Process:
   1. Ask for order number
   2. Look up order in system
   3. Provide current status
   4. Give estimated delivery date
   5. Offer to send tracking link
   6. Handle issues (delays, problems)

   Status Types:
   - Processing: Order received, being prepared
   - Shipped: On the way to customer
   - Out for Delivery: Arriving today
   - Delivered: Successfully delivered
   - Issue: Problem requiring attention

   Tone: Clear, reassuring, helpful
   ```

3. **Add Knowledge:**
   * Datastore: "Shipping Information"
   * Datastore: "Order FAQ"
   * Datasource: "Delivery Policies"

**Required Integration:**

* Connect to order management system
* Enable order lookup tool
* Link to shipping carrier APIs

**Benefits:**

* Reduced "where is my order" inquiries
* Real-time status information
* Better customer experience
* Lower support volume
* Proactive issue resolution

### Use Case 5: HR Assistant

**Scenario:** Provide employees with HR information and support.

**Setup:**

1. **Create Session:**
   * Name: "HR Assistant - Internal"
   * Device: "HR Bot"

2. **Configure AI Employee:**
   ```
   Name: HR Assistant

   Instructions:
   You help employees with HR-related questions on WhatsApp.

   Topics Covered:
   - Company policies
   - Benefits information
   - PTO and leave policies
   - Payroll questions
   - Internal procedures
   - Contact information

   Important:
   - Only share information from official documents
   - Direct sensitive issues to HR team
   - Be professional but friendly
   - Protect employee privacy

   Tone: Professional, helpful, empathetic
   ```

3. **Add Knowledge:**
   * Datastore: "Employee Handbook"
   * Datastore: "Benefits Documentation"
   * Datastore: "Company Policies"
   * Datasource: "PTO Policy 2025"
   * Datasource: "Remote Work Guidelines"

**Security Note:**

* Verify employee identity before sharing sensitive info
* Consider separate session for different regions/departments

**Benefits:**

* 24/7 access to HR information
* Reduced HR team workload
* Consistent policy communication
* Faster employee responses
* Better internal communication

***

## 6. Advanced Configuration

### Multi-Language Support

**Strategy:** Create separate sessions for different languages.

**Implementation:**

```
Session 1: "Support - English"
├─ AI Employee: "Support Bot - EN"
├─ Instructions: Respond in English
└─ Knowledge: English documentation

Session 2: "Suporte - Português"
├─ AI Employee: "Bot de Suporte - PT"
├─ Instructions: Responda em português
└─ Knowledge: Documentação em português

Session 3: "Soporte - Español"
├─ AI Employee: "Bot de Soporte - ES"
├─ Instructions: Responde en español
└─ Knowledge: Documentación en español
```

**Benefits:**

* Better language accuracy
* Culturally appropriate responses
* Specialized knowledge per language
* Easier maintenance and updates

### Business Hours vs. After Hours

**Strategy:** Different AI behavior based on time of day.

**Implementation:**

```
Session 1: "Support - Business Hours"
├─ AI Employee: "Full Support Bot"
├─ Instructions:
│  - Answer all questions
│  - Escalate to human agents when needed
│  - Full access to all tools
└─ Knowledge: Complete knowledge base

Session 2: "Support - After Hours"
├─ AI Employee: "Night Support Bot"
├─ Instructions:
│  - Answer common questions
│  - Take messages for urgent issues
│  - Set expectations for response time
│  - Provide emergency contact if critical
└─ Knowledge: FAQ and emergency procedures only
```

**Switching Method:**

* Manual: Change session at end of business day
* Automated: Use external scheduler to rotate

### Department-Specific Sessions

**Strategy:** Separate sessions for different business functions.

**Example Structure:**

```
├─ "Sales - Main"
│  ├─ Lead qualification
│  ├─ Product information
│  └─ Demo scheduling
│
├─ "Support - Technical"
│  ├─ Troubleshooting
│  ├─ Bug reporting
│  └─ Feature requests
│
├─ "Support - Billing"
│  ├─ Invoice questions
│  ├─ Payment issues
│  └─ Subscription management
│
└─ "HR - Internal"
   ├─ Benefits questions
   ├─ Policy information
   └─ Time-off requests
```

**Routing Strategy:**

* Use different WhatsApp numbers per department
* Or have main bot route to appropriate number
* Train staff on which number to share

### Knowledge Base Organization

**Best Practices:**

**Support Bot Example:**

```
Datastores:
✓ Help Documentation (general guides)
✓ FAQ Database (common questions)
✓ Troubleshooting Guides (problem-solving)
✓ Product Manuals (technical specs)

Datasources:
✓ Quick Start Guide (getting started)
✓ Video Tutorial Links (visual learning)
✓ Latest Release Notes (new features)
```

**Sales Bot Example:**

```
Datastores:
✓ Product Catalog (all products)
✓ Pricing Information (current prices)
✓ Case Studies (success stories)
✓ Competitive Analysis (vs competitors)

Datasources:
✓ Sales Scripts (conversation templates)
✓ Objection Handlers (common objections)
✓ ROI Calculator Guide (value demonstration)
```

**Knowledge Quality Tips:**

✅ **Do:**

* Keep content current and updated
* Use clear, simple language
* Organize by topic
* Include examples
* Test AI responses after updates

❌ **Don't:**

* Mix unrelated topics
* Leave outdated information
* Use overly technical jargon
* Duplicate content across sources
* Overload with too many sources

### Advanced AI Instructions

**Template for Complex Instructions:**

```
Name: [AI Employee Name]

ROLE:
You are [role description]

PRIMARY GOALS:
1. [Goal 1]
2. [Goal 2]
3. [Goal 3]

CONVERSATION FLOW:
1. [Step 1]
2. [Step 2]
3. [Step 3]

RESPONSE GUIDELINES:
- Length: [guideline]
- Tone: [guideline]
- Format: [guideline]
- Language: [guideline]

KNOWLEDGE USAGE:
- When to search: [criteria]
- How to cite: [format]
- What to do if no answer: [action]

ESCALATION RULES:
- Escalate if: [condition 1]
- Escalate if: [condition 2]
- How to escalate: [process]

SPECIAL HANDLING:
- Emergencies: [action]
- Complaints: [action]
- Sensitive topics: [action]

DO:
✓ [Desired behavior 1]
✓ [Desired behavior 2]
✓ [Desired behavior 3]

DON'T:
✗ [Behavior to avoid 1]
✗ [Behavior to avoid 2]
✗ [Behavior to avoid 3]

EXAMPLES:

Example 1:
User: [example input]
AI: [example response]

Example 2:
User: [example input]
AI: [example response]
```

***

## 7. Troubleshooting

### Issue 1: QR Code Problems

**Problem:** QR Code not appearing or loading indefinitely

**Symptoms:**

* Loading spinner shows indefinitely
* "Generating QR Code..." message persists
* Modal opens but QR Code never appears

**Solutions:**

1. **Wait patiently (10-15 seconds)**
   * Initial generation can take time
   * Server needs to create secure code

2. **Click "Generate New QR Code"**
   * Forces new code generation
   * Often resolves stuck states

3. **Refresh browser page**
   * Close modal completely
   * Refresh page (F5 or Ctrl+R)
   * Try creating session again

4. **Check internet connection**
   * Verify stable connection on computer
   * Test with other websites
   * Try different network if possible

5. **Clear browser cache**
   * Clear cache and cookies
   * Try incognito/private mode
   * Use different browser

6. **Disable browser extensions**
   * Temporarily disable ad blockers
   * Disable VPN if active
   * Try without security extensions

***

**Problem:** QR Code expired before scanning

**Symptoms:**

* "Expired" message appears
* Countdown reached zero
* Code won't scan

**Solutions:**

1. Click **"Generate New QR Code"** button
2. Have WhatsApp app open and ready before generating
3. Navigate to Linked Devices screen first
4. Then generate code and scan immediately

**Prevention:**

* Open WhatsApp first
* Go to Linked Devices screen
* Have camera ready
* Then generate QR Code

***

**Problem:** Cannot scan QR Code

**Symptoms:**

* Camera doesn't recognize code
* Scanning but not connecting
* "Invalid QR Code" error in WhatsApp

**Solutions:**

1. **Improve lighting conditions**
   * Ensure screen is well-lit
   * Avoid dark rooms
   * Turn on more lights

2. **Adjust distance and angle**
   * Move phone closer or further (15-30cm optimal)
   * Keep phone steady
   * Try different angles to avoid glare

3. **Clean camera lens**
   * Wipe phone camera with soft cloth
   * Remove any smudges or fingerprints

4. **Increase screen brightness**
   * Turn up monitor/laptop brightness
   * Reduce screen glare
   * Angle screen away from lights

5. **Try different screen**
   * Use different monitor if available
   * Try on laptop screen vs external monitor
   * Use phone or tablet to display QR Code

6. **Screenshot method**
   * Take screenshot of QR Code
   * Transfer to phone (email, cloud)
   * Open screenshot in gallery
   * Scan from photo

7. **Update WhatsApp**
   * Ensure latest version installed
   * Update from App Store/Play Store
   * Restart app after updating

***

### Issue 2: Session Connection Problems

**Problem:** Session shows "Disconnected" after being connected

**Symptoms:**

* Status changed from green to yellow
* Last update timestamp is old
* Cannot receive messages

**Possible Causes:**

* WhatsApp app uninstalled or data cleared
* Device disconnected in WhatsApp settings
* Phone was offline for extended period
* Network instability
* WhatsApp app crash or forced update

**Solutions:**

1. **Check WhatsApp app on phone**
   ```
   Steps:
   1. Open WhatsApp on mobile
   2. Go to Settings → Linked Devices
   3. Look for "ZappWay" (or your device name)
   4. Check if it shows as active
   ```

2. **Verify device in WhatsApp**
   * If device is missing → Reconnect session
   * If device shows "Last active: long time ago" → Check phone connectivity

3. **Reconnect session in ZappWay**
   ```
   Steps:
   1. Click "Connect" button on session card
   2. QR Code modal opens
   3. Scan new QR Code with phone
   4. Wait for "Connected" status
   ```

4. **Restart phone**
   * Sometimes helps restore connection
   * Ensure WhatsApp starts automatically

5. **Check network stability**
   * Ensure phone has stable internet
   * Try switching between WiFi and mobile data
   * Check if WhatsApp is working normally

6. **Update WhatsApp**
   * Install latest version
   * Check for pending updates
   * Restart app after update

**Prevention:**

* Don't manually disconnect devices in WhatsApp
* Keep WhatsApp updated
* Maintain stable internet on phone
* Don't clear WhatsApp data unnecessarily

***

### Issue 3: AI Not Responding

**Problem:** Messages arrive but AI doesn't respond

**Symptoms:**

* Messages show as read/delivered
* No response from AI
* No errors visible in dashboard

**Diagnostic Checklist:**

**1. Verify session status**

```
✓ Status badge is green ("Connected")
✓ Last update timestamp is recent
✓ Device name is correct
```

**2. Verify AI Employee assignment**

```
Steps:
1. Click "Manage" on session card
2. Check if AI Employee is selected
3. Verify AI name is displayed in footer
```

**3. Check AI Employee status**

```
Steps:
1. Go to AI Employees page
2. Find assigned AI Employee
3. Verify status is "Active" not "Inactive"
4. Check last modified date
```

**4. Test AI Employee directly**

```
Steps:
1. Open AI Employee in dashboard
2. Send test message
3. Check if response is generated
4. If works: issue is with WhatsApp integration
5. If doesn't work: issue is with AI configuration
```

**5. Check AI configuration**

```
Review:
✓ Instructions are complete
✓ Tools are enabled if needed
✓ Knowledge base is connected
✓ Model settings are appropriate
```

**6. Review browser console**

```
Steps:
1. Press F12 to open Developer Tools
2. Go to Console tab
3. Look for error messages (red text)
4. Screenshot errors for support
```

**7. Send simple test message**

```
Test:
1. From another WhatsApp account
2. Send simple message: "Hello"
3. Wait 30 seconds
4. Check for response
```

**Common Causes:**

* AI Employee not assigned → Assign AI Employee
* AI Employee inactive → Activate in AI Employees page
* Knowledge base not connected → Add datastores
* Rate limiting or quota exceeded → Check usage limits
* Network issues → Check connection stability

***

### Issue 4: Permission and Access Errors

**Problem:** "Access Denied" or cannot create sessions

**Symptoms:**

* Cannot access integrations page
* "New Session" button disabled
* Permission error messages
* Features grayed out

**Possible Causes:**

**1. No Premium Subscription**

```
Issue: Free plan doesn't include WhatsApp
Solution:
1. Go to Settings → Billing
2. Upgrade to paid plan
3. Choose plan with WhatsApp access
```

**2. User Role Restrictions**

```
Issue: Your role lacks necessary permissions
Solution:
1. Check your role in Settings → Team
2. Contact workspace admin
3. Request permission upgrade
```

**3. Session Limit Reached**

```
Issue: Already at maximum sessions for your plan
Solution:
1. Check session count at top of page
2. Delete unused sessions
3. Or upgrade to higher plan tier
```

**4. Billing Issues**

```
Issue: Payment failed or subscription lapsed
Solution:
1. Go to Settings → Billing
2. Update payment method
3. Resolve any outstanding issues
```

**5. Account Status**

```
Issue: Account suspended or restricted
Solution:
1. Check for email from ZappWay
2. Contact support for details
3. Resolve any violations
```

***

### Issue 5: Knowledge Base Not Working

**Problem:** AI doesn't use connected knowledge

**Symptoms:**

* AI gives generic answers
* Doesn't reference datastores
* Ignores uploaded documents

**Solutions:**

1. **Verify knowledge is connected**
   ```
   Steps:
   1. Click "Manage" on session
   2. Check knowledge selector
   3. Ensure datastores/datasources are selected
   4. Look for knowledge display in footer
   ```

2. **Check datastore status**
   ```
   Steps:
   1. Go to Datastores page
   2. Find connected datastores
   3. Verify status is "Ready" not "Processing"
   4. Check document count
   ```

3. **Test datastore search**
   ```
   Steps:
   1. Open datastore in dashboard
   2. Use search function
   3. Try searching for known content
   4. Verify results appear
   ```

4. **Review AI instructions**
   ```
   Check if AI is instructed to:
   ✓ Search knowledge base
   ✓ Use provided information
   ✓ Cite sources
   ```

5. **Upload test document**
   ```
   Steps:
   1. Upload simple test file
   2. Wait for processing to complete
   3. Ask AI a question about the content
   4. Verify AI uses the information
   ```

***

## 8. Best Practices

### Workflow Design

**Session Organization:**

✅ **Good:**

* Clear, descriptive session names
* One purpose per session
* Organized by department/function
* Well-documented AI configurations

❌ **Avoid:**

* Generic names like "Session 1"
* Multiple purposes in one session
* Overcomplicated setups
* Undocumented configurations

**Example Structure:**

```
├─ "Support - English"
│  └─ Customer support in English
│
├─ "Support - Português"
│  └─ Customer support in Portuguese
│
├─ "Sales - Main"
│  └─ Lead qualification and inquiries
│
└─ "HR - Internal"
   └─ Employee questions and support
```

***

### AI Employee Configuration

**Creating Effective Instructions:**

```
Name: WhatsApp Support Bot

Instructions:
You are a friendly customer support assistant on WhatsApp.

Response Guidelines:
- Keep messages concise (2-3 sentences max)
- Use emojis appropriately 😊
- Be conversational and warm
- Respond in the user's language
- Break long answers into multiple messages

WhatsApp Etiquette:
- Don't send walls of text
- Use bullet points for lists
- Respond quickly
- Be patient with typos
- Ask clarifying questions when needed

Knowledge Usage:
- Search knowledge base before responding
- Cite sources when providing information
- Admit when you don't know something
- Offer to escalate to human if needed
```

**Model Selection:**

* Use GPT-4 for complex reasoning
* Use GPT-3.5 for faster, simpler responses
* Adjust temperature for creativity (0.3-0.7 recommended)

**Tool Configuration:**

* Enable Datastore Search for knowledge-based answers
* Enable Forms for data collection
* Enable HTTP for external integrations

***

### Knowledge Base Strategy

**Organization Best Practices:**

**Support Bot Example:**

```
Datastores:
✓ Help Documentation (general guides)
✓ FAQ Database (common questions)
✓ Troubleshooting Guides (problem-solving)

Datasources:
✓ Quick Start Guide (getting started)
✓ Latest Release Notes (new features)
✓ Contact Information (escalation)
```

**Quality Guidelines:**

✅ **Do:**

* Keep content current and updated
* Use clear, simple language
* Organize by topic
* Include examples
* Test AI responses after updates
* Remove outdated information

❌ **Don't:**

* Mix unrelated topics
* Leave outdated information
* Use overly technical jargon
* Duplicate content across sources
* Overload with too many sources

***

### Security & Privacy

**Protecting Sensitive Information:**

1. **Device Security:**
   * Only scan QR Codes on trusted devices
   * Don't share session credentials
   * Disconnect unused sessions immediately
   * Use unique device names for tracking

2. **Data Privacy:**
   * Messages are processed through ZappWay servers
   * Ensure GDPR/CCPA compliance
   * Inform customers about AI handling
   * Implement data retention policies

3. **Access Control:**
   * Limit who can create/manage sessions
   * Use role-based permissions
   * Audit session access regularly
   * Remove departed team members promptly

**Compliance Checklist:**

```
✓ Privacy policy updated
✓ Customer consent obtained
✓ Data retention policy defined
✓ Security measures documented
✓ Staff trained on data handling
✓ Incident response plan ready
```

***

### Performance Optimization

**Response Time:**

1. **Knowledge Base:**
   * Keep datastores focused and relevant
   * Don't overload with unnecessary documents
   * Regularly clean up old content
   * Use appropriate file formats

2. **AI Configuration:**
   * Use simpler models for faster responses
   * Optimize instructions for clarity
   * Enable only necessary tools
   * Set appropriate token limits

3. **Connection Quality:**
   * Maintain stable internet on phone
   * Keep WhatsApp app updated
   * Don't disconnect/reconnect frequently
   * Monitor session health regularly

***

### Monitoring & Maintenance

**Daily Tasks:**

* Check session connection status
* Monitor for disconnections
* Review critical conversation flows
* Address any urgent issues

**Weekly Tasks:**

* Review AI Employee performance
* Update knowledge bases if needed
* Test conversation scenarios
* Check response quality

**Monthly Tasks:**

* Audit all active sessions
* Remove unused sessions
* Review and optimize AI configurations
* Check subscription usage vs. limits
* Update documentation
* Train team on changes

**Quarterly Tasks:**

* Major workflow review
* Update business processes
* Evaluate ROI and effectiveness
* Plan improvements
* Review security measures

***

### Testing & Quality Assurance

**Before Going Live:**

1. **Create Test Session:**
   * Use separate WhatsApp number
   * Configure identical AI setup
   * Test thoroughly

2. **Test Scenarios:**
   ```
   ✓ Common customer questions
   ✓ Edge cases and unusual requests
   ✓ Multi-language support (if applicable)
   ✓ Escalation procedures
   ✓ Error handling
   ✓ Response times
   ```

3. **Gather Feedback:**
   * Internal team testing
   * Beta users if possible
   * Monitor first conversations closely
   * Iterate based on results

**Ongoing Quality Checks:**

```
Weekly:
- Sample conversation review
- Response accuracy check
- Customer satisfaction tracking

Monthly:
- Full quality audit
- AI instruction refinement
- Knowledge base updates
```

***

## 📞 Support & Resources

### Getting Help

**ZappWay Support:**

* **Email:** [support@zappway.ai](mailto:support@zappway.ai)
* **Live Chat:** Available in dashboard
* **Response Time:** 24-48 hours

**What to Include:**

* Session ID or name
* Detailed problem description
* Screenshots of errors
* Steps to reproduce issue
* Browser and device information

**Emergency Support:**

* For critical issues affecting business operations
* Mark emails as "Urgent"
* Include impact assessment

***

### Documentation Resources

**Core Guides:**

* [AI Employee Configuration](/agent/get-started)
* [Datastore Management](/datastore/get-started)
* [API Reference](/api-reference/authentication)
* [Integrations Overview](/integrations/overview)

**Video Tutorials:**

* WhatsApp Setup Walkthrough
* AI Employee Configuration
* Knowledge Base Integration
* Troubleshooting Common Issues

**Community:**

* User forum (if available)
* Feature request board
* Community best practices
* User case studies

***

### Feedback & Feature Requests

**How to Submit:**

1. **In-App Feedback:**
   * Click feedback button in dashboard
   * Describe your suggestion
   * Include use case details

2. **Email Requests:**
   * Send to [features@zappway.ai](mailto:features@zappway.ai)
   * Explain business need
   * Provide examples

3. **Community Voting:**
   * Visit feature board
   * Vote on existing requests
   * Add comments with context

**Most Requested Features:**

* Session analytics dashboard
* Message volume tracking
* Advanced routing logic
* Multi-agent conversations
* Template message support

***

## ✅ Quick Reference

### Setup Checklist

```
Pre-Setup:
✓ Premium subscription active
✓ WhatsApp installed on phone
✓ AI Employee created
✓ Knowledge base prepared

Setup Steps:
✓ Access WhatsApp integration page
✓ Create new session
✓ Scan QR Code
✓ Assign AI Employee
✓ Add knowledge base
✓ Test with sample messages
✓ Document configuration

Post-Setup:
✓ Monitor first conversations
✓ Adjust AI instructions if needed
✓ Train team on usage
✓ Set up alerts
```

***

### Essential Shortcuts

| Action               | Location     | Quick Access         |
| -------------------- | ------------ | -------------------- |
| **Create Session**   | Main page    | "New Session" button |
| **Connect WhatsApp** | Session card | "Connect" button     |
| **Configure AI**     | Session card | "Manage" button      |
| **Disconnect**       | Session card | "Disconnect" button  |
| **Delete Session**   | Session card | X icon (top-right)   |
| **Refresh Status**   | Main page    | "Update" button      |
| **View Settings**    | Dashboard    | Settings → Billing   |

***

### Status Reference Guide

```
🟢 Connected
   → Everything working normally
   → AI responding to messages
   → No action needed

🟡 Disconnected
   → Not receiving messages
   → Click "Connect" to reconnect
   → Scan new QR Code

🔵 Pairing
   → Connection in progress
   → Wait for completion
   → Don't close modal

🔴 Error
   → Connection failed
   → Check troubleshooting guide
   → Try "Generate New QR Code"
```

***

### Common Commands

**AI Employee Instructions:**

```markdown theme={null}
WhatsApp-Specific Commands:

Response Format:
- Keep under 3 sentences
- Use line breaks for readability
- Add emojis for friendliness

Escalation:
- If question too complex: "Let me connect you with a specialist"
- If technical issue: "I'll create a ticket for our team"
- If emergency: "This requires immediate attention. Please call [number]"

Language:
- Detect user's language
- Respond in same language
- Be culturally appropriate
```

***

## 🔄 Updates & Changelog

### Version 2.0 (March 2026)

**New Features:**

* ✅ Multiple session support
* ✅ In-modal AI Employee creation
* ✅ Real-time status updates
* ✅ Enhanced knowledge base selector
* ✅ Improved session management UI
* ✅ Better error handling

**Improvements:**

* Faster QR Code generation
* More stable connections
* Better mobile compatibility
* Enhanced security measures

**Bug Fixes:**

* Fixed QR Code expiration issues
* Resolved disconnection problems
* Improved session deletion flow
* Fixed knowledge base sync issues

***

### Coming Soon

**Q2 2025:**

* 📊 Session analytics dashboard
* 📈 Message volume tracking
* 🔔 Connection status alerts
* 📱 Mobile app management
* 🤖 Multi-agent conversations

**Q3 2025:**

* 📋 Template message support
* 🔄 Advanced routing logic
* 📊 Performance metrics
* 🎯 A/B testing for AI responses
* 🔗 Webhook integrations

**Future Roadmap:**

* Voice message support
* Image recognition capabilities
* Video message handling
* Group chat support
* Broadcast message features

***

## 📊 Subscription Plans & Limits

### Session Limits by Plan

| Plan           | Sessions | Price    | Best For            |
| -------------- | -------- | -------- | ------------------- |
| **Free**       | 0        | \$0/mo   | Trial users         |
| **Starter**    | 1        | \$29/mo  | Solo entrepreneurs  |
| **Growth**     | 3        | \$79/mo  | Small teams         |
| **Pro**        | 10       | \$199/mo | Growing businesses  |
| **Business**   | 25       | \$499/mo | Mid-size companies  |
| **Enterprise** | 50+      | Custom   | Large organizations |

**Current Usage:**

* Check usage at top of integrations page
* Format: "X/Y sessions used"
* Warning appears when limit reached

**Upgrading:**

1. Click "Upgrade" button in alert
2. Or go to Settings → Billing
3. Select new plan
4. Complete payment
5. Limits update immediately

***

## 🎓 Training Resources

### For Administrators

**Setup Training:**

* Session creation and management
* QR Code connection process
* AI Employee configuration
* Knowledge base integration
* Security best practices

**Ongoing Management:**

* Monitoring session health
* Updating AI configurations
* Managing team access
* Troubleshooting issues

***

### For End Users

**Using WhatsApp Integration:**

* How customers interact
* Expected response times
* Escalation procedures
* When to use human support

**Best Practices:**

* Clear communication
* Appropriate use cases
* Privacy considerations
* Feedback collection

***

## 📋 Compliance & Legal

### Data Processing

**Information Collected:**

* WhatsApp messages sent to connected sessions
* User phone numbers
* Message timestamps
* Conversation metadata

**Data Usage:**

* Process messages through AI Employee
* Generate automated responses
* Improve service quality
* Analytics and monitoring

**Data Retention:**

* Messages stored per retention policy
* Configurable retention periods
* Deletion upon request
* Compliance with regulations

***

### Terms of Service

**User Responsibilities:**

* Comply with WhatsApp Terms of Service
* Obtain necessary customer consents
* Protect access credentials
* Report security issues promptly

**Prohibited Uses:**

* Spam or unsolicited messages
* Illegal content or activities
* Harassment or abuse
* Terms of Service violations

***

## 🌟 Success Stories

### Customer Support Automation

**Company:** Tech Startup\
**Challenge:** 24/7 support with small team\
**Solution:** WhatsApp AI automation\
**Results:**

* 80% of inquiries handled automatically
* Response time reduced from hours to seconds
* Customer satisfaction increased 35%
* Support team focuses on complex issues

***

### Lead Qualification

**Company:** B2B SaaS Company\
**Challenge:** Qualify inbound leads quickly\
**Solution:** WhatsApp lead qualification bot\
**Results:**

* 100% of leads qualified within 5 minutes
* Sales team conversion rate up 25%
* Lead response time improved 90%
* More qualified demos booked

***

## 💡 Tips & Tricks

### Pro Tips

1. **Use Templates:**
   * Create AI instruction templates
   * Reuse for similar sessions
   * Document successful patterns

2. **Test Regularly:**
   * Send test messages weekly
   * Verify AI responses
   * Check knowledge base accuracy

3. **Monitor Performance:**
   * Track response quality
   * Measure customer satisfaction
   * Iterate based on data

4. **Keep It Updated:**
   * Refresh knowledge base monthly
   * Update AI instructions quarterly
   * Remove outdated sessions

5. **Backup Configurations:**
   * Document AI settings
   * Save successful instructions
   * Keep configuration history

***

**Last Updated:** March 2026\
**Version:** 2.0\
**Platform:** ZappWay - WhatsApp Integration\
**Support:** [support@zappway.ai](mailto:support@zappway.ai)