Triggers

Triggers are the starting point of every workflow. They define when and how workflows start executing — listening for specific events and automatically running your automation when conditions are met.

Time to complete: 15 minutes

---

What Are Triggers?

A trigger is a special node that sits at the beginning of a workflow. When the trigger's conditions are met, the workflow executes automatically.

Example triggers:

• "When a new contact is created" → Send welcome email
• "When a deal moves to Negotiation" → Notify sales manager
• "When customer sends WhatsApp message" → Auto-respond
• "Every Monday at 9am" → Generate weekly report

---

Quick Reference

Trigger Types

Category	Triggers	Use Cases
Channel	User Message, WhatsApp, Slack, Voice	Chat responses, messaging automation
CRM	Database, Segment, Campaign Activity	Entity changes, membership updates
Integration	Webhook, Google Sheets	External system events
Scheduling	Scheduler (Cron/Interval/Daily/Weekly/Monthly)	Time-based automations
Marketing	Campaign Trigger	Campaign-driven workflows
Knowledge	KB Document	Knowledge base changes
Manual	Click Trigger	Manual workflows, UI buttons, testing

Common Variables

Database:  {{trigger.entity_id}}, {{trigger.operation}}, {{trigger.new_data}}
Webhook:   {{trigger.payload}}, {{trigger.headers}}, {{trigger.params}}
Scheduler: {{trigger.triggered_at}}, {{trigger.schedule_type}}
Segment:   {{trigger.contact_id}}, {{trigger.segment_id}}, {{trigger.action}}

Execution Patterns

• Click Trigger: Synchronous
• All Others: Asynchronous (background)
• Dedup Window: 60 seconds for database triggers

---

Channel Triggers

User Message Trigger

Triggers when users send messages in chat conversations.

Best for: Chatbots, AI assistants, customer support

Setting	Description
Keywords	Words that trigger the workflow
Match Type	Exact or partial keyword matching
Memory Strategy	How to include conversation context
Context Window	Max tokens/messages to include

Memory Strategies:

• recent_only - Include last N messages
• semantic_similar - Find related past messages
• conversation_aware - Context-aware selection
• compressed - Summarized conversation history

Output Variables:

{{usermessagetrigger_1.message}} - The user's message
{{usermessagetrigger_1.matched}} - Whether keywords matched
{{usermessagetrigger_1.context}} - Conversation context

WhatsApp Message Trigger

Triggers when messages arrive on WhatsApp.

Best for: WhatsApp bots, customer inquiries, order updates

Setting	Description
Sender Filter	Specific phone numbers
Keyword Filter	Keywords in message
Message Type	Text, image, video, audio, document

Output Variables:

{{whatsappmessagetrigger_1.message}} - Message content
{{whatsappmessagetrigger_1.sender}} - Sender phone number
{{whatsappmessagetrigger_1.media_url}} - Attachment URL (if any)
{{whatsappmessagetrigger_1.timestamp}} - When received

Slack Message Trigger

Triggers when messages arrive in Slack channels.

Best for: Team notifications, internal bots, channel automation

Setting	Description
Channel Filter	Specific channels to monitor
User Filter	Specific users
Keyword Filter	Keywords in message
Include Bots	Process bot messages too

Voice Inbound Trigger

Triggers on incoming phone calls.

Best for: Voice assistants, call routing, IVR systems

Setting	Description
Phone Numbers	Numbers to monitor
Business Hours	Only during specific hours
Recording	Enable call recording
Call Timeout	Max wait time before timeout

Output Variables:

{{voiceinboundtrigger_1.caller}} - Caller phone number
{{voiceinboundtrigger_1.duration}} - Call duration
{{voiceinboundtrigger_1.recording_url}} - Recording URL

Voice Message Trigger

Triggers when voice input is received from any source.

Best for: Voice-to-text processing, transcription workflows

Setting	Description
Source Filter	Phone, WebRTC, WhatsApp
Transcriber	Integration for transcription

Output Variables:

{{voicemessagetrigger_1.transcription}} - Transcribed text
{{voicemessagetrigger_1.confidence}} - Transcription confidence

---

CRM Triggers

Universal Database Trigger

Triggers when CRM records are created, updated, or deleted.

Best for: Data-driven automation, sync workflows, notifications

Supported Entities:

• Contacts
• Companies
• Deals
• Tasks
• Notes
• Deal Payments

Events:

• Contact created/updated/deleted
• Deal stage changed
• Task completed
• Custom field modified

Setting	Description
Target Table	Which entity to monitor
Operations	INSERT, UPDATE, DELETE
Filter Groups	Conditions for triggering (specific field changes, value conditions, entity types)

Output Variables:

{{universaldatabasetrigger_1.entity_id}} - Record ID
{{universaldatabasetrigger_1.entity_type}} - Entity type (contacts, deals, etc.)
{{universaldatabasetrigger_1.operation}} - INSERT, UPDATE, or DELETE
{{universaldatabasetrigger_1.new_data}} - Current record data
{{universaldatabasetrigger_1.old_data}} - Previous data (UPDATE/DELETE)
{{universaldatabasetrigger_1.changed_fields}} - What changed (UPDATE)

Example - New Contact Created:

Target Table: contacts
Operations: INSERT only
Filter: No filters (all new contacts)

Example - Deal Stage Changed:

Target Table: deals
Operations: UPDATE only
Filter: changed_fields contains "stage"

Segment Trigger

Triggers when contacts join or leave segments.

Best for: Behavioral automation, lifecycle marketing, lead nurturing

Setting	Description
Trigger On	Added, Removed, or Both
Segment Mode	Specific segments, All, or By Tags
Include Contact	Fetch full contact details
Once Per Contact	Prevent re-triggers

Output Variables:

{{segmenttrigger_1.contact_id}} - Contact ID
{{segmenttrigger_1.segment_id}} - Segment ID
{{segmenttrigger_1.segment_name}} - Segment name
{{segmenttrigger_1.action}} - "added" or "removed"
{{segmenttrigger_1.contact}} - Full contact data (if enabled)

Campaign Activity Trigger

Triggers on campaign engagement events.

Best for: Follow-up automation, re-engagement, conversion tracking

Monitored Events:

Channel	Events
Email	Sent, Delivered, Opened, Clicked, Bounced, Unsubscribed
WhatsApp	Sent, Delivered, Read, Replied, Failed
SMS	Sent, Delivered, Failed

Setting	Description
Channel	Email, WhatsApp, SMS
Activity Types	Which events to monitor
Campaign Filter	Specific campaigns
Time Window	How recent the activity

Output Variables:

{{campaignactivitytrigger_1.campaign_id}} - Campaign ID
{{campaignactivitytrigger_1.contact_id}} - Contact ID
{{campaignactivitytrigger_1.activity_type}} - Event type
{{campaignactivitytrigger_1.metadata}} - Event details

---

Integration Triggers

Webhook Trigger

Triggers when external systems send HTTP requests.

Best for: Third-party integrations, Zapier connections, API automations, form submissions

Setting	Description
Webhook	Select configured webhook
HTTP Methods	GET, POST, PUT, PATCH, DELETE

Setup:

1. Go to Settings → Webhooks
2. Create an incoming webhook
3. Copy the webhook URL
4. Configure external system to POST to that URL
5. Use webhook in your workflow trigger

Output Variables:

{{webhooktrigger_1.payload}} - Request body (JSON)
{{webhooktrigger_1.headers}} - Request headers
{{webhooktrigger_1.params}} - Query parameters
{{webhooktrigger_1.method}} - HTTP method used
{{webhooktrigger_1.webhook_id}} - Webhook identifier

Example Payload Access:

{{webhooktrigger_1.payload.customer_id}}
{{webhooktrigger_1.payload.order.items}}
{{webhooktrigger_1.headers.Authorization}}

Google Sheets Trigger

Triggers when rows are added, updated, or deleted in Google Sheets.

Best for: Spreadsheet automation, data imports, form responses

Setting	Description
Integration	Google Sheets integration
Spreadsheet URL	Link to the spreadsheet
Sheet Name	Specific sheet tab
Trigger Events	New row, Updated row, Deleted row
Poll Interval	How often to check (1-60 minutes)

Output Variables:

{{googlesheetstrigger_1.row_data}} - Row data as object
{{googlesheetstrigger_1.change_type}} - new_row, row_updated, row_deleted
{{googlesheetstrigger_1.timestamp}} - When detected

---

Scheduling Triggers

Scheduler Trigger

Triggers workflows on a schedule.

Best for: Reports, cleanup tasks, recurring processes, batch operations

Schedule Types:

Type	Description	Example
Cron	Unix cron expression	0 9 * * 1 (Monday 9am)
Interval	Every X minutes	Every 30 minutes
Daily	Specific time each day	9:00 AM on weekdays
Weekly	Specific day and time	Monday at 10:00 AM
Monthly	Specific day of month	1st of month at 8:00 AM

Configuration Options:

Setting	Description
Schedule Type	Cron, Interval, Daily, Weekly, Monthly
Timezone	Which timezone to use
Max Iterations	Limit total executions
Execution Timeout	Max run time per execution

Cron Expression Reference:

minute (0-59)
│ hour (0-23)
│ │ day of month (1-31)
│ │ │ month (1-12)
│ │ │ │ day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Examples:
0 9 * * *     = Daily at 9:00 AM
0 9 * * 1     = Every Monday at 9:00 AM
0 0 1 * *     = First of every month at midnight
*/15 * * * *  = Every 15 minutes
0 9-17 * * 1-5 = Every hour 9am-5pm, Mon-Fri

Output Variables:

{{schedulertrigger_1.triggered_at}} - Execution timestamp
{{schedulertrigger_1.schedule_type}} - Type of schedule
{{schedulertrigger_1.iteration}} - Current iteration count

---

Click Trigger

A special trigger for manual execution and button integrations.

Best for: Manual workflows, UI buttons, testing

Use cases:

• Generate reports on demand
• Process specific records
• Test workflows

Setting	Description
Trigger Name	Display name
Button Text	Button label
Button Style	Primary, Secondary, Success, Warning, Danger
Button Icon	Lucide icon name
Expected Variables	Variables the button should pass
External UUIDs	Listen to buttons from other parts of the app

How It Works:

1. Each Click Trigger gets a unique UUID
2. Frontend buttons can call this UUID with variables
3. Workflow executes with the passed variables

Output Variables:

{{clicktrigger_1.entity_id}} - Passed entity ID
{{clicktrigger_1.entity_type}} - Passed entity type
{{clicktrigger_1.trigger_source}} - Where triggered from
{{clicktrigger_1.trigger_metadata}} - Trigger metadata

---

Knowledge Base Triggers

KB Document Trigger

Triggers when knowledge base documents change.

Best for: Document processing, content updates, sync workflows

Events:

• Document added
• Document updated
• Document deleted
• Knowledge base created
• Knowledge base deleted

Setting	Description
Event Type	Which event to monitor
KB Selection	Specific knowledge base
Document Filters	Metadata conditions

Output Variables:

{{kbdocumenttrigger_1.document_id}} - Document ID
{{kbdocumenttrigger_1.content}} - Document content
{{kbdocumenttrigger_1.metadata}} - Document metadata
{{kbdocumenttrigger_1.kb_id}} - Knowledge base ID

---

Multiple Triggers

Workflows can have multiple triggers:

• Same workflow, different entry points
• All triggers share the workflow logic
• Each trigger provides its own data

---

Trigger Execution Patterns

Synchronous vs Asynchronous

Pattern	Triggers	Behavior
Synchronous	Click Trigger	Executes immediately, waits for response
Asynchronous	All others	Queued for background processing

Deduplication

To prevent rapid re-triggers:

• Database triggers have a 60-second dedup window
• Same entity + operation won't re-trigger within window
• Segment triggers can use "Once per contact" flag

Filter Evaluation

For triggers with filters (Database, Segment):

1. Event occurs
2. Trigger conditions evaluated
3. If conditions match → Workflow executes
4. If conditions don't match → Event ignored

---

Best Practices

Choosing the Right Trigger

If You Want To...	Use This Trigger
Respond to chat messages	User Message Trigger
Automate when records change	Universal Database Trigger
Follow up on campaign engagement	Campaign Activity Trigger
Process external API calls	Webhook Trigger
Run scheduled tasks	Scheduler Trigger
React to segment membership	Segment Trigger

Trigger Design Tips

✅ Use specific filters to reduce noise
✅ Test triggers with sample data first
✅ Document expected input variables
✅ Consider deduplication needs
✅ Set appropriate timeouts

❌ Don't trigger on every database change
❌ Don't forget to handle missing data
❌ Don't create infinite loops (trigger → action → trigger)

Avoiding Infinite Loops

Dangerous Pattern:

Database Trigger (on contact update)
  → Update Contact node
    → Triggers Database Trigger again!

Safe Pattern:

Database Trigger (on contact update)
  Filter: changed_fields contains "lead_score"
  → Update Contact (only update "lead_status")

Performance Considerations

Trigger	Considerations
Database	Use filters to limit executions
Scheduler	Don't run too frequently (min 1 min)
Webhook	Implement idempotency for retries
Segment	Large segments = many executions

---

Troubleshooting

Trigger Not Firing

1. Check workflow is active - Only active workflows trigger
2. Verify trigger conditions - Test with actual data
3. Review filters - Conditions may be too restrictive
4. Check entity data - Required fields might be empty
5. View execution logs - Look for errors

Trigger Firing Too Often

1. Add filters - Narrow down conditions
2. Enable deduplication - Use "Once per contact" for segments
3. Review operation types - Maybe only need INSERT, not UPDATE
4. Check for loops - Workflow output might re-trigger

Variable Not Available

1. Check trigger outputs - Use correct variable path
2. Verify data exists - Source might not have that field
3. Use default values - Handle missing data gracefully

---

Next Steps

With triggers understood, continue with:

1. Creating Your First Workflow - Build complete workflows
2. Using Conditions & Branches - Add logic
3. Testing Workflows - Debug and test

---

Related

• Workflows Overview
• Webhook API