Creating Campaigns

​

Campaign Creation Process

​

Step 1: Basic Information

​

Campaign Name

• Displayed in campaign list, statistics, and audit logs
• Used for filtering and searching
• Best practice: Use descriptive names like “Welcome Sequence - Q1 2024”

​

Description

• Visible to team members in organization mode
• Useful for explaining campaign goals and strategy
• Not used in processing logic

​

Telegram Account

• Must have at least one connected account
• Account must be healthy and connected
• Campaign cannot send without valid account

• Dropdown shows all available accounts
• Account health status displayed
• Unhealthy accounts cannot be selected

​

Step 2: Flow Builder

​

Start Node

• Campaign starts as soon as it’s launched
• All executions begin processing immediately
• next_execution_at set to now()

• Campaign starts at specific date/time
• Requires scheduled_start_at (date + time)
• Requires timezone (e.g., “America/Sao_Paulo”)
• Worker checks scheduled campaigns every 30 seconds
• Automatically transitions to active when time reached

• Scheduled time stored in UTC in database
• Displayed in selected timezone in UI
• Worker converts UTC to campaign timezone for comparison
• Ensures campaigns start at correct local time

​

Node Types

​

SEND_MESSAGE Node

• Plain text message
• Supports dynamic tags and spintax
• Optional media URL (image, video, document)

1. Spintax processed first (variations resolved deterministically)
2. Tags replaced with actual values (with fallbacks)
3. Rate limiting checked
4. Message sent via Telegram API
5. Execution log created

• {firstName}, {lastName}, {username}, {phoneNumber}, {groupName}
• {cf-fieldName} for custom fields
• {tag|fallback} for fallback values

• {option1|option2|option3} for message variations
• Same lead always gets same variation (deterministic)
• Supports nested spintax

​

WAIT Node

• Specify days, hours, minutes
• Execution status: waiting
• next_execution_at calculated: now() + duration
• Worker resumes execution when time reached

• Waits for lead to reply
• Configurable timeout (days/hours/minutes)
• Execution status: waiting
• If response detected: execution continues immediately
• If timeout reached: execution continues to next node
• If no timeout: waits indefinitely

​

CONDITION Node

• Response check: Did lead reply?
• Variable check: Does variable match value?
• Custom condition: Evaluate expression

• Edges define paths: condition: "yes" or condition: "no"
• Next node determined by condition result
• If no matching edge: execution stops (error)

• Source: Condition node ID
• Target: Next node ID
• Condition: "yes" or "no" (or custom value)

​

END Node

• Execution status: completed
• completed_at timestamp set
• Campaign checks if all executions done
• If all done: campaign status → completed

​

Adding Nodes

1. Click ”+” button or node type icon
2. Node added to flow canvas
3. Auto-connected to previous node (if sequential)
4. Configure node properties in sidebar

• Each node type has specific properties
• SEND_MESSAGE: message text, media URL
• WAIT: duration or response timeout
• CONDITION: condition expression
• Properties saved in node data field

​

Connecting Nodes

• Nodes processed in array order by default
• Edges created automatically for sequential flow
• Manual edges only needed for condition branches

• Drag edge from condition node to target node
• Set edge condition to "yes" or "no"
• Multiple edges from same condition node allowed
• Each edge represents different branch path

• source: Source node ID
• target: Target node ID
• condition: Branch condition (for condition nodes)
• label: Optional display label

​

Flow Validation

• Must have START node
• Must have at least one SEND_MESSAGE node
• All nodes must be connected (directly or via edges)
• Condition nodes must have edges for all branches

• Unconnected nodes
• Condition nodes without branches
• Empty message nodes
• Invalid wait durations

​

Step 3: Advanced Features

​

A/B Testing

• Toggle ab_test_enabled to enable
• Create variations (A, B, C, etc.)
• Each variation has independent flow configuration
• Variations can be enabled/disabled independently

• Deterministic: Same lead always gets same variation
• Uses hash of contact_id as seed
• Weighted distribution: Configure weights per variation
• Default: Uniform distribution (equal weights)

• Automatic optimization based on performance
• Compares response rates between variations
• Adjusts weights to favor better performers
• Threshold: ab_test_optimization_threshold (default: 0.1)

• Tracked per variation: sent, responses, response rate
• Updated every 5 minutes
• View via campaign statistics page

​

Response Handling

• pause_on_response: If true, execution stops immediately when response detected
• If false, execution completes current node before stopping
• Default: false

• response_timeout_hours: Maximum wait time for response
• If no response after timeout, execution continues
• Default: No timeout (waits indefinitely)
• Only applies to response-based WAIT nodes

​

Timezone Configuration

• Required for scheduled campaigns
• Used for converting scheduled time
• Format: IANA timezone (e.g., “America/Sao_Paulo”, “Europe/London”)
• Default: “UTC”

• Scheduled start time displayed in campaign timezone
• Worker converts to UTC for storage
• Ensures campaigns start at correct local time

​

Step 4: Contact Selection

​

Adding Contacts

• Select contacts from available list
• Filter by segment, custom fields, etc.
• Executions created immediately when campaign saved

• Add contacts via campaign detail page
• Executions created with status pending
• For active campaigns: executions processed immediately
• For completed campaigns: campaign reactivated to active

​

Contact Filtering

• Segment membership
• Custom field values
• Tags
• Organization (in org mode)

• One execution per contact
• Status: pending
• next_execution_at: now() for immediate processing
• Context initialized with contact data

​

Step 5: Save and Launch

​

Save as Draft

• Campaign saved but not launched
• Status: draft
• Can be edited freely
• No executions processed
• Can launch later

​

Save and Launch

• Status changes to active (or scheduled if scheduled)
• Executions created for all selected contacts
• next_execution_at set to now() (or scheduled time)
• Worker picks up executions on next cycle

• Campaign must be enabled (enabled = true)
• Telegram account must be connected and healthy
• At least one contact selected
• Flow must be valid

​

Flow Examples

​

Simple Sequence

START → SEND_MESSAGE (Welcome) → WAIT (24 hours) → SEND_MESSAGE (Follow-up) → END

1. START: Initialize execution
2. SEND_MESSAGE: Send welcome message
3. WAIT: Set next_execution_at to 24 hours later
4. Worker resumes after 24 hours
5. SEND_MESSAGE: Send follow-up message
6. END: Mark execution completed

​

Conditional Flow

START → SEND_MESSAGE (Initial) → CONDITION (Response?) 
  ├─ Yes → SEND_MESSAGE (Thank you) → END
  └─ No → WAIT (48 hours) → SEND_MESSAGE (Reminder) → END

1. START: Initialize execution
2. SEND_MESSAGE: Send initial message
3. CONDITION: Check for response
4. If response: Branch to “Yes” path → Send thank you → END
5. If no response: Branch to “No” path → Wait 48h → Send reminder → END

• Edge 1: source: condition_node_id, target: thank_you_node_id, condition: "yes"
• Edge 2: source: condition_node_id, target: wait_node_id, condition: "no"

​

Scheduled Campaign

START (Scheduled: 2024-01-15 09:00 America/Sao_Paulo) 
  → SEND_MESSAGE (Announcement) → END

1. Campaign status: scheduled
2. Worker checks every 30 seconds
3. When scheduled time reached: Status → active
4. Executions begin processing
5. SEND_MESSAGE: Send announcement
6. END: Mark execution completed

​

A/B Test Campaign

START → A/B SELECTION
  ├─ Variation A: SEND_MESSAGE (Version A) → END
  ├─ Variation B: SEND_MESSAGE (Version B) → END
  └─ Variation C: SEND_MESSAGE (Version C) → END

1. START: Initialize execution
2. A/B service selects variation based on contact_id hash
3. Execution uses selected variation’s flow
4. Variation tracked in execution (ab_variation field)
5. Statistics updated per variation

​

Best Practices

1. Test Flow First: Create draft, review flow visually, test with small audience
2. Use Descriptive Names: Make campaigns easy to identify
3. Set Correct Timezone: Ensure scheduled campaigns start at right time
4. Add Fallbacks: Always provide fallback values for tags: {firstName|Guest}
5. Respect Rate Limits: Space out messages with WAIT nodes
6. Monitor Responses: Enable pause on response to stop when lead engages
7. Use A/B Testing: Test variations to optimize performance
8. Document Strategy: Use description field to explain campaign goals

​

Common Mistakes

1. Missing START Node: Every campaign needs START node
2. No Telegram Account: Campaign cannot send without account
3. Invalid Timezone: Scheduled campaigns need valid IANA timezone
4. No Contacts: Campaign needs at least one contact
5. Condition Without Branches: Condition nodes need edges for all paths
6. Circular References: Avoid loops in flow (causes infinite execution)
7. Missing Fallbacks: Tags without fallbacks may break messages
8. Too Aggressive Rate Limiting: Sending too fast causes FloodWaitError