Integration Guide

How to Build a Referral Leaderboard Bot in Slack with GrowSurf

Name: GrowSurf
Rating: 4.74 (47 reviews)
Author: GrowSurf

Create a Slack bot that posts daily referral leaderboards and program stats from GrowSurf.

Competition drives referral programs — and nothing fuels healthy competition like a public leaderboard. A Slack leaderboard bot that posts daily rankings of your top referrers creates visibility, motivates participants, and gamifies your referral program. When team members and customers see who's leading, they're more likely to step up their sharing game.

This guide covers building a Slack bot that automatically pulls referral data from GrowSurf's API, ranks participants by referral count, and posts a formatted leaderboard to a Slack channel on a daily or weekly schedule.

Integration Steps

Step 1: Set Up API Access for Both Platforms

Configure API keys and credentials for GrowSurf and Slack.

Get your GrowSurf API key from Campaign > Settings > API
Create a Slack app at api.slack.com/apps
Add an Incoming Webhook to your leaderboard channel
Store both credentials securely as environment variables

Step 2: Build the Leaderboard Data Fetcher

Create a function that pulls participant data from GrowSurf's API and ranks them by referral count.

Use GrowSurf's API endpoint: GET /v2/campaign/{campaignId}/participants
Sort participants by referralCount descending
Take the top 10 (or 20) referrers
Calculate additional stats: total referrals, average per participant, new referrals today

Step 3: Format the Leaderboard Message

Design a Slack Block Kit message that presents the leaderboard in an engaging, scannable format.

Header: "Referral Leaderboard — [Date]"
Ranked list with medals for top 3 (gold, silver, bronze emoji)
Show each referrer's name, referral count, and change from yesterday
Include summary stats at the bottom: total referrals, program size, top mover

Step 4: Schedule the Leaderboard Post

Set up a scheduled job that runs daily to post the leaderboard automatically.

Use a cron job, cloud function (AWS Lambda, Google Cloud Functions), or scheduler service
Schedule for 9 AM in your team's timezone for maximum visibility
Run the data fetcher, format the message, and POST to Slack
Add error handling and notification if the job fails

Step 5: Add Engagement Features

Make the leaderboard interactive and engaging beyond a simple list.

Add "movement arrows" showing rank changes from the previous day
Highlight "newcomers" who just appeared on the leaderboard
Include a "Streak" counter for consecutive days on the leaderboard
Add a weekly summary post with total program metrics and growth rate

Step 6: Support Slash Commands for On-Demand Stats

Create a Slack slash command that lets team members check referral stats anytime.

Register a slash command: /referrals
/referrals leaderboard — show current top 10
/referrals stats — show program summary stats
/referrals [email] — look up a specific participant's referral stats

Code Snippets

// GrowSurf Referral Leaderboard Bot for Slack
const axios = require('axios');
const cron = require('node-cron');

const GROWSURF_API = 'https://api.growsurf.com/v2';
const CAMPAIGN_ID = process.env.GROWSURF_CAMPAIGN_ID;

async function getTopReferrers(limit = 10) {
  const response = await axios.get(
    `${GROWSURF_API}/campaign/${CAMPAIGN_ID}/participants?limit=100&order=desc&orderBy=referralCount`,
    { headers: { 'Authorization': `Bearer ${process.env.GROWSURF_API_KEY}` } }
  );

  return response.data.participants
    .filter(p => p.referralCount > 0)
    .slice(0, limit);
}

function formatLeaderboard(participants) {
  const medals = ['🥇', '🥈', '🥉'];
  const today = new Date().toLocaleDateString('en-US', {
    weekday: 'long', month: 'long', day: 'numeric'
  });

  let leaderboardText = participants.map((p, i) => {
    const rank = i < 3 ? medals[i] : `${i + 1}.`;
    const name = p.firstName ? `${p.firstName} ${p.lastName || ''}` : p.email;
    return `${rank} *${name.trim()}* — ${p.referralCount} referrals`;
  }).join('\n');

  const totalReferrals = participants.reduce((sum, p) => sum + p.referralCount, 0);

  return {
    blocks: [
      {
        type: 'header',
        text: { type: 'plain_text', text: `Referral Leaderboard — ${today}` }
      },
      {
        type: 'section',
        text: { type: 'mrkdwn', text: leaderboardText }
      },
      { type: 'divider' },
      {
        type: 'context',
        elements: [{
          type: 'mrkdwn',
          text: `Total referrals: *${totalReferrals}* | Top ${participants.length} referrers shown`
        }]
      }
    ]
  };
}

// Post leaderboard daily at 9 AM
cron.schedule('0 9 * * *', async () => {
  const topReferrers = await getTopReferrers(10);
  const message = formatLeaderboard(topReferrers);
  await axios.post(process.env.SLACK_WEBHOOK_URL, message);
});

Tips

Anonymize or Consent Before Public Posting

If your referral program includes external participants (not just employees), get consent before displaying names on a public leaderboard. Use first names only or anonymize with initials. For internal programs, full names are usually fine.

Add a Weekly Awards Message

In addition to the daily leaderboard, post a weekly "awards" message every Friday that highlights: Top Referrer of the Week, Biggest Mover (most improvement), and Newcomer Award (best new participant). This creates additional recognition moments.

Cache Previous Day's Data for Trend Tracking

Store the previous day's leaderboard data so you can show rank changes (up/down arrows) and highlight movers. Use a simple JSON file or Redis cache to store yesterday's rankings and compare against today's data.

FAQ

Can the leaderboard include external referrers, not just internal team members?

Yes. GrowSurf's API returns all participants regardless of whether they're internal or external. You can filter by email domain (e.g., only show @yourcompany.com for internal leaderboards) or show everyone for public-facing programs. Use separate Slack channels for internal vs. external leaderboards.

How do I handle ties on the leaderboard?

When two participants have the same referral count, sort by who reached that count first (using their last referral date). This rewards consistency and speed. Alternatively, display tied participants at the same rank and skip the next rank number.

Can I gamify the leaderboard with points instead of just referral counts?

Yes. Create a points system in your handler: 1 point per referral, 3 points per conversion, 5 points for high-value conversions. Pull conversion data from GrowSurf's API or your CRM, calculate point totals, and rank by points instead of raw referral count. This rewards quality over quantity.

GrowSurf for Startups Program

Startups get a 50% discount

GrowSurf Deals

Get $234k+ In Software Savings

LoyaltySurf

Reward Your Customers For Their Loyalty

Startup Growth Tactics Quiz

How to Build a Referral Leaderboard Bot in Slack with GrowSurf

Integration Steps

Step 1: Set Up API Access for Both Platforms

Step 2: Build the Leaderboard Data Fetcher

Step 3: Format the Leaderboard Message

Step 4: Schedule the Leaderboard Post

Step 5: Add Engagement Features

Step 6: Support Slash Commands for On-Demand Stats

Code Snippets

Tips

Anonymize or Consent Before Public Posting

Add a Weekly Awards Message

Cache Previous Day's Data for Trend Tracking

FAQ

Can the leaderboard include external referrers, not just internal team members?

How do I handle ties on the leaderboard?

Can I gamify the leaderboard with points instead of just referral counts?

Unlock the power of word-of-mouth marketing anddeepen your bond with customers

Set up your refer a friend program with customer referral and affiliate program software that lowers your acquisition costs, increases customer loyalty, and saves you gobs of time.

Built for startups,scaled for unicorns

View GrowSurfCustomer Examples

Unlock the power of word-of-mouth marketing and
deepen your bond with customers

Built for startups,
scaled for unicorns

View GrowSurf
Customer Examples