Campaigns

Campaigns are the core unit of communication in Pidgr. Each campaign delivers a structured message to a targeted audience and tracks engagement through the entire lifecycle.

Creating a Campaign

Via Admin Dashboard

1. Navigate to Campaigns → Create Campaign
2. Fill in the required fields:
   • Name — Internal identifier for the campaign
   • Title — User-facing title shown in push notifications and inbox
   • Template — Select a template and version
   • Sender Name — Display name for the message sender
3. Configure the audience:
   • Select target groups and/or teams
   • Optionally provide per-user template variables
4. The campaign is created in Draft status

Via API

const response = await campaignClient.createCampaign({
  name: "Q1 Security Update",
  title: "Important Security Changes",
  templateId: "template-uuid",
  templateVersion: 1,
  senderName: "Security Team",
  audience: [
    { userId: "user-uuid-1", variables: { name: "Alice" } },
    { userId: "user-uuid-2", variables: { name: "Bob" } },
  ],
});

Editing a Campaign

Draft campaigns can be edited before launch. Once a campaign is started, it cannot be modified.

1. Open the campaign from the list view
2. Click Edit
3. Modify any field (name, title, template, audience)
4. Save changes

Caution

Only campaigns in Draft (CREATED) status can be edited. Active campaigns are immutable.

Launching a Campaign

Starting a campaign triggers the workflow engine:

1. Open the draft campaign
2. Click Start Campaign
3. Confirm the launch

What Happens on Launch

1. The campaign status changes to ACTIVE
2. The workflow engine picks up the workflow definition
3. The first step (usually SEND_NOTIFICATION) executes:
   • Template is rendered for each audience member
   • Push notifications are dispatched to all registered devices
   • Deliveries are created with SENT status
4. Subsequent steps execute according to the workflow DAG

Monitoring Deliveries

Track campaign progress in real time:

1. Open an active campaign
2. View the Deliveries tab
3. Monitor status breakdown:
   • Sent — Notification delivered to device
   • Read — User opened the message
   • Acknowledged — User completed the required action
   • Missed — Deadline passed without acknowledgment
   • Failed — Delivery error (no device, push failure)

Delivery Metrics

The campaign detail view shows:

• Total audience size
• Acknowledgment rate (acknowledged / total)
• Read rate (read / total)
• Missed count
• Failed count

Cancelling a Campaign

Active campaigns can be cancelled:

1. Open the active campaign
2. Click Cancel Campaign
3. Confirm the cancellation

Cancellation stops the workflow — no further reminders or webhook calls will be made. Existing deliveries retain their current status.

Campaign Lifecycle

CREATED (Draft)
    ↓ Start
ACTIVE
    ↓ All deliveries resolved
COMPLETED

ACTIVE
    ↓ Manual cancel
CANCELLED

Webhooks

Campaigns can include a CALL_WEBHOOK step that POSTs delivery outcome data to an external URL when the campaign completes. See the Webhooks guide for configuration details.

Best Practices

• Use descriptive names — Campaign names should clearly identify the purpose and timing
• Pin template versions — Always specify a template version to avoid unexpected content changes
• Size audiences carefully — Larger audiences mean more push notifications; consider splitting into batches
• Monitor actively — Check delivery progress within the first hour to catch failures early
• Configure webhooks — Pipe results to your existing tools (Slack, PagerDuty, etc.) for visibility