Core Concepts

Pidgr is built around a few core concepts that work together to turn internal announcements into measurable, actionable campaigns.

Organizations

An organization is the top-level container for everything in Pidgr — members, teams, groups, roles, templates, and campaigns all belong to exactly one organization. All API requests are scoped to an organization; cross-organization access is denied.

A user can belong to multiple organizations and switch between them in the mobile, desktop, and admin apps.

Sandbox organizations

Besides standard organizations, Pidgr supports sandbox organizations — disposable environments for demos, evaluation, and automated testing. Sandboxes can be seeded from fixtures and carry an expiry, after which they are automatically cleaned up.

Members

A member is a user within an organization. Members join in one of two ways:

• Email invitation — an admin invites a specific email address (individually or in bulk) and assigns a role.
• Invite links — an admin creates a shareable link that lets people self-join. Links carry a role assignment and optional constraints (maximum redemptions, expiry) and can be revoked at any time.

Each member has a profile (name, department, title, location, manager, and organization-defined custom attributes) that can be populated by admins, by the member, or automatically via SSO attribute mapping or SCIM provisioning. Profile attributes such as the member’s manager are used at runtime — for example, to resolve manager escalation targets.

Member accounts move through a simple lifecycle: INVITED → ACTIVE → DEACTIVATED (deactivated members no longer receive messages and can be reactivated).

Campaigns

A campaign is a structured communication sent to a targeted audience. Unlike email blasts or chat 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

Campaign Statuses

Status	Description
CREATED	Draft campaign, not yet started
RUNNING	Actively delivering messages and processing actions
COMPLETED	All recipients processed; campaign finished
FAILED	Terminated due to an unrecoverable error
CANCELLED	Manually stopped before completion

Workflows

A workflow is a data-driven DAG (directed acyclic graph) that defines the steps a campaign follows. Workflows are not hardcoded — they are declarative definitions that the orchestration engine executes.

Default Workflow Shape

1. SEND_NOTIFICATION — Deliver the message to all audience members
2. DEADLINE_CHECK — Wait for a configurable period (e.g., 72 hours)
3. SEND_REMINDER — Re-notify users who haven’t acknowledged
4. ESCALATE — Notify managers, groups, or role holders about unacknowledged deliveries
5. MARK_MISSED — Mark remaining unacknowledged deliveries as missed
6. CALL_WEBHOOK — POST delivery outcome data to a configured endpoint

Step Types

Type	Purpose
SEND_NOTIFICATION	Send the initial notification with a template
DEADLINE_CHECK	Timer that waits for a configured duration
SEND_REMINDER	Re-send to users who haven’t acknowledged
ESCALATE	Escalate unacknowledged deliveries to configured targets
MARK_MISSED	Mark unacknowledged deliveries as missed
CALL_WEBHOOK	POST campaign results to an external URL

Reminder and escalation steps can additionally fan out through third-party notification channels — Email, Slack, Telegram, SMS, and generic webhooks — alongside the primary push notification.

Escalation

An escalation step turns silence into action. When it fires, it notifies configured targets about deliveries that are still unacknowledged.

• Conditions — escalate if a delivery has not been acknowledged, or while the campaign is still open.
• Targets — a specific user, all members of a group, all holders of a role, or the recipient’s direct manager (resolved at runtime from the recipient’s profile).
• Modes — DELIVER gives targets a full delivery of the campaign, just like primary recipients; ALERT_ONLY sends an out-of-band alert without creating a delivery.
• Repeats — an escalation can repeat on an interval before the workflow moves on.

Templates

A template defines the message content delivered to recipients. Templates support Markdown formatting and variable interpolation.

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

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.

Translations

Templates support multi-language translations. Each translation targets a locale, goes through a review flow (draft → approved), and is selected at delivery time based on the recipient’s preferred locale, falling back to the template’s source language.

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

A delivery represents a single campaign message sent to one recipient. Each delivery tracks:

• Status — Whether the message was delivered, acknowledged, missed, or failed
• Timestamps — When the notification was sent, delivered, and acknowledged
• Actions — What the recipient did (e.g., acknowledged via the ACK button)

Delivery Statuses

Status	Description
PENDING	Message queued but not yet sent
SENT	Notification handed to the delivery provider
DELIVERED	Confirmed delivered to the recipient’s device
ACKNOWLEDGED	Recipient performed the required action
MISSED	Deadline passed without acknowledgment
NO_DEVICE	Recipient has no registered device; delivery skipped
FAILED	Delivery failed due to a provider or system error

Read tracking is separate from acknowledgment: opening a message in the inbox is recorded for analytics, while acknowledgment is the explicit action that drives the workflow.

Actions

An action is an explicit user interaction with a delivered message. The primary action type is ACK (acknowledge), which signals that the recipient has read and understood the message. The action system is generic — each action carries an optional payload, so new action types can be introduced without changing the delivery model.

Actions drive workflow progression — when a user acknowledges a delivery, the workflow records the action and evaluates the next step.

Notification Channels

The first delivery of a campaign always goes through the Pidgr apps (mobile, desktop). If a recipient hasn’t acted by the time a reminder or escalation step executes, notification channels carry the nudge through third-party messengers — Email, Slack, Telegram, SMS, and generic webhooks.

Channel messages are notification-only: they carry a deeplink back to the campaign, never the message content. See the channels overview for the full model and per-channel setup.

Roles and Permissions

Pidgr uses role-based access control (RBAC). Each organization has:

• System roles — Immutable roles seeded on organization creation
• Custom roles — Organization-defined roles with configurable permissions

Permissions are granular, split into read and write per resource area — organization settings, members, campaigns, templates (including translation review), groups, teams, inbox, privacy requests, audit trail, channel dispatch, and reachability management. See the Permission enum for the complete list.