CampaignService

Manages the full lifecycle of communication campaigns — from creation through delivery to completion.

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
CancelCampaign	Cancel an active campaign
ListDeliveries	List deliveries for a campaign

CreateCampaign

Create a new campaign in CREATED (draft) status.

Authorization: Requires MANAGE_CAMPAIGNS permission

Request: CreateCampaignRequest

Field	Type	Description
name	string	Internal name for the campaign. Max 200 characters.
title	string	User-facing title shown in notifications. Max 200 characters.
template_id	string	ID of the template to use. UUID format.
template_version	int32	Pinned template version.
sender_name	string	Display name for the message sender. Max 200 characters.
workflow	WorkflowDefinition	Workflow DAG definition.
audience	AudienceMember[]	Target audience with optional per-user variables.

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",
  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",
    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. Starts the workflow engine.

Authorization: Requires MANAGE_CAMPAIGNS permission

Request: StartCampaignRequest

Field	Type	Description
id	string	Campaign ID to start.

Response: StartCampaignResponse

Field	Type	Description
campaign	Campaign	The updated campaign with ACTIVE status.

GetCampaign

Retrieve a campaign by ID.

Authorization: Requires VIEW_CAMPAIGNS permission

Request: GetCampaignRequest

Field	Type	Description
id	string	Campaign ID.

Response: GetCampaignResponse

Field	Type	Description
campaign	Campaign	The campaign.

ListCampaigns

List campaigns for the organization with pagination.

Authorization: Requires VIEW_CAMPAIGNS permission

Request: ListCampaignsRequest

Field	Type	Description
pagination	Pagination	Pagination parameters.

Response: ListCampaignsResponse

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

UpdateCampaign

Update a draft campaign. Only CREATED status campaigns can be updated.

Authorization: Requires MANAGE_CAMPAIGNS permission

Request: UpdateCampaignRequest

Field	Type	Description
id	string	Campaign ID.
name	string	Updated name.
title	string	Updated title.
template_id	string	Updated template ID.
template_version	int32	Updated template version.
sender_name	string	Updated sender name.

Response: UpdateCampaignResponse

Field	Type	Description
campaign	Campaign	The updated campaign.

CancelCampaign

Cancel an active campaign. Stops the workflow — no further reminders or webhook calls.

Authorization: Requires MANAGE_CAMPAIGNS permission

Request: CancelCampaignRequest

Field	Type	Description
id	string	Campaign ID to cancel.

Response: CancelCampaignResponse

Field	Type	Description
campaign	Campaign	The cancelled campaign.

ListDeliveries

List deliveries for a specific campaign.

Authorization: Requires VIEW_CAMPAIGNS permission

Request: ListDeliveriesRequest

Field	Type	Description
campaign_id	string	Campaign ID.
pagination	Pagination	Pagination parameters.

Response: ListDeliveriesResponse

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

Campaign Message

Field	Type	Description
id	string	Unique identifier.
name	string	Internal name.
title	string	User-facing title.
template_id	string	Template ID.
template_version	int32	Pinned template version.
sender_name	string	Sender display name.
status	CampaignStatus	Current status.
workflow	WorkflowDefinition	Workflow DAG.
created_at	Timestamp	Creation timestamp.
started_at	Timestamp	Launch timestamp.
completed_at	Timestamp	Completion timestamp.

Delivery Message

Field	Type	Description
id	string	Unique identifier.
campaign_id	string	Parent campaign ID.
user_id	string	Recipient user ID.
status	DeliveryStatus	Current delivery status.
message	Message	The rendered message content.
sent_at	Timestamp	When the notification was sent.
read_at	Timestamp	When the user opened the message.
acknowledged_at	Timestamp	When the user acknowledged.