CampaignService

Manages the full lifecycle of communication campaigns — from creation through delivery to completion. Campaigns freeze an audience snapshot at creation time, render a pinned template version per recipient, and execute a workflow DAG that can send notifications, check deadlines, send reminders, escalate, call webhooks, and fan out to third-party channels.

Methods

Method	Description
CreateCampaign	Create a new campaign in draft status
StartCampaign	Launch a draft campaign
GetCampaign	Retrieve a campaign by ID
ListCampaigns	List campaigns for the organization
UpdateCampaign	Update a draft campaign
GetCampaignAudience	Read a campaign’s frozen audience snapshot
CancelCampaign	Cancel a running campaign
ListDeliveries	List deliveries for a campaign
GetCampaignArchetypeBreakdown	Archetype share shifts for an archetype-originated campaign
ResolveOrCreateShortCode	Resolve a campaign’s short-code (internal)
GetCampaignByShortCode	Look up minimal campaign metadata by short-code

Escalation and third-party channels

Reminder and escalation behavior is configured in the campaign’s WorkflowDefinition, not on the campaign itself:

• STEP_TYPE_SEND_REMINDER steps can list additional third_party_channels (email, Slack, Telegram, SMS, WhatsApp, Microsoft Teams, LINE, Google Chat, webhook) to dispatch reminders through, and notify_targets to send passive heads-up copies to.
• STEP_TYPE_ESCALATE steps notify escalation targets (a user, a group, the recipient’s manager, or a role) when a condition fires (IF_NOT_ACKED or IF_NOT_CLOSED). The EscalateMode controls what targets receive: ESCALATE_MODE_DELIVER (default) creates real deliveries for the targets, ESCALATE_MODE_ALERT_ONLY sends an informational alert. Both modes support third-party channel fan-out.

Which channels are actually eligible at runtime depends on the organization’s channel configuration and each recipient’s linked channels.

CreateCampaign

Create a new campaign in CREATED (draft) status. The audience is frozen into a snapshot at creation time — members added to the organization later are not reached unless the audience is replaced before start.

Authorization: Requires Manager role or higher

Request: CreateCampaignRequest

Field	Type	Description
name	string	Internal name for the campaign. Max 200 characters.
template_id	string	ID of the template to use. UUID format.
template_version	int32	Pinned template version.
user_ids	string[]	User IDs forming the campaign audience. Max 100,000 items.
workflow	WorkflowDefinition	Workflow DAG definition. Required — requests without a workflow are rejected with INVALID_ARGUMENT. Must be an acyclic graph of well-formed steps.
sender_name	string	Display name for the message sender (e.g. “HR Team”). Max 200 characters.
title	string	Optional user-facing title override. If empty, the template title is used. Max 200 characters.
audience	AudienceMember[]	Rich audience with per-user template variables. Takes precedence over user_ids when set. Max 100,000 items.
include_restricted	bool	Whether to include users with restricted processing in the audience. Default false.
critical	bool	Whether notifications break through Do Not Disturb / Focus mode.
default_locale	string	Optional locale override for all recipients (en, es, pt-BR, zh, ja). Empty means per-recipient locale resolution.
wait_for_enrollment	bool	Whether the campaign deadline waits for users without registered devices, letting them acknowledge via inbox after installing the app. Default false.
originating_archetype	CampaignOriginatingArchetype	Optional. Set when the campaign is created from an archetype call-to-action. Metadata only — the audience is not filtered by archetype.

Response: CreateCampaignResponse

Field	Type	Description
campaign	Campaign	The created campaign.

Example

TypeScript (Connect-Web)

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

Go (gRPC)

resp, err := campaignClient.CreateCampaign(ctx, &pidgrv1.CreateCampaignRequest{
    Name:            "Q1 Security Update",
    Title:           "Important Security Changes",
    TemplateId:      "template-uuid",
    TemplateVersion: 1,
    SenderName:      "Security Team",
    Workflow:        securityAckWorkflow,
    Audience: []*pidgrv1.AudienceMember{
        {UserId: "user-1", Variables: map[string]string{"name": "Alice"}},
        {UserId: "user-2", Variables: map[string]string{"name": "Bob"}},
    },
})

StartCampaign

Launch a draft campaign, triggering its workflow execution.

Authorization: Requires Manager role or higher

Request: StartCampaignRequest

Field	Type	Description
campaign_id	string	Campaign ID to start. UUID format.

Response: StartCampaignResponse

Field	Type	Description
campaign	Campaign	The campaign with updated status (RUNNING).

GetCampaign

Retrieve a campaign by ID.

Authorization: Authenticated user within the organization

Request: GetCampaignRequest

Field	Type	Description
campaign_id	string	Campaign ID. UUID format.

Response: GetCampaignResponse

Field	Type	Description
campaign	Campaign	The campaign.

ListCampaigns

List campaigns for the organization with pagination.

Authorization: Authenticated user within the organization

Request: ListCampaignsRequest

Field	Type	Description
pagination	Pagination	Pagination parameters.

Response: ListCampaignsResponse

Field	Type	Description
campaigns	Campaign[]	List of campaigns.
pagination_meta	PaginationMeta	Pagination metadata.

UpdateCampaign

Update a draft campaign. Only CREATED status campaigns can be updated. Non-empty fields overwrite existing values; omitted fields remain unchanged.

Authorization: Requires Manager role or higher

Request: UpdateCampaignRequest

Field	Type	Description
campaign_id	string	Campaign ID. UUID format.
name	string	Updated name. Empty means no change.
sender_name	string	Updated sender display name. Empty means no change.
title	string	Updated title override. Empty means no change.
template_id	string	Updated template ID. Empty means no change.
template_version	int32	Updated template version. Zero means no change.
workflow	WorkflowDefinition	Updated workflow DAG. Null means no change.
audience_replacement	AudienceReplacement	Replaces the frozen audience snapshot wholesale (an empty member list is valid). Omitted means no change. Rejected once the campaign has started.

Response: UpdateCampaignResponse

Field	Type	Description
campaign	Campaign	The updated campaign.

GetCampaignAudience

Read a campaign’s frozen audience snapshot, enriched with member identity so clients can render and edit it. Empty for campaigns without a snapshot.

Authorization: Authenticated user within the organization

Request: GetCampaignAudienceRequest

Field	Type	Description
campaign_id	string	Campaign ID. UUID format.

Response: GetCampaignAudienceResponse

Field	Type	Description
entries	CampaignAudienceEntry[]	The frozen audience, enriched per entry.

CampaignAudienceEntry

Field	Type	Description
member	AudienceMember	The frozen audience row: user ID plus per-user template variables.
email	string	The member’s email at read time. Empty when the user no longer resolves.
display_name	string	The member’s display name at read time. Empty when unresolvable.
active	bool	False when the user is no longer an active or invited member of the organization.

CancelCampaign

Cancel a running campaign, stopping further deliveries and reminders.

Authorization: Requires Manager role or higher

Request: CancelCampaignRequest

Field	Type	Description
campaign_id	string	Campaign ID to cancel. UUID format.

Response: CancelCampaignResponse

Field	Type	Description
campaign	Campaign	The campaign with updated status (CANCELLED).

ListDeliveries

List delivery records for a campaign, optionally filtered by status.

Authorization: Authenticated user within the organization

Request: ListDeliveriesRequest

Field	Type	Description
campaign_id	string	Campaign ID. UUID format.
status_filter	DeliveryStatus	Optional filter by delivery status. UNSPECIFIED returns all.
pagination	Pagination	Pagination parameters.

Response: ListDeliveriesResponse

Field	Type	Description
deliveries	Delivery[]	List of deliveries.
pagination_meta	PaginationMeta	Pagination metadata.

GetCampaignArchetypeBreakdown

Compute how each archetype’s share of the originating group has moved between the snapshot closest to campaign creation and the most recent snapshot. Only valid for campaigns whose originating_archetype is set. Results are cohort-level only.

Authorization: Authenticated user within the organization

Request: GetCampaignArchetypeBreakdownRequest

Field	Type	Description
campaign_id	string	Campaign ID. UUID format.

Response: GetCampaignArchetypeBreakdownResponse

Field	Type	Description
shifts	ArchetypeShareShift[]	One entry per archetype in the originating group. Empty when insufficient_history is true.
before_snapshot_at	Timestamp	When the “before” sample was taken.
after_snapshot_at	Timestamp	When the “after” sample was taken.
insufficient_history	bool	True when fewer than two clustering snapshots exist, so no shift can be computed yet.

ResolveOrCreateShortCode

Resolve a campaign’s 8-character short-code, lazily generating one on first call. The same campaign always resolves to the same code for its lifetime. Used when assembling third-party-channel deeplinks.

Authorization: Internal service callers only

Request: ResolveOrCreateShortCodeRequest

Field	Type	Description
campaign_id	string	The campaign whose short-code is being resolved. UUID format.

Response: ResolveOrCreateShortCodeResponse

Field	Type	Description
short_code	string	8-character base62 short-code, stable for the campaign’s lifetime.

GetCampaignByShortCode

Look up a campaign by its public short-code. Called by the native app when a recipient taps a third-party-channel deeplink. Returns minimal, non-PII metadata sufficient to route to the correct campaign card and show organization branding before sign-in.

Authorization: Unauthenticated

Request: GetCampaignByShortCodeRequest

Field	Type	Description
short_code	string	The 8-character base62 short-code from the deeplink path.

Response: GetCampaignByShortCodeResponse

Field	Type	Description
campaign_id	string	Campaign UUID for the authenticated GetCampaign follow-up.
org_id	string	Organization UUID owning the campaign.
organization_name	string	Organization display name for sign-in branding.
subject	string	Campaign subject (title).

Campaign Message

Field	Type	Description
id	string	Unique identifier. UUID format.
name	string	Internal name. Max 200 characters.
template_id	string	Template ID. UUID format.
template_version	int32	Pinned template version.
audience_snapshot_ref	string	Storage reference to the audience snapshot taken at creation.
status	CampaignStatus	Current status (CREATED, RUNNING, COMPLETED, FAILED, CANCELLED).
workflow	WorkflowDefinition	Workflow DAG.
total_recipients	int32	Total recipients in the audience snapshot (counts deliveries; 0 until start).
action_completed_count	int32	Recipients who completed the required action.
missed_count	int32	Recipients who did not act before the deadline.
created_at	Timestamp	Creation timestamp.
started_at	Timestamp	Launch timestamp.
completed_at	Timestamp	Completion timestamp (completed, failed, or cancelled).
sender_name	string	Sender display name.
title	string	User-facing title override. Takes precedence over the template title when set.
critical	bool	Whether notifications break through Do Not Disturb / Focus mode.
default_locale	string	Locale override for all recipients. Empty means per-recipient resolution.
wait_for_enrollment	bool	Whether the deadline waits for users without registered devices.
originating_archetype	CampaignOriginatingArchetype	Set when created from an archetype call-to-action.
synthetic	bool	True when the campaign contains synthetic (demo/test) data.
audience_snapshot_size	int32	Recipients frozen in the snapshot at creation time. Known before start.
current_audience_size	int32	Members currently eligible for the audience, computed at read time.
audience_snapshot_stale	bool	True when the frozen audience no longer covers the current eligible membership.
workflow_progress	CampaignWorkflowProgress	Live workflow execution position. Unset until start and after a terminal state.

CampaignWorkflowProgress

Field	Type	Description
current_step_id	string	Workflow step currently executing or being waited on.
step_entered_at	Timestamp	When the workflow entered the current step.
next_wake_at	Timestamp	For timer-backed steps: when the pending timer fires. Unset otherwise.

CampaignOriginatingArchetype

Field	Type	Description
group_id	string	UUID of the group whose archetype set the label belongs to.
archetype_label	string	Stable archetype label (e.g. “Swift Acknowledger”).

AudienceMember

Field	Type	Description
user_id	string	User ID. UUID format.
variables	map<string, string>	Template variable values for this user (e.g. {"name": "Alice"}).

Delivery Message

Field	Type	Description
id	string	Unique identifier. UUID format.
user_id	string	Recipient user ID.
campaign_id	string	Parent campaign ID.
status	DeliveryStatus	Current delivery status.
delivered_at	Timestamp	When the message was delivered to the device.
read_at	Timestamp	When the recipient read the message.
acted_at	Timestamp	When the recipient performed the required action.
recipient_email	string	Email address of the recipient, populated on read.
kind	Delivery.Kind	What produced this delivery row.
parent_delivery_id	string	For non-primary deliveries, the originating delivery. Empty for primary deliveries.
rendered_locale	string	The locale this delivery’s body was actually rendered in after fallback resolution.
metadata	DeliveryMetadata	Optional out-of-band context (populated for REMINDER_FYI deliveries).
synthetic	bool	True when this delivery’s outcome is synthetic data.

Delivery.Kind

Value	Description
KIND_PRIMARY	Delivery generated for an audience recipient at campaign start
KIND_ESCALATION	Delivery generated by an escalation step targeting a non-audience user
KIND_REMINDER_FYI	Passive heads-up delivery generated when a reminder step fans out to its notify targets. Carries no action button and auto-dismisses when the parent delivery is acknowledged