Core Concepts
Pidgr is built around a few core concepts that work together to turn internal announcements into measurable, actionable campaigns.
Campaigns
Section titled “Campaigns”A campaign is a structured communication sent to a targeted audience. Unlike email blasts or Slack messages, campaigns are tracked end-to-end with delivery confirmation and engagement metrics.
Each campaign has:
- A name for internal identification
- A title shown to recipients
- A template that defines the message content
- An audience of targeted users
- A workflow that orchestrates the delivery lifecycle
- A status tracking its progression (Draft → Active → Completed/Cancelled)
Campaign Statuses
Section titled “Campaign Statuses”| Status | Description |
|---|---|
CREATED | Draft campaign, not yet started |
ACTIVE | Running — notifications being sent, waiting for acknowledgments |
COMPLETED | All deliveries resolved (acknowledged, missed, or failed) |
CANCELLED | Manually stopped before completion |
Workflows
Section titled “Workflows”A workflow is a data-driven DAG (directed acyclic graph) that defines the steps a campaign follows. Workflows are not hardcoded — they are JSON definitions that the orchestration engine executes.
Default Workflow Steps
Section titled “Default Workflow Steps”- SEND_NOTIFICATION — Deliver the push notification to all audience members
- DEADLINE_CHECK — Wait for a configurable period (e.g., 72 hours)
- SEND_REMINDER — Re-notify users who haven’t acknowledged
- MARK_MISSED — Mark remaining unacknowledged deliveries as missed
- CALL_WEBHOOK — POST delivery outcome data to a configured endpoint
Step Types
Section titled “Step Types”| Type | Purpose |
|---|---|
SEND_NOTIFICATION | Send push notifications with a template |
DEADLINE_CHECK | Timer that waits for a configured duration |
SEND_REMINDER | Re-send to users who haven’t acknowledged |
MARK_MISSED | Mark unacknowledged deliveries as missed |
CALL_WEBHOOK | POST campaign results to an external URL |
Templates
Section titled “Templates”A template defines the message content delivered to recipients. Templates support Markdown formatting and variable interpolation.
Template Variables
Section titled “Template Variables”Variables use {{variable_name}} syntax and are resolved at render time:
- Audience variables — Per-user values provided when creating a campaign (e.g.,
{{name}},{{department}}) - Custom variables — Step-level values defined in the workflow (e.g.,
{{deadline}})
Template Versioning
Section titled “Template Versioning”Templates are append-only versioned. Each edit creates a new version. Campaigns pin a specific template version at creation time, ensuring consistency even if the template is later modified.
Audiences
Section titled “Audiences”An audience defines who receives a campaign. Audiences are composed from:
- Groups — Named collections of users for cross-functional targeting (e.g., “Engineering”, “All Managers”)
- Teams — Organizational units representing departments or divisions
- Individual members — Specific users added directly
Each audience member can have per-user variables that personalize the template content for that recipient.
Deliveries
Section titled “Deliveries”A delivery represents a single campaign message sent to one recipient. Each delivery tracks:
- Status — Whether the recipient has acknowledged, missed, or failed to receive the message
- Timestamps — When the notification was sent, read, and acknowledged
- Actions — What the recipient did (e.g., acknowledged via the ACK button)
Delivery Statuses
Section titled “Delivery Statuses”| Status | Description |
|---|---|
PENDING | Notification queued but not yet sent |
SENT | Push notification delivered to the device |
READ | User opened the message in their inbox |
ACKNOWLEDGED | User performed the required action (e.g., tapped “Got it”) |
MISSED | Deadline passed without acknowledgment |
FAILED | Delivery failed (e.g., no registered device, push error) |
Actions
Section titled “Actions”An action is a user interaction with a delivered message. The primary action type is ACK (acknowledge), which signals that the recipient has read and understood the message.
Actions drive workflow progression — when a user acknowledges a delivery, the workflow records the action and evaluates the next step.
Roles and Permissions
Section titled “Roles and Permissions”Pidgr uses role-based access control (RBAC). Each organization has:
- System roles — Immutable roles seeded on organization creation (Super Admin, Admin, Manager, Member)
- Custom roles — Organization-defined roles with configurable permissions
Permissions are granular and cover operations like managing campaigns, templates, members, teams, groups, roles, SSO, and API keys.