Message Campaign API

The Message Campaign API allows you to create, retrieve, update, and delete scheduled WhatsApp message campaigns for groups and individuals.

createCampaign

Create a new message campaign with scheduled messages.

Input Parameters

groupId

string

required

The WhatsApp group ID or contact ID

groupName

string

required

The WhatsApp group name or contact name

sessionId

string

required

The WhatsApp session ID to use for sending messages

title

string

Optional campaign title

targetAmount

string

Optional contribution target amount

startDate

string

required

Campaign start date in ISO format (e.g., “2024-01-01”)

endDate

string

required

Campaign end date in ISO format (e.g., “2024-12-31”)

messageTime

string

required

Time to send messages in HH:mm format (e.g., “09:30”)

timeZone

string

default:"America/Chicago"

Time zone for scheduling messages

messageTemplate

string

required

Message template. Use {days_left} placeholder for dynamic days remaining. Separate multiple messages with asterisks (*) for recurring campaigns.

isFreeForm

boolean

default:false

If true, excludes campaign metadata from message content

isRecurring

boolean

required

Whether the campaign sends messages on a recurring schedule

recurrence

enum

default:"DAILY"

Recurrence pattern for the campaignOptions: DAILY, WEEKLY, SEMI_MONTHLY, MONTHLY, SEMI_ANNUALLY, ANNUALLY

audienceType

enum

default:"groups"

Type of audience for the campaignOptions: groups, individuals

Response

success

boolean

Indicates whether the campaign was created successfully

campaignId

string

The unique identifier of the created campaign

Example

const result = await trpc.messageCampaign.createCampaign.mutate({
  groupId: "[email protected]",
  groupName: "Community Group",
  sessionId: "session_1234567890",
  title: "Fundraising Campaign",
  targetAmount: "$5000",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  messageTime: "09:00",
  timeZone: "America/Chicago",
  messageTemplate: "Day {days_left}: Please contribute to our cause!",
  isFreeForm: false,
  isRecurring: true,
  recurrence: "DAILY",
  audienceType: "groups"
});

console.log(result);
// { success: true, campaignId: "clx1234567890" }

getCampaigns

Retrieve all active campaigns for the current user (campaigns with future scheduled messages).

Response

campaigns

array

Array of campaign objects

string

Campaign ID

title

string

Campaign title

targetAmount

string

Target contribution amount

startDate

Date

Campaign start date

endDate

Date

Campaign end date

sendTimeUtc

Date

Scheduled send time in UTC

timeZone

string

Campaign time zone

template

string

Message template

status

string

Campaign status

createdAt

Date

Campaign creation timestamp

isRecurring

boolean

Whether campaign is recurring

recurrence

string

Recurrence pattern

group

object

Associated WhatsApp group

string

Group ID

groupName

string

Group name

groupId

string

WhatsApp group ID

messages

array

Array of scheduled messages

string

Message ID

content

string

Message content

scheduledAt

Date

Scheduled send time

sentAt

Date

Actual send time

isSent

boolean

Whether message was sent

isFailed

boolean

Whether message failed to send

Example

const campaigns = await trpc.messageCampaign.getCampaigns.query();

console.log(campaigns);
// [
//   {
//     id: "clx1234567890",
//     title: "Fundraising Campaign",
//     targetAmount: "$5000",
//     startDate: new Date("2024-01-01"),
//     endDate: new Date("2024-01-31"),
//     status: "SCHEDULED",
//     group: {
//       id: "clg9876543210",
//       groupName: "Community Group",
//       groupId: "[email protected]"
//     },
//     messages: [...]
//   }
// ]

getCompletedCampaigns

Retrieve all completed campaigns for the current user (all messages sent or past scheduled time).

Response

Same structure as getCampaigns, but returns campaigns where all messages have been sent or are past their scheduled time.

Example

const completedCampaigns = await trpc.messageCampaign.getCompletedCampaigns.query();

console.log(completedCampaigns);
// Returns array of completed campaign objects

updateCampaign

Update an existing campaign. Only campaigns with no sent messages can be edited.

Input Parameters

campaignId

string

required

The ID of the campaign to update

title

string

Optional campaign title

targetAmount

string

Optional contribution target amount

startDate

string

required

Campaign start date in ISO format

endDate

string

required

Campaign end date in ISO format

messageTime

string

required

Time to send messages in HH:mm format

timeZone

string

default:"America/Chicago"

Time zone for scheduling messages

messageTemplate

string

required

Message template with optional placeholders

isRecurring

boolean

required

Whether the campaign sends messages on a recurring schedule

isFreeForm

boolean

default:false

If true, excludes campaign metadata from message content

recurrence

enum

default:"DAILY"

Recurrence patternOptions: DAILY, WEEKLY, SEMI_MONTHLY, MONTHLY, SEMI_ANNUALLY, ANNUALLY

audienceType

enum

default:"groups"

Type of audienceOptions: groups, individuals

Response

success

boolean

Indicates whether the campaign was updated successfully

campaignId

string

The unique identifier of the updated campaign

Example

const result = await trpc.messageCampaign.updateCampaign.mutate({
  campaignId: "clx1234567890",
  title: "Updated Campaign Title",
  targetAmount: "$7500",
  startDate: "2024-01-01",
  endDate: "2024-02-15",
  messageTime: "10:00",
  timeZone: "America/New_York",
  messageTemplate: "Updated message: {days_left} days left!",
  isRecurring: true,
  isFreeForm: false,
  recurrence: "WEEKLY"
});

console.log(result);
// { success: true, campaignId: "clx1234567890" }

Error Cases

“Campaign not found or access denied”: Campaign doesn’t exist or user doesn’t have permission
“Cannot edit campaign with messages that have already been sent”: At least one message has been sent
“Invalid time format”: messageTime doesn’t match HH:mm format
“End date must be after start date”: Invalid date range

deleteCampaign

Soft delete a campaign and all its associated messages.

Input Parameters

campaignId

string

required

The ID of the campaign to delete

Response

success

boolean

Indicates whether the campaign was deleted successfully

Example

const result = await trpc.messageCampaign.deleteCampaign.mutate({
  campaignId: "clx1234567890"
});

console.log(result);
// { success: true }

Type Definitions

type RecurrencePattern = 
  | 'DAILY'          // Every 1 day
  | 'WEEKLY'         // Every 7 days
  | 'SEMI_MONTHLY'   // Every 15 days
  | 'MONTHLY'        // Every 30 days
  | 'SEMI_ANNUALLY'  // Every 182 days
  | 'ANNUALLY';      // Every 365 days

type AudienceType = 'groups' | 'individuals';

type CampaignStatus = 
  | 'DRAFT'
  | 'SCHEDULED'
  | 'IN_PROGRESS'
  | 'COMPLETED'
  | 'CANCELLED'
  | 'FAILED';

tRPC Routers

Database Schema

createCampaign

Input Parameters

Response

Example

getCampaigns

Response

Example

getCompletedCampaigns

Response

Example

updateCampaign

Input Parameters

Response

Example

Error Cases

deleteCampaign

Input Parameters

Response

Example

Type Definitions

Build docs developers (and LLMs) love

tRPC Routers

Database Schema

​createCampaign

​Input Parameters

​Response

​Example

​getCampaigns

​Response

​Example

​getCompletedCampaigns

​Response

​Example

​updateCampaign

​Input Parameters

​Response

​Example

​Error Cases

​deleteCampaign

​Input Parameters

​Response

​Example

​Type Definitions

Build docs developers (and LLMs) love

createCampaign

Input Parameters

Response

Example

getCampaigns

Response

Example

getCompletedCampaigns

Response

Example

updateCampaign

Input Parameters

Response

Example

Error Cases

deleteCampaign

Input Parameters

Response

Example

Type Definitions