> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reach.raysium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign Statuses

> Complete guide to campaign statuses, transitions, and status-based rules

## Status Overview

Campaigns have seven possible statuses that indicate their current state and determine what actions are allowed. Understanding statuses is crucial for effective campaign management.

## Status Types

### Draft

**When:** Campaign is created but not yet launched.

**Characteristics:**

* Created but not active
* No executions created yet (or executions exist but not started)
* Can be edited freely (flow configuration, settings)
* Can be deleted
* Cannot send messages

**State:**

* `status = "draft"`
* `enabled = true` (default)
* Executions: None or all `pending` with `next_execution_at` in future

**Actions Available:**

* Edit campaign (full access)
* Launch campaign
* Delete campaign
* Duplicate campaign
* Add/remove contacts

**Transitions:**

* → `active`: When launched (immediate start)
* → `scheduled`: When launched with scheduled start time
* → `cancelled`: When deleted (soft delete)

### Scheduled

**When:** Campaign is set to start at a specific date/time.

**Characteristics:**

* Waiting for scheduled start time
* Timezone-aware: Scheduled time stored in UTC, displayed in campaign timezone
* Worker checks every 30 seconds for scheduled campaigns
* Can be edited before start time
* Cannot send messages until scheduled time reached

**State:**

* `status = "scheduled"`
* `start_type = "scheduled"`
* `scheduled_start_at`: UTC timestamp
* `timezone`: Campaign timezone (e.g., "America/Sao\_Paulo")
* Executions: Created but `next_execution_at` set to scheduled time

**Actions Available:**

* Edit campaign (before start time)
* Cancel scheduled start (changes to `draft`)
* Delete campaign
* View schedule details

**Transitions:**

* → `active`: Automatically when scheduled time reached
* → `draft`: When scheduled start cancelled
* → `cancelled`: When deleted

**Timezone Handling:**

* Scheduled time converted from UTC to campaign timezone for display
* Worker compares current UTC time with scheduled UTC time
* Ensures campaigns start at correct local time

### Active

**When:** Campaign is currently running and processing executions.

**Characteristics:**

* Sending messages to leads
* Workers processing executions
* Real-time progress updates
* Cannot edit flow configuration (must pause first)
* Can add/remove contacts dynamically

**State:**

* `status = "active"`
* `enabled = true` (required)
* Executions: Mix of `pending`, `running`, `waiting`, `completed`, `responded`, `failed`
* Worker actively processing executions

**Actions Available:**

* Pause campaign
* Stop campaign
* View statistics (real-time)
* View progress
* Add/remove contacts
* Edit basic metadata (name, description, Telegram account)
* Cannot edit flow configuration

**Transitions:**

* → `paused`: When paused manually
* → `completed`: Automatically when all executions finished
* → `cancelled`: When stopped manually
* → `active`: When reactivated after adding contacts to completed campaign

**Processing:**

* Worker picks up pending executions
* Processes nodes sequentially
* Updates execution status and `next_execution_at`
* Creates execution logs for audit trail

### Paused

**When:** Campaign was active but temporarily stopped.

**Characteristics:**

* Not sending new messages
* All active executions paused
* Progress preserved (executions resume from same point)
* Can be edited (flow configuration unlocked)
* Can be resumed

**State:**

* `status = "paused"`
* `enabled = true` (can be `false` if also disabled)
* Executions: Mix of `paused`, `waiting`, `completed`, `responded`, `failed`
* `next_execution_at` preserved for paused executions

**Actions Available:**

* Resume/Launch campaign
* Edit campaign (full access)
* Stop campaign
* Delete campaign
* Add/remove contacts

**Transitions:**

* → `active`: When resumed/launched
* → `cancelled`: When stopped
* → `draft`: When flow edited significantly (rare)

**Resume Behavior:**

* Paused executions resume (status: `pending`)
* `next_execution_at` unchanged (continues from same point)
* No progress lost

### Completed

**When:** Campaign has finished processing all contacts.

**Characteristics:**

* All executions reached terminal status
* No pending/running/waiting executions
* Shows final statistics
* Cannot be restarted (must duplicate)
* Can be reactivated by adding contacts

**State:**

* `status = "completed"`
* `enabled = true` (can be `false`)
* Executions: All `completed`, `responded`, `failed`, or `cancelled`
* No active executions remaining

**Actions Available:**

* View statistics (final)
* Duplicate campaign
* Delete campaign
* Add contacts (reactivates to `active`)
* Cannot edit flow configuration
* Cannot restart

**Transitions:**

* → `active`: When contacts added (automatic reactivation)
* → `cancelled`: When deleted (soft delete)

**Auto-Completion:**

* Campaign automatically transitions to `completed` when:
  1. All executions reach terminal status
  2. No pending/running/waiting executions remain
  3. Worker detects completion and updates status

### Cancelled

**When:** Campaign was stopped before completion.

**Characteristics:**

* Stopped manually (not natural completion)
* All active executions cancelled
* May have partially sent messages
* Cannot be restarted (must duplicate)
* Historical record preserved

**State:**

* `status = "cancelled"`
* `enabled = true` or `false` (depends on how stopped)
* Executions: Mix of `cancelled`, `completed`, `responded`, `failed`
* `completed_at` timestamp set for cancelled executions

**Actions Available:**

* View statistics (partial)
* Duplicate campaign
* Delete campaign
* Cannot edit flow configuration
* Cannot restart

**Transitions:**

* → (none): Cancelled campaigns cannot transition
* Must duplicate to restart

**Stop Behavior:**

* All active executions immediately cancelled
* `error_message`: "Campaign stopped by user"
* `completed_at` timestamp set
* Progress lost (cannot resume)

### Tracking

**Note:** This status is deprecated. Response detection is now handled automatically by UnifiedWorker. Campaigns no longer use "tracking" status.

**Historical Context:**

* Previously used for campaigns monitoring responses
* Now handled automatically during `active` status
* Response detection runs every 60 seconds for active campaigns

## Status Transitions

### Normal Flow

```
Draft → Scheduled → Active → Completed
         ↓
      Active → Paused → Active → Completed
         ↓
      Cancelled
```

### Transition Rules

**To Active:**

* **From:** `draft`, `paused`, `scheduled`
* **Requires:**
  * Campaign enabled (`enabled = true`)
  * Telegram account connected and healthy
  * At least one contact selected
  * Valid flow configuration
* **Process:**
  * Status changes to `active`
  * Executions created/resumed
  * `next_execution_at` set to `now()`
  * Worker picks up executions

**To Paused:**

* **From:** `active`
* **Requires:**
  * Campaign is active
  * User has pause permissions
* **Process:**
  * Status changes to `paused`
  * All active executions paused
  * `next_execution_at` preserved
  * Flow configuration unlocked for editing

**To Cancelled:**

* **From:** `active`, `paused`, `scheduled`
* **Requires:**
  * User has stop permissions
* **Process:**
  * Status changes to `cancelled`
  * All active executions cancelled
  * `completed_at` timestamp set
  * Cannot be resumed

**To Completed:**

* **From:** `active`
* **Requires:**
  * All executions reached terminal status
  * No pending/running/waiting executions
* **Process:**
  * Worker detects completion
  * Status changes to `completed`
  * Final statistics calculated
  * Campaign locked (cannot restart)

**To Scheduled:**

* **From:** `draft`
* **Requires:**
  * `start_type = "scheduled"`
  * `scheduled_start_at` set
  * `timezone` set
* **Process:**
  * Status changes to `scheduled`
  * Executions created with `next_execution_at = scheduled_start_at`
  * Worker monitors for scheduled time

## Status-Based Restrictions

### Editing Restrictions

**Can Edit Flow Configuration:**

* `draft`: Always editable
* `paused`: Editable (flow unlocked)
* `scheduled`: Editable (before start time)

**Cannot Edit Flow Configuration:**

* `active`: Must pause first (prevents mid-execution changes)
* `completed`: Cannot edit (historical record)
* `cancelled`: Cannot edit (historical record)

**Can Edit Basic Metadata (Always):**

* Campaign name
* Description
* Telegram account
* Timezone
* A/B test settings (if not active)
* Response handling settings

### Permission Restrictions

**View Permissions:**

* Own campaigns: All roles can view
* Other members' campaigns:
  * Owner/Admin: Can view if `admin_view_enabled = true`
  * Member: Cannot view

**Edit Permissions:**

* Own campaigns: All roles can edit (subject to status)
* Other members' campaigns:
  * Owner: Can edit (subject to status)
  * Admin: Can edit (subject to status)
  * Member: Cannot edit

**Delete Permissions:**

* Own campaigns: All roles can delete
* Other members' campaigns:
  * Owner: Can delete
  * Admin: Can delete
  * Member: Cannot delete

## Enable vs Status

### Enabled Campaigns

**Characteristics:**

* `enabled = true`
* Can be launched
* Can become `active`
* Can execute normally

**Behavior:**

* Launch allowed (if status permits)
* Workers process executions
* Normal operation

### Disabled Campaigns

**Characteristics:**

* `enabled = false`
* Cannot be launched
* Any active executions cancelled immediately
* Status may show as "Disabled" regardless of other status

**Behavior:**

* Launch blocked (regardless of status)
* Active executions cancelled on disable
* Different from pause (cannot launch when disabled)

**Use Cases:**

* Emergency stop without deleting
* Temporarily prevent launches
* Disable problematic campaigns

## Status Indicators

### Visual Indicators

Statuses are displayed with color-coded badges:

* **Draft**: Gray/Muted
* **Active**: Green/Success
* **Paused**: Yellow/Warning
* **Completed**: Blue/Primary
* **Cancelled**: Red/Destructive
* **Scheduled**: Orange

### Status in Campaign List

In the campaign list, status is shown:

* As a badge next to the campaign name
* With an enable/disable toggle (separate from status)
* In the status column (if table view)
* With progress indicators (for active campaigns)

## Troubleshooting Status Issues

### Campaign Stuck in Active

**Symptoms:**

* Status shows `active` but no progress
* Executions remain in `pending` or `running`

**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 Change Status

**Check:**

1. You have permissions (must be creator or admin/owner)
2. Campaign is enabled (for launch)
3. Status allows transition (see transition rules)
4. Requirements met (contacts, account, etc.)

**Solutions:**

* Verify your role and permissions
* Check campaign requirements
* Ensure status allows desired transition
* Contact support if issue persists

### Status Not Updating

**Symptoms:**

* Status doesn't reflect actual state
* Transitions not happening automatically

**Check:**

1. Worker is running (for auto-transitions)
2. Database is updated correctly
3. Cache is refreshed

**Solutions:**

* Refresh the page
* Wait for worker cycle (30 seconds)
* Check database directly (if admin)
* Contact support if issue persists

### Scheduled Campaign Not Starting

**Check:**

1. Scheduled time has passed
2. Campaign timezone is correct
3. Worker is running (checks every 30 seconds)
4. Campaign is enabled

**Solutions:**

* Verify scheduled time and timezone
* Check worker logs for errors
* Ensure worker is running
* Contact support if issue persists

## Best Practices

1. **Monitor Status**: Regularly check campaign statuses
2. **Use Pause**: Pause instead of stop when temporarily halting
3. **Plan Schedules**: Use scheduled status for planned campaigns
4. **Track Completion**: Monitor campaigns approaching completion
5. **Document Changes**: Note why status changes were made
6. **Understand Transitions**: Know which transitions are allowed
7. **Respect Restrictions**: Follow status-based edit restrictions
8. **Check Permissions**: Verify role-based access before operations