Skip to main content

​
What Is the Bonus Engine?

The Bonus Engine determines whether players qualify for bonuses during a conversation. Think of it like a VIP host at a casino—it evaluates who the player is, what they’ve done, and decides what special offers they deserve. Key benefits:
  • Consistent qualification — Same rules apply to every player, every time
  • Tiered rewards — VIPs get better offers automatically
  • Seamless integration — Works with your existing AI Procedures
The Bonus Engine determines eligibility. Your AI Procedures control what happens next—whether to offer the bonus, issue it automatically, or escalate for human review.

​
End-to-End Setup

Getting bonuses working requires three things: a bonus configuration, an AI Procedure that uses it, and instructions telling the AI what to do with the qualification result.
1

Create a Bonus Configuration

Go to Settings → Bonus Engine and click Create Segment. Define:
  • Qualification rules — Who is eligible (e.g., players with positive NGR)
  • Reward tiers — What they get (e.g., VIPs get 50 spins, others get 15)
See Creating a Bonus Configuration for details.
2

Set up your AI Procedure

Create or edit an AIP that will handle bonus inquiries:
  1. Enable player authentication — Toggle on Verify Player Identity in the AIP settings. The bonus engine needs player data to evaluate eligibility.
  2. Reference the bonus action in your instructions — In the instructions editor, type @ to open the mentions dropdown. Go to the Actions tab and select Qualify for Bonus. This inserts a mention that tells the AI it can check bonus eligibility.
3

Decide what happens after qualification

The Bonus Engine only determines eligibility — it doesn’t issue bonuses automatically. You decide what happens next:
  • Build a custom integration to call your back-office and issue bonuses (see Custom Integrations)
  • Escalate to a human for manual processing
  • Send an external message to notify your team
  • Or any combination that fits your workflow
4

Write instructions for the AI

Tell the AI what to do when a player qualifies (or doesn’t). See What to Do After Qualification for examples.
5

Test in the Playground

Use the Testing Playground with real player data to verify the flow works correctly.

​
How It Works

The Bonus Engine uses a three-layer system: 
1. SEGMENTATION → "Which players does this bonus apply to?"
   Example: Only VIP players, or players in a specific tier

2. QUALIFICATION → "Does this player meet the requirements?"
   Example: Player must have deposited before and have positive NGR

3. REWARD TIERS → "What do they get?"
   Example: Gold VIPs get 50 premium spins, Silver VIPs get 25 standard spins
When all three layers pass, the engine returns the reward details to your AI Procedure.

​
Creating a Bonus Configuration

1

Navigate to Bonus Engine

Go to Settings → Bonus Engine and click Create Segment.
2

Name Your Configuration

Give it a clear name that describes the scenario, like “Deposit Bonus - First Time Players” or “VIP Loyalty Rewards”.
3

Define Segmentation Rules

Specify which players this bonus applies to. Use player attributes to target specific groups. Leave empty to evaluate all players.Example: Only VIP players
player.vipLevel != 'none'
Example: Players in a specific tier
player.tier == 'gold' OR player.tier == 'platinum'
4

Define Qualification Rules

Specify who qualifies. Players must meet ALL conditions.Example: First deposit only, with positive value
player.totalDeposits == 0
AND player.NGR > 0
5

Add Reward Tiers

Create one or more tiers—the first matching tier wins. Always add a “default” tier at the bottom as a catch-all.
6

Save and Test

Click Save, then test with real player data in the Playground before going live.

​
Reward Types

The Bonus Engine supports different reward types depending on your back-office integration:

Standard Free Spins

Basic free spins at minimum bet value. Players can use them on multiple game providers.Fields required:
  • Game Provider (BGaming, Mascot, etc.)
  • Number of spins
Player sees: “25 Free Spins (min bet) on BGaming games”

Boosted Free Spins

Premium spins with a fixed bet value, powered by pre-configured templates.Fields required:
  • Template name (from back-office)
  • Value per spin description
Player sees: “15 Free Spins at $0.50/spin with 35x wagering”

Premium Free Spins

Top-tier spins with higher bet values and lower wagering requirements.Fields required:
  • Template name (from back-office)
  • Value per spin description
Player sees: “25 Free Spins at $1.00/spin with 30x wagering”
Boosted and Premium spins use templates configured in your back-office system (like SoftSwiss DSL templates). Make sure template names match exactly—they’re case-sensitive!

​
Reward Tiers

Tiers let you give different rewards based on player attributes. They’re evaluated top to bottom—the first match wins.

​
Example Tier Structure

PriorityConditionReward
1VIP Player (player.category == 'VIP')50 Premium Free Spins
2High depositor (player.lastDeposit >= 500)30 Boosted Free Spins
3Default (always true)15 Standard Free Spins
Always include a default tier. Without one, players who pass qualification but don’t match any tier will get no reward—and you won’t know why.

​
Using “Qualify for Bonus” in Your Instructions

To check bonus eligibility in your AIP, you reference the action using the mentions system:
  1. In the instructions editor, type @
  2. A dropdown appears — go to the Actions tab
  3. Click Qualify for Bonus
  4. A mention chip is inserted into your instructions
The mention tells the AI that it can use this action. In your surrounding instructions, you describe when and how to use it. What the action does:
  1. Evaluates all your bonus configurations against the current player
  2. Returns whether they qualify and what reward they’d receive
  3. Provides the reward details (spin count, game provider, template name, etc.)
What your AIP receives:
FieldDescriptionExample
qualifiedWhether the player qualifiestrue
rewardTypeThe type of rewardstandard, boosted, or premium
spinsCountNumber of free spins25
gameProviderWhich games the spins work onBGaming, Mascot
templateNameBack-office template (for boosted/premium)15 FS Boosted Pack
valuePerSpinDescriptionBet value per spin (for boosted/premium)$0.50 AUD/spin
The Bonus Engine only determines eligibility. It doesn’t automatically issue bonuses. Your AIP instructions (or custom integrations) decide what happens with this data.

​
What to Do After Qualification

The Bonus Engine tells you IF a player qualifies and WHAT they’d receive. What happens next is up to you. Here are the common patterns:

​
Option A: Build a Custom Integration

Create a custom integration that calls your back-office API to issue bonuses automatically. 
If the player qualifies:
- Use your custom "Issue Bonus" tool to grant the reward
- Pass the reward data (spinsCount, templateName, etc.) to the tool
- Confirm: "Done! Your free spins have been added."

​
Option B: Escalate to a Human

Let a human agent handle the actual issuance. 
If the player qualifies:
- Create an internal note with the reward details
- @Transfer to Live Agent for manual processing

Internal note: "Player qualifies for 25 Premium Free Spins via
template '15 FS Premium Pack'. Please issue manually."

​
Option C: Send an External Message

Notify your back-office team via webhook or email. 
If the player qualifies:
- Use @send_external_message to notify the bonus team
- Tell the player: "I've submitted your bonus request.
  You'll see it in your account shortly."

​
Option D: Just Inform the Player

Sometimes you just want to tell them what they’re eligible for. 
If the player qualifies:
- Tell them the good news and what they'd receive
- Direct them to claim it through your normal process

"Great news! You're eligible for 25 Free Spins on BGaming games.
You can claim this bonus in the Promotions section of your account."

​
Complete AIP Example

Here’s a full example. Note that @Qualify for Bonus and @Transfer to Live Agent would be mention chips inserted via the @ dropdown — not typed as plain text: 
When a player asks about bonuses, promotions, or free spins:

1. First, verify the player's identity
2. Use @Qualify for Bonus to check if they're eligible
3. Based on the result:

If they qualify:
- Tell them the good news with the reward details
- Ask if they'd like it added to their account
- If yes, use your bonus tool to issue it
- Confirm it's been added

If they don't qualify:
- Be polite: "I checked your account, and you're not currently
  eligible for this bonus."
- Don't reveal the specific qualification criteria
- Offer to help with something else

If there's an error:
- Apologize for the inconvenience
- Use @Transfer to Live Agent with an internal note
The @mentions in the example above would appear as styled chips in the actual editor, not as plain text. You insert them by typing @ and selecting from the dropdown.

​
Qualification Rules

Rules compare player data against expected values. You can combine multiple conditions with AND/OR logic.

​
Available Operators

OperatorUse ForExample
==Exact matchplayer.vipLevel == 'gold'
!=Exclusionplayer.status != 'banned'
> >=Minimum thresholdplayer.totalDeposits >= 100
< <=Maximum limitplayer.bonusRate <= 30
containsArray has valueplayer.tags contains 'loyal'
is_inValue in listplayer.status is_in ['active', 'verified']
contains any ofArray has ANY of multiple valuesplayer.tags contains any of ['vip', 'whale']
contains all ofArray has ALL of multiple valuesplayer.badges contains all of ['verified', 'depositor']
does not contain any ofArray has NONE of multiple valuesplayer.restrictions does not contain any of ['banned', 'abuser']

​
Tag-Based Qualification

The contains any of, contains all of, and does not contain any of operators are powerful for tag-based bonus qualification:
Qualify players who have ANY VIP-related tag:
player.tags contains any of ['vip', 'whale', 'high-roller', 'platinum']
This matches if the player has vip OR whale OR high-roller OR platinum in their tags.
Require players to have completed ALL verification steps:
player.badges contains all of ['email-verified', 'kyc-complete', 'deposit-made']
This only matches if the player has ALL three badges.
Exclude players with any abuse or restriction flags:
player.flags does not contain any of ['bonus-abuser', 'fraud-alert', 'chargeback']
This matches only if the player has NONE of these flags.

​
Data Sources

Rules can reference:
  1. Player Context data — From back-office integrations (balance, deposits, VIP level)
  2. Computed attributes — Custom calculations you’ve configured (like bonus rate or lifetime value)

​
Testing Your Configuration

Before enabling a bonus configuration:
1

Open the Playground

Go to Testing → Playground and select a test conversation.
2

Choose a test player

Select or create a player with data that should trigger your bonus.
3

Run a test conversation

Send messages that would trigger the bonus scenario (e.g., “I’d like a deposit bonus”).
4

Verify the results

Check that:
  • The right bonus configuration was selected
  • Qualification passed/failed as expected
  • The correct reward tier matched

​
Troubleshooting

IssueWhat to Check
Player doesn’t qualify when they shouldIs the ticket being evaluated? Check segmentation rules first.
Wrong reward tier matchesTiers evaluate top-to-bottom. Reorder them or adjust conditions.
”Template not found” errorTemplate names are case-sensitive. Verify it exists in your back-office.
Player data not available in rulesIs the back-office tool configured? Is authentication working?
No reward returnedDid you add a default catch-all tier?

​
Best Practices

Begin with one qualification rule and one reward tier. Add complexity only when needed.
“VIP First Deposit Loyalty Pack” is clearer than “Bonus Config 3”.
Use the Playground with actual player scenarios before going live.
Keep a reference of which back-office templates map to which reward tiers.
Always include a default tier so no qualified player leaves empty-handed.