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 with Real Data

Use the test panel on the Bonus Engine page (click the flask icon in the top right) with a real authenticated ticket to verify qualification 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.When you click to add a condition, a searchable field picker appears with two sections:
  • Player Fields — Computed attributes configured in your workspace (e.g., VIP level, lifetime value). See Player Fields for how to set these up.
  • Tool Fields — Data returned by your back-office integrations (e.g., balance, deposit count, player tier).
Type to search for a field, then click to select it. Fields that require player authentication show a lock icon — the player must be verified before that data is available.
Only tools that return data appear in the field picker. ACTION-type tools (tools that perform an operation like issuing a bonus) are not listed here — they don’t provide data for rules to evaluate.
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 use the test panel (flask icon, top right) with a real authenticated ticket to verify your rules 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 based on their priority number—the first match wins.
Priority ordering is descending — higher number = evaluated first. Priority 10 is evaluated BEFORE priority 1. This means a broad catch-all tier with a high priority number will shadow more specific tiers below it. Put your most specific conditions at the highest priority numbers, and your default/catch-all at the lowest.

​
Example Tier Structure

PriorityConditionReward
3VIP Player (player.category == 'VIP')50 Premium Free Spins
2High depositor (player.lastDeposit >= 500)30 Boosted Free Spins
1Default (always true)15 Standard Free Spins
In this example, VIP players (priority 3) are checked first. If they don’t match, high depositors (priority 2) are checked next. Everyone else falls through to the default (priority 1).
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.

​
Brand Scoping

If your workspace has multiple brands, you can scope a bonus configuration to apply only to players from a specific brand. This is useful for multi-brand operators who offer different bonus programs per brand — for example, a welcome bonus on one brand and a loyalty program on another.Leave the brand field empty to apply the configuration to all brands in the workspace.

​
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: The response always includes qualified (true/false) and rewardType. Other fields depend on the reward type:
Reward TypeFields You’ll See
StandardspinsCount, game, gameProvider, wager
BoostedtemplateName, valuePerSpinDescription
PremiumtemplateName, valuePerSpinDescription
Cash Amount / Free Spinsamount, amountType, name, description, wager
All types may also include comment if one was configured.
Boosted and Premium rewards don’t have an amount field. Don’t write AIP instructions that check amount for all reward types — template-based rewards use templateName instead. If your instructions say “if amount is 0 then deny”, it will incorrectly deny players with Boosted/Premium rewards.
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."
SoftSwiss workspaces: Two canonical issuance tools are available through Connect:
  • Issue Free Spins (/issue-freespins) — for Standard rewards (basic free spins at minimum bet)
  • Issue DSL (/issue-dsl) — for Boosted and Premium rewards (template-based spins)
Template names in the reward tier must match exactly what’s configured in SoftSwiss — they’re case-sensitive. See Custom Integrations for setting up the issuance tool.

​
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. All conditions within a rule set are combined with AND logic — every condition must pass. See Condition Logic below for how to achieve OR behavior.

​
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)
Simple (manually-set) custom player fields are not currently available in the bonus rule builder. Only computed attributes and tool fields from back-office integrations can be used in segmentation, qualification, and tier conditions.If you need to use a static value in your rules, create a computed field that returns it, or use a back-office tool that provides the data. See Player Fields for how to configure computed attributes.

​
Condition Logic

Within each section (segmentation, qualification, and tier conditions), all conditions are combined with AND logic — every condition must be true for the section to pass. There is no OR toggle within a single rule set. If you need OR logic, create separate bonus configurations (segments) with different priority levels. For example, instead of “VIP OR high depositor” in one segment, create two segments — one targeting VIPs and another targeting high depositors.

​
Testing Your Configuration

Before enabling a bonus configuration, use the built-in test panel on the Bonus Engine page itself:
1

Open the Test Panel

On the Settings → Bonus Engine page, click the flask/test icon in the top right corner to open the test panel.
2

Select an Authenticated Ticket

Choose an existing ticket where the player has already been authenticated. The test panel needs real player data to evaluate your rules.
3

Run the Test

The panel evaluates the selected player against your bonus configuration and shows:
  • Whether the player qualifies (pass/fail)
  • Which reward tier matched
  • The full reward details (spin count, template, etc.)
4

Review the Rule Trace

After evaluation, the test panel shows a rule trace tree below the results. This shows exactly which rules passed or failed at each stage (classification, qualification, reward tier) — including the resolved values, operators, and comparison values for each condition.
5

Generate an AI Explanation

Click Generate in the AI Explanation section to get a plain-English summary of the evaluation. Choose between:
  • CSM-friendly — Simple language explaining why the player did or didn’t qualify
  • Engineering — Detailed view with field paths, resolved values, and compute expressions
The test panel requires a real authenticated ticket — you cannot mock player data yet. To test different player profiles, you’ll need tickets from players that represent different segments.

​
Bonus Explain (Ticket-Level Debugging)

When investigating why a specific player qualified (or didn’t), use the Explain Bonus feature from the ticket inbox:
1

Open the Ticket

Navigate to the ticket conversation in the inbox.
2

Open Explain

Click the QA dropdown button in the ticket header, then select Explain Bonus.
3

Review the Evaluation

The explain panel shows:
  • Context — Ticket metadata, player ID, brand, authentication status
  • Classification — Which bonus config matched (with expandable rule trace)
  • Qualification — Whether the player qualified (with rule-by-rule breakdown)
  • Reward Tier — Which tier matched and what rewards were calculated
  • Player Context — All tool responses and computed attributes used
4

Toggle Cached vs Fresh

  • Cached shows data as it was at evaluation time
  • Fresh re-invokes tools and re-evaluates with current player data (without affecting the ticket)
5

Generate AI Explanation

Click Generate to get a narrative summary of the evaluation in plain English.
The Explain panel is useful when a player reports they didn’t receive a bonus they expected. You can see exactly which rule failed and what the player’s data looked like at the time.

​
Restoring Deleted Configurations

If you accidentally delete a bonus configuration, you can restore it from the Archived tab.
1

Go to the Archived tab

Navigate to Settings > AI Bonus Engine and click the Archived tab.
2

Find the deleted configuration

Archived configurations are listed with their name and the date they were deleted.
3

Click Restore

Click Restore next to the configuration you want to bring back. A confirmation dialog will appear.
4

Confirm the restore

The configuration and its associated rules will be restored to the Setup tab.
When a configuration is restored, only the rules and reward tiers that were deleted at the same time as the configuration are brought back. If you individually removed reward tiers before deleting the entire configuration, those tiers will remain archived.

​
Troubleshooting

IssueWhat to Check
Player qualifies but AI denies themCheck your AIP instructions. If they check amount for all reward types, Boosted/Premium rewards will be incorrectly denied — use templateName instead.
Player doesn’t qualify when they shouldIs the ticket being evaluated? Check segmentation rules first.
Wrong reward tier matchesTiers evaluate by descending priority (highest number first). A broad tier with a high priority number may shadow more specific ones. Adjust priority numbers or 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 test panel on the Bonus Engine page with real authenticated tickets before going live. Test different player profiles to verify each segment and tier works as expected.
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.