# Whello CS Rotator Plugin Tutorial

## Introduction

The Whello CS Rotator is a WordPress plugin designed to manage WhatsApp customer service contacts with automatic rotation based on various logic including working hours, shifts, and staff availability. This tutorial will guide you through setting up and using the plugin effectively.

## Table of Contents

1. [Installation](#installation)
2. [Initial Setup](#initial-setup)
3. [Managing CS Staff](#managing-cs-staff)
4. [Creating Rotator Links](#creating-rotator-links)
5. [Configuring Loading Page](#configuring-loading-page)
6. [Using Shortcodes and Links](#using-shortcodes-and-links)
7. [Monitoring Performance](#monitoring-performance)
8. [Troubleshooting](#troubleshooting)

## Installation

1. Log in to your WordPress admin dashboard
2. Go to **Plugins > Add New**
3. Click the **Upload Plugin** button
4. Click **Choose File** and select the Whello CS Rotator plugin ZIP file
5. Click **Install Now** and then **Activate Plugin**

After activation, the plugin will redirect you to the setup wizard automatically.

## Initial Setup

### Setup Wizard

The setup wizard will guide you through the initial configuration of the plugin:

1. **Settings**: Configure basic settings including the rotator slug (default is "csrotator")
2. **Staff**: Add your first customer service staff member
3. **Link**: Create your first rotator link

### General Settings

If you skipped the wizard or need to modify settings later:

1. Go to **Whello CS Rotator > Settings** in your WordPress admin menu
2. Configure the following:
   - **Rotator Slug**: The URL path for your rotator pages (e.g., yourdomain.com/csrotator/link-name)
   - **Loading Message**: The message shown while connecting to a CS agent
   - **No Staff Message**: The message shown when no staff is available

## Managing CS Staff

### Adding Staff Members

1. Go to **Whello CS Rotator > CS Staff** in your WordPress admin menu
2. Click **Add New Staff**
3. Fill in the required information:
   - **First Name** and **Last Name**
   - **Email Address**
   - **WhatsApp Number** (include country code without + symbol)
   - **Employee ID** (optional)
   - **Status** (Active/Inactive)
   - **Always Online** (toggle if staff should be available 24/7)

### Setting Work Schedule

If "Always Online" is not enabled:

1. In the staff form, scroll to the **Work Schedule** section
2. For each workday:
   - Select the checkbox to enable that day
   - Set **Start Time** and **End Time** in 24-hour format
3. Click **Save** when finished

### Managing Existing Staff

1. Go to **Whello CS Rotator > CS Staff**
2. View all staff members in the list
3. Use the **Edit** or **Delete** links for each staff member
4. Toggle the **Status** switch to quickly activate or deactivate staff

## Creating Rotator Links

Rotator links are the core functionality of the plugin, directing customers to available CS agents.

### Creating a New Link

1. Go to **Whello CS Rotator > Links Rotator**
2. Click **Add New Link**
3. Configure the link settings:
   - **Link Name**: A descriptive name for internal reference
   - **Link Slug**: The URL segment (e.g., yourdomain.com/csrotator/this-slug)
   - **WhatsApp Message**: Default message that will be pre-filled in WhatsApp
   - **Status**: Active or Inactive

### Assigning Staff to Links

1. In the link form, scroll to the **Assigned CS Staff** section
2. Click **Add CS Staff**
3. Select a staff member from the dropdown
4. Set the **Workload** percentage (determines rotation priority)
5. Add multiple staff members as needed
6. Click **Save Link** when finished

### Using the {cs_name} Placeholder

In the WhatsApp Message field, you can use the `{cs_name}` placeholder which will be automatically replaced with the assigned CS agent's name when a customer is connected.

Example: "Hello, my name is {cs_name}. How can I help you today?"

## Configuring Loading Page

The loading page appears when a customer clicks a rotator link, showing a loading animation while connecting to an available CS agent.

### Customizing the Loading Page

1. Go to **Whello CS Rotator > Settings**
2. Configure:
   - **Loading Message**: Text shown during connection
   - **Loading Time**: How long to show the loading screen (in seconds)
   - **No Staff Message**: Text shown when no staff is available

## Using Shortcodes and Links

### Direct Link Method

Create direct links to your rotator links using this format:
```
https://yourdomain.com/csrotator/your-link-slug
```

You can place these links in:
- Navigation menus
- Buttons
- Call-to-action areas
- Social media profiles

### How the Rotation Works

When a customer clicks a rotator link:

1. The system checks which staff members are assigned to the link
2. It filters out staff who are:
   - Inactive
   - Not currently in their working hours (unless "Always Online" is enabled)
   - Already at their maximum workload
3. Among available staff, it selects the one with the lowest current workload
4. The customer is redirected to WhatsApp with the selected staff member's number and pre-filled message

## Monitoring Performance

The plugin tracks which staff members are assigned to which customers:

1. Go to **Whello CS Rotator > Overview**
2. View statistics on:
   - Total links
   - Total staff
   - Total leads (customer connections)
   - Distribution of leads among staff

## Troubleshooting

### No Staff Available Message

If customers see the "No staff available" message:

1. Check that you have active staff members assigned to the link
2. Verify staff working hours are correctly set
3. Ensure staff haven't reached their maximum workload

### Incorrect Staff Rotation

If staff rotation doesn't seem balanced:

1. Check the workload percentages assigned to each staff member
2. Verify that staff working hours are correctly configured
3. Check if any staff members have the "Always Online" option enabled

### Cron Job Issue

The plugin uses a WordPress cron job named 'wh_csrotator_cron_event' that is scheduled to run daily. Note that there is a known issue where 'daily' is incorrectly defined as 1 hour instead of 24 hours. This cron job is used to validate license activation and update the activation settings.

If you experience issues with license validation, you may need to manually trigger the cron job or contact support.

---

This tutorial covers the basic setup and usage of the Whello CS Rotator plugin. For more advanced features or custom configurations, please refer to the plugin documentation or contact support.