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

# Create and Manage Leaderboards

> Set up Leaderboard campaigns in ChatbotX to boost omnichannel engagement, automate score tracking, viral referrals, and honor top players.

**Leaderboards** allow you to organize competitive gamification campaigns across multiple channels to stimulate user engagement, post comments, live stream interactions, and viral sharing in exchange for gifts or discount coupons.

This feature combines real-time automated scoring with a responsive mobile leaderboard experience, allowing customers to track their rank and compete for top positions.

![Leaderboard Tool Location](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_tool_location.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=83c187a3ee9d9e4f6ed007f14b6d9d58)

## Understanding Leaderboard Mechanics

Leaderboards in ChatbotX operate on four core principles:

| Principle | Details |
| - | - |
| **Single platform per campaign** | Each social platform identifies contacts with unique IDs. To maintain fairness and prevent identity collisions, each campaign strictly applies to one selected platform. |
| **Real-time automated scoring** | The system automatically monitors interactions and adds points in real time when the campaign is Active. When paused or ended, point calculation is locked. |
| **Opt-in activation gate** | Users must open the Leaderboard link or join through a referral link to be enrolled in the campaign before post comments are tracked and scored. |
| **Player privacy protection** | The public leaderboard displays full details for Top 1, Top 2, and Top 3. From Rank 4 onward, participant names are partially masked to protect customer privacy. |

## Managing Leaderboard Campaigns

From the left navigation bar, go to **Tools > Leaderboards** to open the central management dashboard for all campaigns.

![Leaderboard Campaign Management](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_campaign_management.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=bd141718f933d3effb649563ee0ff8ca)

### Overview Metric Cards

At the top of the page, the system displays two operational metrics:

* **Total Campaigns:** The total number of leaderboard campaigns in the workspace, including active, paused, and ended campaigns.
* **Running:** The number of campaigns currently accepting interactions and calculating points in real time.

### Filters and Campaign Table

You can search and filter campaigns using:

* **Status tabs:** Quickly filter by lifecycle stage: All, Running, Paused, and Ended.
* **Search bar and platform filter:** Search by campaign name or filter by a specific connected channel.
* **Campaign data table:** View campaign name, duration, remaining days, connected channel, total participants, today's new participants, total awarded points, and current status.

### Campaign Actions

Click the three-dot menu at the end of each row to perform actions:

* **Edit:** Adjust campaign name, rules, scoring configurations, and rewards.
* **Pause / Start:** Temporarily pause automatic scoring or reactivate the campaign.
* **View Participants:** View participant rankings, inspect score breakdowns, and adjust points manually.
* **Copy Public Link:** Copy the leaderboard page URL to share across social media or attach to posts.
* **Export:** Download the full list of participants and scores as CSV or Excel.
* **End:** Permanently close scoring, lock results, and trigger the reward distribution flow for winners.
* **Reset Scores:** Reset accumulated scores for all players back to zero when organizing a new season.

## Creating a New Leaderboard Campaign

To launch a new tournament, click **Create Leaderboard** in the top-right corner. The wizard consists of three steps:

**1. Configure Campaign Information**

In the first step, configure identity details and tournament rules.

![Leaderboard Step 1 Information](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_step_1_information.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=735fe30ef1f1fc68f2f08b5ba0a661af)

1. **Leaderboard Name:** Enter the official campaign title. This name appears on the mobile webview and inside automated flows.
2. **Cover Image (Optional):** Upload a promotional banner image with a recommended 16:9 aspect ratio (1200 x 630 px, JPG or PNG, maximum 5MB). Upload from your device or click **Open media library** to select existing assets.
3. **Rules & Rewards (Optional):** Summarize reward tiers and competition guidelines so players know their goals.
4. **Start Time and End Time:** Set the exact campaign duration down to the minute. The system displays a live countdown timer on the mobile page and freezes point calculation when time expires.
5. Click **Next** to proceed.

**2. Select Channel and Configure Scoring Rules**

Choose the target platform and configure point-earning actions.

![Leaderboard Step 2 Platform Channel](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_step_2_platform_channel.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=8eec1b80c2f6a6f3f532d55a375e256c)

#### Platform and Channel Selection

The system supports 9 independent platforms:

> [card] Messenger
>
> Earn points via Fanpage interactions, post comments, livestreams, and messaging.

> [card] Instagram
>
> Earn points via post comments, Reels, Story mentions, and direct messages.

> [card] WhatsApp
>
> Earn points via conversational messages and click-to-WhatsApp ads.

> [card] Zalo OA
>
> Earn points via following OA, scanning QR codes, and interactive messages.

> [card] Telegram
>
> Earn points via joining channels and community group discussions.

> [card] TikTok
>
> Earn points via TikTok channel interactions and video comments.

> [card] Threads
>
> Earn points via post interactions and replies on Threads.

> [card] Email SMTP
>
> Earn points by opening marketing newsletters and clicking call-to-action links.

> [card] Interactive Games
>
> Sync winning scores directly from 5 interactive gamification mini-games.

Select your connected account under **Channel** and specify the scope:

* **All posts:** Automatically listen and award points for all public posts on the channel.
* **Specific posts:** Only award points for designated posts.

> [!NOTE]
>
> The platform and channel cannot be changed once the campaign is published.

#### Scoring Rules

Enable toggles for the actions you want to reward:

![Leaderboard Step 2 Scoring Rules](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_step_2_scoring_rules.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=338fcf16b6552073c17ce8a84689b59b)

* **Post Comments:**
  * **Points:** Points earned per valid comment.
  * **Daily Limit:** Maximum times a user can earn comment points per day (leave empty for unlimited).
  * **Minimum Characters:** Minimum character count required to prevent short spam comments.
  * **Golden Hour Bonus:** Bonus points awarded to users who comment early after a post is published.
  * **Golden Hour Duration:** Time window in minutes after post publication when bonus points apply.
* **Live Stream Comments:** Points awarded per comment during live broadcasts and daily limit.
* **Keyword Messages:** Earn points when customers send messages containing preset keywords configured in the channel's Keywords tool.
* **Share & Refer Friends:** Points awarded to the referrer when a new friend clicks their unique referral link and interacts with the bot.

#### General Settings

Scroll to the bottom of the step to configure operational limits and rewards:

![Leaderboard Step 2 General Settings](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_step_2_general_settings.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=156944ae3a34ee4effbc112ddb119efe)

* **Filter by Tags:** Only permit contacts tagged with at least one designated tag to earn points.
* **Daily Action Reset Hour:** The UTC hour when daily limits reset to zero (default: 22:00 UTC).
* **Anti-Spam Interval:** Minimum interval in seconds between two point rewards for the same user (enter 0 to disable).
* **Referral Welcome Flow:** The automated flow sent to friends who click a referral link. Choose an existing flow or generate an automated template.
* **Public Link:** The URL opening the mobile leaderboard with a one-click copy button.

#### End-of-Campaign Reward Settings

Automate reward distribution for top performers:

* **Reward Flow:** Select the automated flow that delivers congratulatory messages, coupons, or redemption links.
* **Number of Winners:** Set how many top-ranking participants receive rewards (e.g., Top 3 or Top 10).
* **Auto-send when ended:** Toggle on to automatically trigger the reward flow when the campaign ends.

**3. Review and Publish**

Review your configurations before launching the tournament.

![Leaderboard Step 3 Review Publish](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_step_3_review_publish.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=83c0a6c8d6f275de5427d8cad37bca6b)

* **Left Column:** Displays campaign summary, general settings, and active scoring rules.
* **Right Column (Mobile Preview):** Renders the live mobile webview with cover banner, 3D podium for Top 1, Top 2, and Top 3, ranked list, and the pinned personal bar.
* **Save Draft:** Save configurations without opening point calculation.
* **Publish:** Activate the campaign into Running status, start real-time scoring, and begin the countdown timer.

## Mobile Leaderboard Experience

When participants open the leaderboard link on their mobile device or browser, the interface provides an engaging visual experience:

![Leaderboard Webview Experience](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_webview_experience.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=337c7a25ffc61b4e4cef27d9ba17649e)

* **Live Countdown Timer:** Displays remaining days, hours, minutes, and seconds until the tournament closes.
* **Winner Podium:** Visual podium columns highlighting Top 1 with a gold crown, Top 2 with a silver crown, avatars, names, and real-time scores.
* **Rankings List:** Displays ranks from 4th place onward with scores (names are partially masked for privacy).
* **Pinned Personal Bar:** Fixed at the bottom of the screen, showing the user's current rank, total score, and a call-to-action button to share and earn more points.

## Opt-in Enrollment and Viral Referral Gate

To ensure that leaderboards only track actual participants and avoid unconsented data collection, the system utilizes a two-way enrollment gate:

```mermaid theme={null}
graph TD
    A["User A opens Leaderboard"] --> B["Clicks share button at bottom"]
    B --> C["System generates unique referral link"]
    C --> D["User A shares link with Friend B"]
    D --> E["Friend B clicks link and interacts with Bot"]
    E --> F["System enrolls both A and B into campaign"]
    F --> G["Award referral points to User A"]
    F --> H["Enable comment scoring for both A and B"]
```

1. Participant opens the Leaderboard page and clicks the share button to obtain their unique referral link.
2. Participant sends this link to friends.
3. When Friend B clicks the link and sends an initial message to the bot, both users are enrolled into the campaign's official participant roster.
4. User A instantly receives referral bonus points.
5. From this moment on, social post comments and livestream interactions from both users are tracked and scored automatically.

## Managing Participants and Anti-Cheat Controls

To monitor contestants, click the three-dot menu on any campaign and select **View Participants**.

![Leaderboard Participants List](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_participants_list.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=e40bd7984f2791c62d9b04ffc759372b)

### Participant Table

The table provides detailed records for every player:

* **Rank:** Gold, silver, and bronze medal badges for Top 1–3, sequential numbers for remaining ranks, and a banned icon for restricted accounts.
* **Participant:** Name, avatar, and social platform ID.
* **Channel and Total Score:** Connected channel and current real-time score.
* **Interaction Breakdown:** Detailed point origins such as flow points, manual adjustments, post comments, or referral points.
* **Last Active:** Timestamp of the most recent interaction.

### Manual Adjustments and Penalties

Click the three-dot menu on any participant row to access management tools:

![Leaderboard Adjust Points Modal](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_adjust_points_modal.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=899f4d0e5170d3efd9cff9451700e2b6)

* **Adjust Points:** Opens a modal allowing you to add positive points or deduct negative points, with a mandatory reason field recorded in the audit log.
* **Ban Participant:** Disqualifies accounts caught cheating or spamming. When banned, the player's score is struck through and new points are blocked.
* **Reset to 0:** Resets an individual player's points back to zero.
* **View History:** View a chronological log of score transactions for that specific user.

![Leaderboard Score History Modal](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_score_history_modal.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=8b8415380b08c04196c15b1c574bfa57)

* **Audit Log:** Click **Audit Log** in the upper-right corner of the participants page to view an immutable campaign-wide record showing admin username, score delta, exact timestamp, affected contact, and change reason.

![Leaderboard Audit Log Modal](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_audit_log_modal.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=ed8e6452908033dc3a5d6120e36ba730)

## Integrating Leaderboards into Automated Flows

You can embed Leaderboard logic into conversational flows under **Flows** to award points for survey completion, purchase confirmations, or quiz games.

### Change Gamification Scores Action

Inside the flow builder, add **Action > Tools > Change gamification scores**:

![Leaderboard Flow Action Menu](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_flow_action_menu.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=a8c57d226da797af0687bdcec4336b49)

Configure the action in the left sidebar:

![Leaderboard Flow Change Scores Configuration](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_flow_change_scores_configuration.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=046fa4777812a21dce8aea70965d14e6)

* **Leaderboard:** Select the target campaign.
* **Operation:**
  * **Add (+):** Grant points when a user completes a desired flow step.
  * **Subtract (-):** Deduct points when redeeming gifts, cancelling orders, or violating rules.
* **Points:** Enter the numerical point value.
* **User scores:** Toggle on to apply the change to the active contact chatting with the bot.
* **Referent scores:** Toggle on to also reward bonus points to the contact who referred this user ("Also change the score of whoever referred this contact").

> [!NOTE]
>
> When a campaign is Paused or Ended, point modifications from flows are automatically blocked to maintain competitive integrity.

### Condition Card for Score Thresholds

Use Leaderboard score attributes inside **Condition** cards to branch flows, deliver tiered rewards, or unlock VIP perks:

![Leaderboard Flow Condition Scores](https://mintcdn.com/chatbotx/F2y8oTN5QD9EAJXb/images/leaderboard_flow_condition_scores.png?fit=max\&auto=format\&n=F2y8oTN5QD9EAJXb\&q=85\&s=2cf023e8b76c02109cff2bf00fa3209f)

1. In a Condition block, select **Add New Condition**.
2. Scroll to the **Gamification scores** group and select your Leaderboard campaign.
3. Choose one of five comparison operators:
   * **Is:** Score exactly equals the target value.
   * **Less than:** Score is strictly less than the target value.
   * **Less than or Equal to:** Score is less than or equal to the target value.
   * **Greater than:** Score is strictly greater than the target value.
   * **Greater than or Equal to:** Score is greater than or equal to the target value.
4. Enter the threshold value in the right input box.
5. Connect the matching branch to message blocks delivering exclusive vouchers, discount coupons, or prize instructions.

## Operational Best Practices

* **Spam Prevention:** Configure a minimum character count for post comments and set anti-spam intervals to discourage automated repetitive comments.
* **Safe Campaign Closure:** When a campaign concludes, review the participants list and audit log before automated rewards are sent. If verification is needed, pause the campaign instead of ending it immediately.
* **Time Synchronization:** Daily limits reset based on your configured UTC reset hour. Clearly communicate this reset time in campaign rules so players can plan their daily activities.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.