Skip to main content

​
Campaign Management Overview

Campaign management involves viewing, editing, controlling execution, and monitoring performance. All operations respect organization context and role-based permissions.

​
Viewing Campaigns

​
Campaign List

The campaigns list displays all accessible campaigns based on view mode and permissions. View Modes: My Campaigns (view_mode=own):
  • Shows only campaigns you created
  • Default view for all users
  • In organization mode: Shows your campaigns within organization
  • In personal mode: Shows your personal campaigns
All Organization Campaigns (view_mode=all):
  • Shows all campaigns in organization
  • Only available to Owner/Admin roles
  • Requires admin_view_enabled = true setting
  • Members cannot access this view (falls back to “own”)
Personal Mode:
  • Shows campaigns with organization_id = NULL
  • Complete isolation from organization data
  • Only your own campaigns visible

​
Campaign Details

Click campaign name to view detailed information: Overview Tab:
  • Campaign metadata (name, description, status)
  • Telegram account information
  • Creation and update timestamps
  • Creator information (in org mode)
Flow Tab:
  • Visual representation of flow
  • Read-only view of nodes and edges
  • Shows current flow configuration
Contacts Tab:
  • List of all contacts in campaign
  • Execution status per contact
  • Add/remove contacts functionality
  • Filter and search contacts
Statistics Tab:
  • Real-time campaign metrics
  • Execution breakdown by status
  • Message statistics (sent, delivered, failed)
  • Response rates and completion rates
  • Recent activities (last 20 log entries)
Logs Tab:
  • Complete audit trail of all executions
  • Filter by execution, node type, status
  • Search by contact name or message content
  • Export logs for compliance

​
Permissions

​
View Permissions

Own Campaigns:
  • All roles can view own campaigns
  • Always accessible regardless of organization settings
Other Members’ Campaigns:
  • Owner/Admin: Can view if admin_view_enabled = true
  • Member: Cannot view (even if admin_view_enabled = true)
  • Campaign must belong to same organization
Personal Mode:
  • Users can only view campaigns with organization_id = NULL
  • Complete isolation from organization data

​
Edit Permissions

Own Campaigns:
  • All roles can edit own campaigns
  • Subject to status-based restrictions (see below)
Other Members’ Campaigns:
  • Owner: Can edit any organization campaign (regardless of status)
  • Admin: Can edit any organization campaign (regardless of status)
  • Member: Cannot edit other members’ campaigns
Status-Based Restrictions:
  • draft, paused, scheduled: Can edit flow configuration
  • active: Cannot edit flow (must pause first)
  • completed, cancelled: Cannot edit (historical record)
Note: Basic metadata (name, description, Telegram account) can be updated even when flow is locked.

​
Delete Permissions

Own Campaigns:
  • All roles can delete own campaigns
  • Soft delete: deleted_at timestamp set
  • Statistics and logs preserved
Other Members’ Campaigns:
  • Owner: Can delete any organization campaign
  • Admin: Can delete any organization campaign
  • Member: Cannot delete other members’ campaigns

​
Campaign Actions

​
Launch Campaign

Start a campaign to begin processing executions. Requirements:
  • Campaign status: draft or paused
  • Campaign must be enabled (enabled = true)
  • Telegram account must be connected and healthy
  • At least one contact must be selected
Launch Process:
  1. Status changes to active (or scheduled if scheduled)
  2. Paused executions resume (status: pending)
  3. Completed executions reset (status: pending, current_node_id = null)
  4. next_execution_at set to now() for immediate processing
  5. Worker picks up executions on next cycle
Permissions:
  • Owner: Can launch own campaigns
  • Admin: Can launch own campaigns
  • Member: Can launch own campaigns
  • Cannot launch other members’ campaigns (even with view access)

​
Pause Campaign

Temporarily stop an active campaign. Pause Process:
  1. Campaign status changes to paused
  2. All active executions paused (status: paused)
  3. next_execution_at preserved (resume from same point)
  4. Flow configuration can be edited
Resume:
  • Launch campaign again to resume
  • Executions continue from where they stopped
  • No progress lost
Permissions:
  • Owner: Can pause own campaigns
  • Admin: Can pause own campaigns
  • Member: Can pause own campaigns
  • Cannot pause other members’ campaigns

​
Stop Campaign

Immediately stop a campaign and cancel all executions. Stop Process:
  1. Campaign status changes to cancelled
  2. All active executions cancelled (status: cancelled)
  3. completed_at timestamp set
  4. error_message: “Campaign stopped by user”
  5. Cannot be resumed (must duplicate to restart)
Permissions:
  • Owner: Can stop own campaigns
  • Admin: Can stop own campaigns
  • Member: Can stop own campaigns
  • Cannot stop other members’ campaigns

​
Edit Campaign

Modify campaign settings and flow configuration. What Can Be Edited: Always Editable (regardless of status):
  • Campaign name
  • Description
  • Telegram account
  • Timezone
  • A/B test settings (if not active)
  • Response handling settings
Status-Dependent:
  • Flow configuration (nodes, edges): Only if draft, paused, or scheduled
  • Cannot edit flow if active, completed, or cancelled
Edit Restrictions:
  • Active campaigns: Must pause before editing flow
  • Completed campaigns: Cannot edit (historical record)
  • Cancelled campaigns: Cannot edit (historical record)
Permissions:
  • Owner: Can edit own campaigns (subject to status)
  • Admin: Can edit own campaigns (subject to status)
  • Member: Can edit own campaigns (subject to status)
  • Owner/Admin: Can edit other members’ campaigns (subject to status)
  • Member: Cannot edit other members’ campaigns

​
Duplicate Campaign

Create a copy of an existing campaign. Duplication Process:
  1. New campaign created with name: "{original_name} (Copy)"
  2. Flow configuration copied (nodes, edges)
  3. Settings copied (timezone, Telegram account, A/B test config)
  4. Status set to draft
  5. No contacts assigned (must add manually)
Use Cases:
  • Create variations for A/B testing
  • Test changes without affecting original
  • Reuse successful campaign structure
Permissions:
  • Owner: Can duplicate own campaigns
  • Admin: Can duplicate own campaigns
  • Member: Can duplicate own campaigns
  • Owner/Admin: Can duplicate other members’ campaigns (if can view)
  • Member: Cannot duplicate other members’ campaigns

​
Delete Campaign

Permanently remove a campaign (soft delete). Delete Process:
  1. deleted_at timestamp set
  2. Campaign hidden from list (soft delete)
  3. Statistics and logs preserved
  4. Executions preserved (for audit trail)
  5. Can be restored (if needed)
Permissions:
  • Owner: Can delete own campaigns
  • Admin: Can delete own campaigns
  • Member: Can delete own campaigns
  • Owner/Admin: Can delete other members’ campaigns
  • Member: Cannot delete other members’ campaigns

​
Enable/Disable Campaign

​
Enable Campaign

Enable a disabled campaign to allow launching. Enable Process:
  1. enabled flag set to true
  2. Campaign can be launched
  3. Previously cancelled executions remain cancelled
  4. Does not automatically start campaign
Use Cases:
  • Re-enable after maintenance
  • Enable after fixing issues
  • Prepare campaign for launch

​
Disable Campaign

Disable a campaign to prevent launching and stop active executions. Disable Process:
  1. enabled flag set to false
  2. Campaign cannot be launched
  3. All active executions immediately cancelled
  4. Status remains unchanged (can be active, paused, etc.)
Use Cases:
  • Emergency stop without deleting
  • Temporarily prevent launches
  • Disable problematic campaigns
Difference from Pause:
  • Pause: Temporarily stops, can resume
  • Disable: Prevents launching, cancels executions
  • Disabled campaigns cannot be launched until re-enabled

​
Contact Management

​
Adding Contacts

Add contacts to campaign (works for any status). During Campaign Creation:
  • Select contacts from available list
  • Executions created when campaign saved
After Campaign Creation:
  • Use “Add Contacts” button on campaign detail page
  • Select contacts from available list
  • Executions created with status pending
  • For active campaigns: Executions processed immediately
  • For completed campaigns: Campaign reactivated to active
Execution Creation:
  • One execution per contact
  • Status: pending
  • next_execution_at: now() for immediate processing
  • Context initialized with contact data
  • Duplicate contacts skipped (execution already exists)

​
Removing Contacts

Remove contacts from campaign. Remove Process:
  1. Select contacts to remove
  2. Executions deleted (soft delete)
  3. Progress lost for removed contacts
  4. Campaign statistics updated
Permissions:
  • Owner: Can remove contacts from own campaigns
  • Admin: Can remove contacts from own campaigns
  • Member: Can remove contacts from own campaigns
  • Owner/Admin: Can remove contacts from other members’ campaigns
  • Member: Cannot remove contacts from other members’ campaigns

​
Campaign Statistics

​
Real-Time Metrics

Execution Metrics:
  • total_contacts: Total leads in campaign
  • contacts_started: Executions that began processing
  • contacts_completed: Executions that finished successfully
  • contacts_failed: Executions that failed
  • contacts_active: Currently processing executions
  • contacts_responded: Leads who replied
Message Metrics:
  • messages_sent: Total messages sent
  • messages_failed: Failed send attempts
  • messages_delivered: Confirmed deliveries
  • messages_not_sent: Pending sends
Rates:
  • completion_rate: (completed / total) × 100
  • response_rate: (responded / delivered) × 100
  • delivery_rate: (delivered / sent) × 100

​
Statistics Calculation

Database Function:
  • Statistics computed by get_campaign_statistics() function
  • Aggregates data from executions, logs, and messages
  • Cached for performance (refreshed every 5 minutes)
Real-Time Updates:
  • Statistics update as executions progress
  • Refresh button available for manual update
  • Auto-refresh every 30 seconds on statistics page
Access:
  • Available via /campaign-flows/{id}/statistics endpoint
  • Displayed on campaign detail page
  • Used for performance monitoring

​
Recent Activities

Activity Feed:
  • Last 20 log entries from all executions
  • Shows node executions, message sends, responses
  • Filtered by importance (sendMessage, delivery, response, etc.)
  • Sorted by executed_at (newest first)
Activity Types:
  • message_sent: Message sent to lead
  • campaign_activity: Other node executions
  • response_detected: Lead replied
  • delivery_confirmed: Message delivered

​
Troubleshooting

​
Campaign Not Sending

Check:
  1. Campaign status is active
  2. Campaign is enabled (enabled = true)
  3. Telegram account is connected and healthy
  4. Contacts are selected and executions exist
  5. Rate limits not exceeded
  6. Flow configuration is valid
Common Issues:
  • Account disconnected: Reconnect Telegram account
  • Rate limit exceeded: Wait for cooldown or adjust limits
  • No executions: Add contacts to campaign
  • Invalid flow: Check flow configuration for errors

​
Campaign Stuck

Symptoms:
  • Executions remain in pending or running status
  • No progress for extended period
Check:
  1. Worker is running (check worker logs)
  2. Executions have valid next_execution_at
  3. Rate limits not blocking execution
  4. Telegram account is healthy
Solutions:
  • Pause and resume campaign
  • Check worker logs for errors
  • Verify rate limit configuration
  • Restart worker if needed

​
Cannot Edit Campaign

Check:
  1. Campaign status allows editing (draft, paused, scheduled)
  2. You have edit permissions (owner or admin)
  3. Campaign is not locked by another process
Solutions:
  • Pause campaign before editing flow
  • Check your role and permissions
  • Refresh page and try again
  • Contact support if issue persists

​
Statistics Not Updating

Check:
  1. Statistics cache (refreshes every 5 minutes)
  2. Executions are actually progressing
  3. Database function is working
Solutions:
  • Click refresh button
  • Wait for cache refresh (5 minutes)
  • Check execution logs for activity
  • Contact support if issue persists

​
Best Practices

  1. Monitor Regularly: Check campaign progress and statistics frequently
  2. Use Pause: Pause instead of stop when temporarily halting
  3. Review Logs: Check audit logs for debugging and compliance
  4. Test First: Test campaigns with small audience before full launch
  5. Respect Permissions: Understand role-based access controls
  6. Document Changes: Use description field to note changes
  7. Monitor Rate Limits: Watch account health and rate limit usage
  8. Optimize Based on Data: Use statistics to improve campaigns