Outbox State Machine: Pausing & Cancelling Broadcasts

Traditional SMS aggregators operate as "black boxes": once you click send or schedule a campaign, your message payload is locked. If you discover a broken discount link, a pricing typo, or the wrong date, your money is spent and your brand reputation is damaged.

Nyota SMS features an enterprise Local Outbox State Machine that retains campaigns in a local queue, giving you real-time Pause, Edit, Resume, and Cancel control right up to the moment of carrier dispatch.

1. How the Outbox State Machine Works Under the Hood

When you launch or schedule an SMS broadcast, messages transition through distinct operational states in the Nyota database:

TEXT

1. DRAFT & COMPOSER
    Admin uploads CSV audience -> Composes message -> Clicks "Schedule Campaign"
                         │
                         ▼
 2. LOCAL OUTBOX QUEUE (status: "queued")
    - Campaign sits in local database table sms.sms_campaigns.
    - All recipient rows generated in sms.sms_messages with status: "queued".
    - Units are held in reserve.
    - [YOU CAN PAUSE, EDIT, OR CANCEL FREELY HERE]
                         │
                         ▼
 3. DISPATCHER WORKER (Every 30 Seconds)
    Cron worker fetches chunks of 20 messages -> Submits to Safaricom/Airtel/Telkom binds.
    - Sent messages move to status: "submitted".
    - [SUBMITTED MESSAGES CAN NO LONGER BE RECALLED]
                         │
                         ▼
 4. TERMINAL DELIVERY (status: "delivered")
    Carrier emits DLR callback code 32 -> Database updates to "delivered".

2. Campaign Lifecycle States Explained

State	Status in Dashboard	What It Means	Actions Available
Queued / Scheduled	`queued`	Messages are pre-rendered in your local Outbox waiting for their scheduled send time.	Pause, Edit Content, Cancel & Refund
Running	`running`	The dispatcher worker is actively transmitting message chunks to mobile network carriers.	Pause, Cancel Remaining
Paused	`paused`	Dispatching is suspended. The worker skips remaining queued recipients.

3. How to Pause or Cancel a Live Campaign

A. Pausing a Campaign (Emergency Hold)

If you spot an error during a live broadcast:

Log in to sms.nyotaimara.com/campaigns.
Locate the active campaign with status: "running".
Click the "Pause Campaign" button.
The dispatcher worker will immediately stop fetching new chunks. Any messages not yet submitted to telecom carriers remain safely in your Outbox.

B. Cancelling a Campaign & Receiving an Instant Refund

If you want to terminate a broadcast completely:

Open sms.nyotaimara.com/campaigns.
Click on the campaign options menu (...) and select "Cancel & Purge".
Confirm the cancellation.
Instant Unit Refund: All unsent queued messages are permanently purged, and the reserved SMS units for those unsent messages are instantly credited back to your workspace unit balance.

4. Common Pitfalls & Why Issues Occur

Pitfall A: "Can I cancel a message after its status changes to 'Submitted'?"

The Explanation: No. Once a message is transmitted across carrier telecom binds (status: "submitted"), the mobile network operator (Safaricom, Airtel, Telkom) has taken custody for handset delivery. Cancellation and refunds apply strictly to remaining messages that are still queued in your local Outbox.

Pitfall B: "My campaign was paused automatically by the system."

The Cause: Your workspace ran out of SMS units mid-broadcast AND your master Nyota Wallet had insufficient balance to cover the automatic Pay-As-You-Go (PAYG) failover.
The Resolution:
1. Pre-fund your Nyota Wallet at accounts.nyotaimara.com/billing or purchase an SMS unit package.
2. Go to sms.nyotaimara.com/campaigns.
3. Click "Resume Campaign" to continue dispatching to the remaining recipients.