Managing Campaigns

​

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