Common Types

Shared types referenced by multiple services. Most are defined in pidgr/v1/common.proto; user, channel, key, and organization types that are used platform-wide are noted with their source file.

Messages

Message

Canonical message type used across rendering, inbox, and delivery. Represents the fully rendered content delivered to a recipient.

Field	Type	Description
content_id	string	SHA-256 hash of the rendered content (content-addressable ID).
campaign_id	string	Parent campaign ID.
sender_name	string	Sender display name. Max 200 characters.
title	string	User-facing message title (resolved from campaign or template). Max 200 characters.
summary	string	One-line summary for notification banners. Max 500 characters.
preview	string	Preview text for inbox list views. Max 500 characters.
body	string	Full message body. Max 100,000 characters.
critical	bool	Whether immediate attention is required.
actions	MessageAction[]	Available recipient actions.
created_at	Timestamp	Creation timestamp.

MessageAction

An action button attached to a message.

Field	Type	Description
id	string	Unique action identifier within the message.
type	ActionType	Action type (e.g. ACK).
label	string	Display label (e.g., “Got it”). Max 50 characters.

Pagination

Cursor-based pagination parameters for list requests.

Field	Type	Description
page_size	int32	Maximum items per page.
page_token	string	Opaque token from a previous response for the next page.

PaginationMeta

Pagination metadata in list responses.

Field	Type	Description
next_page_token	string	Token for the next page. Empty if no more pages.
total_count	int32	Total items matching the query (across all pages).

Role

A named role with permissions within an organization.

Field	Type	Description
id	string	Unique identifier.
slug	string	URL-safe slug, unique within the organization (e.g. admin).
name	string	Display name.
is_default	bool	Seeded by the system on organization creation.
permissions	Permission[]	Granted permissions.
is_system	bool	System-managed and immutable (e.g. super_admin).

WorkflowDefinition

A data-driven workflow represented as a directed acyclic graph (DAG) of steps. Defines the automation logic for a campaign’s lifecycle.

Field	Type	Description
steps	WorkflowStep[]	Steps in the workflow DAG. Max 100 steps; the graph must contain no cycles.

WorkflowStep

A single step in a workflow DAG with typed configuration and transitions. Exactly one config field (matching type) must be set — they form a oneof.

Field	Type	Description
id	string	Unique step identifier within the workflow.
type	StepType	Step type.
send_notification	SendNotificationConfig	Config for SEND_NOTIFICATION steps.
deadline_check	DeadlineCheckConfig	Config for DEADLINE_CHECK steps.
send_reminder	SendReminderConfig	Config for SEND_REMINDER steps.
call_webhook	CallWebhookConfig	Config for CALL_WEBHOOK steps.
escalate_config	EscalateConfig	Config for ESCALATE steps.
transitions	map<string, string>	Next step ID by outcome key (e.g. "completed" -> "step_3"). Max 10 entries.

SendNotificationConfig

Configuration for the step that sends the initial notification.

Field	Type	Description
type	string	Delivery type. Accepted value: push.
template_id	string	Template for this step. Empty falls back to the campaign-level template.
template_version	int32	Pinned template version. 0 falls back to the campaign-level version.
action_label	string	Action button label (e.g. “Acknowledge”). Max 50 characters.
action_type	ActionType	Action type for the message button.
custom_variables	map<string, string>	Step-level values for custom template variables. Max 100 entries.

DeadlineCheckConfig

Configuration for a deadline-based timer step that sleeps before proceeding. Acknowledgments happen independently at the delivery level and are evaluated by subsequent steps.

Field	Type	Description
delay	string	Duration string (e.g. "72h"). Valid range 1 minute to 1 year.

SendReminderConfig

Configuration for a step that sends a one-time reminder to non-responsive recipients.

Field	Type	Description
type	string	Delivery type. Accepted value: push.
third_party_channels	ChannelName[]	Additional notification channels to dispatch the reminder through alongside push. Empty means push-only.
notify_targets	EscalationTarget[]	Third parties to loop in when the reminder fires. Each resolved target receives a passive inbox delivery (no action button) that auto-dismisses when the original recipient acknowledges. Max 5 entries.

CallWebhookConfig

Configuration for a step that calls an external webhook.

Field	Type	Description
name	string	Human-readable name for logging/display. Max 200 characters.
url	string	URL to POST campaign context to. HTTPS required in production; private, loopback, and link-local addresses are rejected. Max 2048 characters.
headers	map<string, string>	Additional HTTP headers. Max 20 entries.

EscalationTarget

Who should be notified when an escalation (or reminder notify-target) fires.

Field	Type	Description
type	EscalationTargetType	Target type.
target_id	string	ID of the target (user, group, or role). Empty for MANAGER — resolved at runtime from the recipient’s manager.

EscalateConfig

Configuration for an escalation step in the workflow DAG.

Field	Type	Description
condition	EscalationCondition	Condition that triggers escalation.
targets	EscalationTarget[]	Targets to notify when escalation fires.
repeat_count	int32	Times to repeat before moving to the next step. Max 5.
repeat_interval_minutes	int32	Minutes between repeat attempts.
mode	EscalateMode	Behavior mode. UNSPECIFIED is normalized to DELIVER.
third_party_channels	ChannelName[]	Additional notification channels to dispatch the escalation through. Empty means no third-party fan-out.

User

A user within an organization. Defined in pidgr/v1/user.proto.

Field	Type	Description
id	string	Unique platform identifier (not the identity-provider subject ID).
email	string	Email address. Max 254 characters.
name	string	Display name. Max 200 characters.
status	UserStatus	Account status.
created_at	Timestamp	Creation timestamp.
role	Role	The user’s role with its permission set.
role_id	string	ID of the user’s role (for assignment operations).
profile	UserProfile	Structured profile attributes. May be empty.
processing_restricted	bool	Whether data processing is restricted (GDPR Art. 18). When true, the user is excluded from campaign audiences by default.
data_governance_region	string	Region override (EU, LATAM, BR, APAC, US). Empty inherits the organization default.

UserProfile

Structured profile attributes, populated through admin invitation, mobile onboarding, or SSO/SCIM attribute sync. Defined in pidgr/v1/user.proto. All string fields max 200 characters.

Field	Type	Description
first_name	string	Given name.
last_name	string	Family name.
department	string	Department or team.
title	string	Job title.
phone	string	Phone number.
location	string	Office or geographic location.
employee_id	string	Organization-specific employee identifier.
manager_name	string	Display name of the direct manager.
start_date	string	Employment start date (YYYY-MM-DD).
custom_attributes	map<string, string>	Organization-defined custom attributes. Max 50 entries.
manager_id	string	UUID of the direct manager within the same organization. Used to resolve MANAGER escalation targets.

UserSettings

User-configurable platform settings that apply across all clients. Defined in pidgr/v1/user.proto. Zero values mean “no change” in updates.

Field	Type	Description
theme_preference	ThemePreference	Preferred color scheme.
preferred_locale	string	Preferred language for UI and notifications (en, es, pt-BR, zh, ja). Empty means organization default / auto-detect.

Enums

ActionType

Value	Number	Description
ACTION_TYPE_UNSPECIFIED	0	Unspecified
ACTION_TYPE_ACK	1	Acknowledge — recipient confirms they received the message

CampaignStatus

Value	Number	Description
CAMPAIGN_STATUS_UNSPECIFIED	0	Unspecified
CAMPAIGN_STATUS_CREATED	1	Created but not yet started
CAMPAIGN_STATUS_RUNNING	2	Actively delivering messages and processing actions
CAMPAIGN_STATUS_COMPLETED	3	All recipients processed; campaign finished
CAMPAIGN_STATUS_FAILED	4	Terminated due to an unrecoverable error
CAMPAIGN_STATUS_CANCELLED	5	Manually cancelled before completion

DeliveryStatus

Value	Number	Description
DELIVERY_STATUS_UNSPECIFIED	0	Unspecified
DELIVERY_STATUS_PENDING	1	Queued, not yet sent
DELIVERY_STATUS_SENT	2	Push notification sent to the delivery provider
DELIVERY_STATUS_DELIVERED	3	Confirmed delivered to the device
DELIVERY_STATUS_ACKNOWLEDGED	4	Recipient completed the required action
DELIVERY_STATUS_MISSED	5	Recipient did not act before the deadline
DELIVERY_STATUS_NO_DEVICE	6	No registered device; delivery skipped
DELIVERY_STATUS_FAILED	7	Failed due to a provider or system error

StepType

Value	Number	Description
STEP_TYPE_UNSPECIFIED	0	Unspecified
STEP_TYPE_SEND_NOTIFICATION	1	Send the initial notification to all recipients
STEP_TYPE_DEADLINE_CHECK	2	Sleep for a configurable deadline
STEP_TYPE_SEND_REMINDER	3	Send a follow-up reminder to recipients who have not acted
STEP_TYPE_CALL_WEBHOOK	4	Call an external webhook with campaign context
STEP_TYPE_MARK_MISSED	5	Mark unacknowledged deliveries as missed
STEP_TYPE_ESCALATE	6	Escalate unacknowledged deliveries to configured targets

EscalationCondition

Value	Number	Description
ESCALATION_CONDITION_UNSPECIFIED	0	Unspecified
ESCALATION_CONDITION_IF_NOT_ACKED	1	Escalate if the delivery has not been acknowledged
ESCALATION_CONDITION_IF_NOT_CLOSED	2	Escalate while the campaign is still open

EscalationTargetType

Value	Number	Description
ESCALATION_TARGET_TYPE_UNSPECIFIED	0	Unspecified
ESCALATION_TARGET_TYPE_USER	1	A specific user by ID
ESCALATION_TARGET_TYPE_GROUP	2	All members of a group
ESCALATION_TARGET_TYPE_MANAGER	3	The recipient’s direct manager (resolved at runtime)
ESCALATION_TARGET_TYPE_ROLE	4	All users with a specific role

EscalateMode

Value	Number	Description
ESCALATE_MODE_UNSPECIFIED	0	Normalized to DELIVER
ESCALATE_MODE_DELIVER	1	Targets receive a delivery for the campaign, like primary recipients
ESCALATE_MODE_ALERT_ONLY	2	Targets receive an out-of-band alert only; no delivery is created

Permission

Granular permission for authorization checks, granted through roles, API keys, and OAuth scopes. PERMISSION_PLATFORM_* values are reserved for platform staff and cannot be assigned within customer organizations.

Value	Number	Description
PERMISSION_UNSPECIFIED	0	Unspecified
PERMISSION_ORG_READ	1	View organization settings
PERMISSION_ORG_WRITE	2	Modify organization settings
PERMISSION_MEMBERS_READ	3	View organization members
PERMISSION_MEMBERS_INVITE	4	Invite new users to the organization
PERMISSION_MEMBERS_MANAGE	5	Change user roles, deactivate users
PERMISSION_CAMPAIGNS_READ	6	View campaigns and deliveries
PERMISSION_CAMPAIGNS_WRITE	7	Create and edit campaigns
PERMISSION_CAMPAIGNS_START	8	Start campaign execution
PERMISSION_TEMPLATES_READ	9	View templates
PERMISSION_TEMPLATES_WRITE	10	Create and edit templates
PERMISSION_INBOX_READ	11	View inbox messages and deliveries
PERMISSION_INBOX_ACT	12	Submit actions on deliveries
PERMISSION_GROUPS_ALL_READ	13	View all groups in the organization
PERMISSION_GROUPS_WRITE	14	Manage groups the caller created
PERMISSION_GROUPS_ALL_WRITE	15	Manage any group in the organization
PERMISSION_TEAMS_ALL_READ	16	View all teams in the organization
PERMISSION_TEAMS_WRITE	17	Manage teams the caller created
PERMISSION_TEAMS_ALL_WRITE	18	Manage any team in the organization
PERMISSION_PRIVACY_READ	19	View privacy requests (exports, deletions)
PERMISSION_PRIVACY_WRITE	20	Schedule deletions, export user data, restrict processing
PERMISSION_AUDIT_READ	21	View audit trail events
PERMISSION_TEMPLATES_REVIEW	22	Review and approve template translations
PERMISSION_PLATFORM_SUPPORT	23	Cross-organization read access (staff only)
PERMISSION_PLATFORM_ACCESS_CODES	24	Manage platform access codes (staff only)
PERMISSION_PLATFORM_PROVISION	25	Provision and manage organizations (staff only)
PERMISSION_PLATFORM_ABUSE_RESPONSE	26	Abuse-response actions against organizations (staff only)
PERMISSION_PLATFORM_COMPLIANCE_WRITE	27	Write subprocessor and compliance records (staff only)
PERMISSION_PLATFORM_SYNTHETIC	28	Create synthetic (flagged) demo data (staff only)
PERMISSION_CHANNELS_DISPATCH	29	Dispatch notifications to third-party channels
PERMISSION_REACHABILITY_WRITE	30	Manage a member’s third-party channel reachability
PERMISSION_PLATFORM_INCIDENTS	31	Triage security incidents (staff only)

Platform

Value	Number	Description
PLATFORM_UNSPECIFIED	0	Unspecified
PLATFORM_IOS	1	iOS
PLATFORM_ANDROID	2	Android

ChannelName

Third-party notification channel for reminder and escalation dispatch. Defined in pidgr/v1/channel_events.proto. Push is intentionally not in this enum — push is the primary channel and always fires; third-party channels are additive and carry only a deeplink notification, never message content. See notification channels.

Value	Number	Description
CHANNEL_NAME_UNSPECIFIED	0	Unspecified
CHANNEL_NAME_EMAIL	1	Email
CHANNEL_NAME_WEBHOOK	2	Generic webhook
CHANNEL_NAME_TELEGRAM	3	Telegram
CHANNEL_NAME_SLACK	4	Slack
CHANNEL_NAME_SMS	5	SMS
CHANNEL_NAME_WHATSAPP	6	WhatsApp
CHANNEL_NAME_MICROSOFT_TEAMS	7	Microsoft Teams
CHANNEL_NAME_LINE	8	LINE
CHANNEL_NAME_GOOGLE_CHAT	9	Google Chat

ChannelStepKind

Workflow step kind that triggered a channel dispatch. Defined in pidgr/v1/channel_events.proto.

Value	Number	Description
CHANNEL_STEP_KIND_UNSPECIFIED	0	Unspecified
CHANNEL_STEP_KIND_REMINDER	1	Dispatch triggered by a reminder step
CHANNEL_STEP_KIND_ESCALATION	2	Dispatch triggered by an escalation step

ChannelEventStatus

Status of a channel dispatch attempt. Events are append-only — each state transition (e.g. SENT → DELIVERED via a provider webhook) is its own event. Defined in pidgr/v1/channel_events.proto.

Value	Number	Description
CHANNEL_EVENT_STATUS_UNSPECIFIED	0	Unspecified
CHANNEL_EVENT_STATUS_SENT	1	Handed to the provider
CHANNEL_EVENT_STATUS_DELIVERED	2	Confirmed delivered by the provider
CHANNEL_EVENT_STATUS_OPENED	3	Recipient opened the notification
CHANNEL_EVENT_STATUS_CLICKED	4	Recipient clicked the deeplink
CHANNEL_EVENT_STATUS_BOUNCED	5	Provider bounce
CHANNEL_EVENT_STATUS_FAILED	6	Dispatch failed
CHANNEL_EVENT_STATUS_SKIPPED	7	Dispatch skipped (see ChannelSkipReason)

ChannelSkipReason

Reason a dispatch was skipped rather than attempted. Defined in pidgr/v1/channel_events.proto.

Value	Number	Description
CHANNEL_SKIP_REASON_UNSPECIFIED	0	Unspecified
CHANNEL_SKIP_REASON_OPTED_OUT	1	Recipient opted out of the channel
CHANNEL_SKIP_REASON_REGION_BLOCKED	2	Blocked by the organization’s region policy
CHANNEL_SKIP_REASON_COST_CAP_EXCEEDED	3	Organization cost cap exceeded
CHANNEL_SKIP_REASON_NO_IDENTIFIER	4	No channel identifier on file for the recipient
CHANNEL_SKIP_REASON_ORG_SUSPENDED	5	Organization suspended

KeyType

Type of API key. Defined in pidgr/v1/api_key.proto.

Value	Number	Description
KEY_TYPE_UNSPECIFIED	0	Unspecified
KEY_TYPE_API_KEY	1	Platform API key
KEY_TYPE_SCIM_TOKEN	2	SCIM provisioning token

OrgType

Classification of an organization’s lifecycle type. Defined in pidgr/v1/organization.proto.

Value	Number	Description
ORG_TYPE_UNSPECIFIED	0	Unspecified
ORG_TYPE_STANDARD	1	Standard organization
ORG_TYPE_SANDBOX	2	Sandbox organization with an expiry
ORG_TYPE_STAFF	3	Reserved for platform operations; cannot be created via the API

ThemePreference

Defined in pidgr/v1/user.proto.

Value	Number	Description
THEME_PREFERENCE_UNSPECIFIED	0	Treated as SYSTEM when reading, “no change” when updating
THEME_PREFERENCE_LIGHT	1	Always light mode
THEME_PREFERENCE_DARK	2	Always dark mode
THEME_PREFERENCE_SYSTEM	3	Follow the operating system or browser preference

UserStatus

Defined in pidgr/v1/user.proto.

Value	Number	Description
USER_STATUS_UNSPECIFIED	0	Unspecified
USER_STATUS_INVITED	1	Invited but has not completed onboarding
USER_STATUS_ACTIVE	2	Active; can receive messages
USER_STATUS_DEACTIVATED	3	Deactivated; will not receive messages