Skip to main content

​
Triggers

Triggers enable you to automate critical security, moderation, and routing decisions by executing actions when specific conversation events occur. Unlike AI-powered actions that require the assistant to make decisions, triggers run immediately and deterministically based on rules you define - making them perfect for blocking spam, labeling conversations, and enforcing business policies.

​
Why Triggers Matter

Without triggers, you would need to manually review every conversation for spam, policy violations, and routing requirements. Triggers provide immediate, automated protection and organization:

​
Automated Security and Moderation

Stop unwanted conversations before they consume resources or reach your AI. Triggers can instantly block messages from known spam sources, suspicious email domains, or users who have violated your policies. This protects your AI from abuse and keeps your conversation analytics clean.

​
Consistent Policy Enforcement

Your business rules should apply uniformly across all conversations. Triggers ensure that every message is evaluated against your criteria without exception. Whether you’re filtering marketplace notifications, enforcing regional restrictions, or implementing compliance requirements, triggers execute your policies reliably and instantly.

​
Proactive Organization

Label and categorize conversations automatically as they arrive. Instead of manually tagging conversations after the fact, triggers can apply labels based on user attributes, message patterns, or conversation context - enabling better filtering, reporting, and team workflows.

​
Resource Protection

By blocking spam and irrelevant messages before your AI processes them, triggers reduce computational costs and improve response times for legitimate users. They act as a first line of defense that operates before AI reasoning begins.

​
Zero-Latency Decisions

Triggers execute synchronously during conversation creation, before your AI generates a response. This means blocking and labeling decisions happen instantly, with no delay or uncertainty in the user experience.

​
How Triggers Work

Triggers follow a simple if-then model: When an event occurs and an audience matches, then execute one or more actions.

​
The Trigger Lifecycle

  1. Event occurs: A user sends a message (currently the only supported event is “User Message Received”)
  2. Audience evaluation: The trigger checks if the conversation, user, and message match your defined criteria
  3. Action execution: If the audience matches, all configured actions execute immediately
  4. Conversation proceeds: If not blocked, the conversation continues to AI processing
Triggers are evaluated in priority order (top to bottom in your trigger list). All matching triggers execute their actions - triggers do not stop processing when one matches.

​
Event Types

Currently, botBrains supports one trigger event: User Message Received - Fires when a user sends a new message to you AI agent. This event occurs before the AI processes the message, allowing you to intercept and act on messages immediately.
More trigger events will be added in future releases, including conversation created, sentiment changed, AI response generated, and escalation requested.

​
Defining Audience Criteria

Audiences determine which conversations match your trigger. You build audience rules using the same visual query builder available throughout botBrains.

​
Building Audience Rules

The audience builder lets you combine multiple conditions with AND/OR logic:
  1. Start with the root-level AND group
  2. Add individual rules based on user, conversation, channel, or time fields
  3. Nest groups within groups to create complex logic
  4. Use the NOT toggle to invert group conditions
Available fields for trigger audiences:
  • User attributes: Email, phone, timezone, labels, external IDs, platform-specific IDs
  • Channel properties: Channel type (Browser, WhatsApp, Zendesk, Slack), subdomain, team ID
  • Conversation context: Message count, created date, labels, external IDs
  • Message properties: Content, sender type, timestamp
  • Time conditions: Current date/time, hour, day of week, timezone

​
Audience Examples

Block email domain: 
user.email ends with "@marketplace.example.com"
Label non-business-hours conversations: 
current hour < 9 OR current hour >= 17
Target specific user segment: 
user.labels contains "vip"
AND
channel.type is "Zendesk"
Identify potential spam: 
user.timezone does not begin with "Europe/"
AND
user.email ends with "@gmail.com"
Audience definitions use the same field structure as Audiences, but are evaluated in real-time as messages arrive rather than as stored segments.

​
Trigger Actions

When a trigger’s audience matches, it executes one or more actions. You can combine multiple actions in a single trigger to perform complex workflows.

​
Available Actions

  • Block
  • Assign Label
  • Unassign Label
Block prevents a conversation from continuing.Use cases:
  • Stop spam conversations immediately
  • Block messages from banned email domains
  • Prevent automated bots from engaging with your AI
  • Enforce regional or channel restrictions
What happens:
  • The conversation is marked as blocked
  • No AI response is generated
  • The conversation disappears from active lists
  • Users receive no response (silent block)
Configuration:
  • Entity type: Conversation (always)
  • No additional parameters needed
Blocking is permanent and silent. Users receive no notification that their message was blocked. Use this for clear policy violations, not for conversations that might be legitimate.

​
Combining Multiple Actions

A single trigger can execute multiple actions in sequence. Common combinations: Spam handling: 
1. Assign label "spam" to user
2. Assign label "blocked-spam" to conversation
3. Block conversation
Flagging for review: 
1. Assign label "review-needed" to conversation
2. Assign label "flagged" to message
Conditional cleanup: 
1. Unassign label "trial-user" from user
2. Assign label "verified-customer" to user
Actions execute in the order you define them. If you’re both labeling and blocking, place the label actions before the block action to ensure labels are applied even if the conversation is blocked.

​
Creating Triggers

​
Using Quick Start Templates

botBrains provides pre-configured templates for common trigger scenarios. Templates automatically populate the trigger configuration with recommended settings.

Block Spam Users

Automatically block conversations from users labeled as spam

Block Marketplace Emails

Block conversations from Amazon, eBay, and PayPal email domains

Label Non-Europe Timezone

Automatically label conversations from users outside Europe for review
To use a template:
  1. Navigate to Settings > Triggers
  2. Scroll to “Quick Start Templates”
  3. Click on a template card
  4. Review and customize the pre-filled configuration
  5. Save to activate the trigger

​
Creating Custom Triggers

1

Navigate to Triggers

Go to Settings > Triggers in your project
2

Create New Trigger

Click New Trigger button in the top right
3

Name Your Trigger

Enter a descriptive name like “Block marketplace notifications” or “Label weekend conversations”
4

Configure the When Section

Select the trigger event:
  • User Message Received (currently the only option)
Define the audience:
  • Use the query builder to specify matching criteria
  • Add rules for user attributes, conversation context, or channel properties
  • Create nested groups for complex logic
5

Configure the Then Section

Add actions to execute:
  • Click “Add Action” to add additional actions
  • For each action, select the type (Block, Assign Label, Unassign Label)
  • Configure action-specific settings (entity type, label name)
  • Arrange actions in the desired execution order
6

Enable and Save

Toggle “Active” to enable the trigger, then click “Create Trigger”
New triggers are created in an inactive state by default. Enable them only after testing your audience criteria to avoid accidentally blocking legitimate conversations.

​
Managing Triggers

​
Viewing Active Triggers

The trigger list shows all configured triggers with key information:
  • Name: Your descriptive trigger name
  • Event: Which event fires the trigger
  • Action Types: Icons showing configured actions (Block, Assign Label, etc.)
  • Enabled: Toggle switch to activate/deactivate
  • Last Updated: When the trigger was last modified

​
Editing Triggers

  1. Click on any trigger row in the trigger list
  2. Modify the name, audience criteria, or actions
  3. Click “Save Changes” to update
Changes to triggers take effect immediately. If you modify a trigger that’s blocking conversations, the new criteria apply to all incoming messages instantly.

​
Enabling and Disabling

Use the toggle switch in the trigger list to activate or deactivate triggers without deleting them:
  • Enabled: Trigger evaluates every matching event and executes actions
  • Disabled: Trigger is ignored, no actions execute
When to disable triggers:
  • Testing new trigger configurations
  • Temporary policy changes
  • Investigating false positives
  • Seasonal or time-limited rules

​
Trigger Priority

Triggers execute in the order they appear in your trigger list (top to bottom). While all matching triggers run, order can matter for label-based logic: Example scenario: 
Trigger 1: If user.email ends with "@spam.com" → Assign label "spam" to user
Trigger 2: If user.labels contains "spam" → Block conversation
Trigger 1 must run before Trigger 2 for the blocking logic to work correctly.
Currently, trigger order cannot be customized in the UI. Triggers execute in the order they were created. If you need specific ordering, delete and recreate triggers in the desired sequence, or contact support for manual reordering.

​
Deleting Triggers

  1. Find the trigger in the trigger list
  2. Click the trash icon on the right side of the row
  3. Confirm deletion in the dialog
Deleting a trigger is permanent and cannot be undone. Conversations that were previously blocked or labeled by the trigger are not affected - only future evaluations stop.

​
Practical Examples

​
Example 1: Comprehensive Spam Protection

Goal: Block known spam sources and flag potential spam for review Triggers to create: Trigger 1: Block Known Spam Users 
Name: Block Known Spam Users
Event: User Message Received
Audience:
  user.labels contains "spam"
Actions:
  1. Block conversation
Trigger 2: Block Marketplace Email Domains 
Name: Block Marketplace Notifications
Event: User Message Received
Audience:
  user.email ends with "@amazon.com"
  OR user.email ends with "@ebay.com"
  OR user.email ends with "@paypal.com"
Actions:
  1. Assign label "marketplace-email" to user
  2. Block conversation
Trigger 3: Flag Suspicious Timezones 
Name: Flag Non-Local Timezone
Event: User Message Received
Audience:
  NOT (user.timezone begins with "Europe/")
  AND user.email ends with ".com"
Actions:
  1. Assign label "potential-spam" to conversation
  2. Assign label "review-timezone" to user
Workflow:
  • Trigger 1 immediately blocks repeat offenders
  • Trigger 2 blocks marketplace notifications before they waste AI resources
  • Trigger 3 labels suspicious conversations for human review without blocking

​
Example 2: VIP Customer Routing

Goal: Label and prioritize conversations from important customers Trigger configuration: 
Name: Tag VIP Customers
Event: User Message Received
Audience:
  user.labels contains "vip"
  OR user.email ends with "@enterprise-client.com"
Actions:
  1. Assign label "high-priority" to conversation
  2. Assign label "vip-customer" to conversation
Benefits:
  • Automatically categorizes VIP conversations
  • Enables filtering in conversation lists
  • Supports custom analytics and reporting
  • Allows different escalation workflows for VIP users

​
Example 3: Channel-Specific Labeling

Goal: Organize conversations by channel and route appropriately Trigger configurations: Zendesk Conversations 
Name: Label Zendesk Conversations
Event: User Message Received
Audience:
  channel.type is "Zendesk"
Actions:
  1. Assign label "source:zendesk" to conversation
  2. Assign label "support-ticket" to conversation
WhatsApp Conversations 
Name: Label WhatsApp Conversations
Event: User Message Received
Audience:
  channel.type is "WhatsApp"
Actions:
  1. Assign label "source:whatsapp" to conversation
  2. Assign label "mobile-user" to user
Usage:
  • Filter conversation lists by channel
  • Track channel performance separately
  • Apply channel-specific guidance or knowledge sources
  • Route escalations to appropriate teams

​
Example 4: After-Hours Management

Goal: Label and handle conversations outside business hours Trigger configuration: 
Name: Label After-Hours Conversations
Event: User Message Received
Audience:
  current_hour < 9
  OR current_hour >= 17
  OR current_day_of_week is "Saturday"
  OR current_day_of_week is "Sunday"
Actions:
  1. Assign label "after-hours" to conversation
Benefits:
  • Identify conversations that need follow-up messaging
  • Track support volume outside business hours
  • Enable different AI guidance for after-hours users
  • Support timezone-aware escalation policies

​
Example 5: User Lifecycle Labeling

Goal: Automatically categorize users based on conversation patterns Trigger configurations: First-Time Users 
Name: Label First-Time Users
Event: User Message Received
Audience:
  conversation.message_count = 1
Actions:
  1. Assign label "first-time-user" to user
  2. Assign label "onboarding" to conversation
Frequent Users 
Name: Label Frequent Users
Event: User Message Received
Audience:
  user.labels contains "returning-user"
  AND conversation.message_count > 5
Actions:
  1. Unassign label "returning-user" from user
  2. Assign label "frequent-user" to user
  3. Assign label "engaged" to conversation
Lifecycle tracking:
  • New users get onboarding labels
  • Returning users are identified automatically
  • Frequent users receive special recognition
  • Enables user journey analytics

​
Best Practices

​
Designing Effective Triggers

  • Start Simple
  • Test Before Enabling
  • Document Your Triggers
  • Monitor False Positives
Begin with straightforward, single-condition triggers:
  • One clear audience criterion
  • One or two actions maximum
  • Easy to understand and test
Example:
IF user.email ends with "@spam.com"
THEN block conversation
As you gain confidence, add complexity incrementally.

​
Security Considerations

Limit blocking triggers to high-confidence criteria:
  • Known spam email domains
  • Previously labeled spam users
  • Clear policy violations
  • Automated bot patterns
Use labels for uncertain situations:
  • Suspicious but not definitive patterns
  • Borderline cases requiring review
  • New moderation criteria being tested
  • Regional or timezone-based filtering
Audit permissions:
  • Only users with trigger:write permission can create/edit triggers
  • Review who has trigger access regularly
  • Use custom roles to limit trigger management to security team
  • Monitor audit logs for trigger changes
Test impact before deploying:
  • Apply new triggers to test projects first
  • Start with small audience segments
  • Use AND logic to narrow criteria
  • Gradually expand scope as confidence grows

​
Performance and Scalability

Keep audience criteria efficient:
  • Avoid overly complex nested groups
  • Use specific field conditions rather than broad text searches
  • Prefer exact matches over pattern matching when possible
  • Test trigger evaluation time on high-volume projects
Limit trigger count:
  • Combine related triggers when possible
  • Delete obsolete triggers promptly
  • Regularly review trigger list and consolidate
  • Typical projects need 5-10 triggers, not dozens
Action efficiency:
  • Multiple labels can be assigned in one trigger
  • Group related actions in single triggers
  • Avoid redundant label assignments
  • Clean up unused labels regularly

​
Organizational Workflows

Label naming conventions: 
spam               # Manually applied spam label
auto:spam          # Trigger-assigned spam label
source:zendesk     # Channel indicator
priority:high      # Routing priority
review:needed      # Action required
status:resolved    # State tracking
Coordinate with your team:
  • Share trigger documentation across teams
  • Align trigger strategy with support workflows
  • Review trigger effectiveness in team meetings
  • Gather feedback from conversation reviewers
  • Adjust triggers based on support team insights
Integration with other features:

​
Troubleshooting

​
Trigger Not Firing

Symptom: Expected conversations are not being blocked or labeled Possible causes:
  1. Trigger is disabled - Check the enabled toggle in trigger list
  2. Audience criteria too narrow - Review field names and operators
  3. Field values don’t match - Verify actual user/conversation data
  4. NOT logic inverting incorrectly - Check group NOT toggles
  5. Case sensitivity - Some text operators are case-sensitive
Debugging steps:
  1. Disable the trigger temporarily
  2. Find a test conversation that should have matched
  3. Review the user, conversation, and message fields
  4. Compare actual values to your audience criteria
  5. Test with a simpler audience rule
  6. Gradually add complexity until it works
Create a test trigger with a label action (not block) to verify audience matching without blocking real conversations.

​
Too Many False Positives

Symptom: Legitimate conversations are being blocked or mislabeled Solutions: Narrow your audience criteria: 
Before: user.email ends with ".com"
After:  user.email ends with "@marketplace.amazon.com"
Add exclusion rules: 
user.email ends with "@spam.com"
AND NOT (user.labels contains "verified")
Use multi-factor logic: 
user.timezone not begins with "Europe/"
AND user.email ends with ".tk"
AND conversation.message_count = 1
Switch from block to label: 
Change: Block conversation
To: Assign label "potential-spam" to conversation

​
Trigger Executing Unexpectedly

Symptom: Trigger is matching conversations you didn’t intend Check these common issues:
  1. OR logic too broad - OR conditions match if ANY criterion is true
  2. Root-level group behavior - Root group always uses AND with not: false
  3. JSON field access - Ensure JSON paths are correct for external attributes
  4. Date/time timezone - Current hour uses server timezone, not user timezone
  5. Empty field handling - Fields without values may match “is empty” unexpectedly
Solution: Review your audience definition carefully and test with known data. Use the audience builder’s preview feature if available.

​
Actions Not Executing in Order

Symptom: Labels are applied but blocking doesn’t work, or vice versa Explanation: All actions in a single trigger execute sequentially. If blocking appears to prevent labeling, check if you have multiple triggers with conflicting logic. Solution: Ensure all desired actions are in a single trigger and ordered correctly: 
Correct order:
1. Assign label "spam" to user
2. Assign label "blocked" to conversation
3. Block conversation

​
Can’t Delete or Edit Trigger

Symptom: UI doesn’t allow trigger modification Possible causes:
  1. Permission issue - You need trigger:write permission
  2. Browser cache - Clear cache or try incognito mode
  3. Active sessions - Sign out and back in
  4. Platform issue - Check status page or contact support
Solution: Contact your organization admin to verify your role and permissions. See Roles and Permissions for details. Now that you understand triggers, explore these related security and automation features:
  • Roles and Permissions - Control who can create and manage triggers
  • API Keys - Secure programmatic access for automation
  • Audiences - Build audience segments used in triggers
  • Actions - Configure AI-powered actions vs. trigger-based automation
  • Labels - Organize and filter conversations with custom labels
  • Conversations - Review conversations affected by triggers