Campaigns

Summary

The Campaign Schema Type defines the structure and behavior of outbound communication initiatives within the Nextiva SDK. Campaigns provide a standardized model for creating, scheduling, targeting, and executing messages across various channels such as voice, SMS, and email.

This document outlines the structure of the Campaign schema, its fields, and how to interact with campaign definitions using the generic SchemaTypeClient.

What is a Campaign?

A Campaign models an outbound message sequence or a broadcast configuration. It includes metadata about delivery channels, target audiences, message content, and its execution state. Campaigns are essential for:

Automated Outreach: Sending customer notifications, follow-up messages, or marketing sequences.
Multi-channel Communication: Coordinating communication across different channels (e.g., a phone call followed by an email).
Targeted Messaging: Defining audience segments for personalized communication.
Lifecycle Management: Tracking campaign progress from draft to completion or cancellation.

Structure of a Campaign

A Campaign object is composed of many fields that define its configuration, content, and state.

Field summary

Field	Type	Description
_id	string	Internal unique identifier (MongoDB ID).
campaignId	string	Public unique identifier for the campaign (e.g., `cmp_123`).
name	string	Human-readable display name for the campaign.
description	string	Optional description for the campaign.
type	'DEFAULT' \| 'PERSONAL'	The type of campaign. 'DEFAULT' for standard campaigns, 'PERSONAL' for campaigns linked to personal inboxes.
callerId	string	The phone number or ID used as the caller ID for outbound calls.
smsFromAddress	string	The SMS address used as the sender for SMS messages.
emailFromAddress	string	The email address used as the sender for emails.
workflowId	string	The ID of the associated workflow that defines the campaign’s logic.
createdAt	number	Unix timestamp (ms) when the campaign was created.
createdBy	string	Identifier of the entity that created the campaign.
modifiedAt	number	Unix timestamp (ms) when the campaign was last modified.
modifiedBy	string	Identifier of the entity that last modified the campaign.
deletedAt	number	Unix timestamp (ms) if the campaign record is soft-deleted.
dispositions	object	Related dispositions for this campaign.
emailAccounts	object[]	List of email accounts used for the campaign.
enableRealtimeTranscription	boolean	Enables real-time transcription for calls within the campaign.
useForEmail	boolean	Indicates if the campaign is enabled for email.
useForExtension	boolean	Indicates if the campaign is enabled for extensions.
useForFax	boolean	Indicates if the campaign is enabled for fax.
useForOutbound	boolean	Indicates if the campaign is enabled for outbound calls.
useForPredictive	boolean	Indicates if the campaign is enabled for predictive dialing.
useForProgressive	boolean	Indicates if the campaign is enabled for progressive dialing.
useForSMS	boolean	Indicates if the campaign is enabled for SMS.
recordingAnalysisPercentage	number	Percentage of calls to analyze for recording analysis.
recordingPromptId	string	ID of the prompt to play for recording consent.
supervisor	CampaignSupervisor[]	List of supervisors for the campaign.

Campaign types

The type field in the Campaign interface uses two string literal values:

'DEFAULT': Represents a standard, general-purpose campaign.
'PERSONAL': Denotes a campaign specifically configured for “personal inboxes.” These are often used for individual agent campaigns or personalized outreach.

Example object

import { Campaign } from '@ncx/ncx-core-sdk';

const exampleCampaign: Campaign = {
  _id: "60c72b2f9b1e8e0007c8e8e3",
  campaignId: "cmp_renewal_q4",
  name: "Renewal Reminder Q4",
  description: "Automated email campaign for Q4 renewals.",
  type: "DEFAULT",
  callerId: "+18001234567",
  smsFromAddress: "8881234567",
  emailFromAddress: "[email protected]",
  workflowId: "wf_renewal_sequence",
  createdAt: 1672531200000, // Jan 1, 2023
  createdBy: "user_admin",
  modifiedAt: 1678886400000, // March 15, 2023
  modifiedBy: "user_marketing",
  deletedAt: 0,
  enableRealtimeTranscription: false,
  useForEmail: true,
  useForOutbound: false,
  useForSMS: true,
  recordingAnalysisPercentage: 0.1,
  recordingPromptId: "prompt_consent_rec",
  // ... other optional fields as needed
};

Interacting with Campaigns

Campaign definitions are managed exclusively through the generic SchemaTypeClient, which provides a consistent interface for all CRUD operations. There is no dedicated sdk.campaigns client.

Access the client

import { Nextiva } from '@nextiva/ncx-web-sdk';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient(); // Use the generic schema client

Create a new Campaign

import { Campaign } from '@ncx/ncx-core-sdk';

const newCampaignData = {
  name: "Holiday Promo 2024",
  description: "SMS campaign for holiday season promotions.",
  type: "DEFAULT",
  smsFromAddress: "8885551212",
  workflowId: "wf_holiday_promo",
  useForSMS: true,
  tenantId: "t_abcde",
  createdAt: Date.now(),
  createdBy: "user_marketing",
  objectType: "campaign"
};

const newCampaign: Campaign = await schemaTypeClient.create("campaign", {
  data: newCampaignData
});

console.log("Created Campaign:", newCampaign.name);

Retrieve a Campaign

import { Campaign } from '@ncx/ncx-core-sdk';

const campaignIdToRetrieve = "cmp_renewal_q4";
const retrievedCampaign: Campaign = await schemaTypeClient.retrieve("campaign", {
  id: campaignIdToRetrieve,
});

console.log("Retrieved Campaign:", retrievedCampaign.name);

Update a Campaign

import { Campaign } from '@ncx/ncx-core-sdk';

const campaignIdToUpdate = "cmp_renewal_q4";
const updatedCampaignData = {
  description: "Updated email campaign for Q4 renewals, now includes SMS.",
  useForSMS: true,
  modifiedAt: Date.now(),
  modifiedBy: "user_marketing",
};

const updatedCampaign: Campaign = await schemaTypeClient.update("campaign", {
  id: campaignIdToUpdate,
  data: updatedCampaignData
});

console.log("Updated Campaign:", updatedCampaign.name);

Search for Campaigns

import { Campaign, FetchCampaignsResponseBody } from '@ncx/ncx-core-sdk';

const searchResults: FetchCampaignsResponseBody = await schemaTypeClient.search("campaign", {
  q: "name:Holiday*", // Search for campaigns with names starting with "Holiday"
  rows: 10,
  start: 0,
});

console.log(`Found ${searchResults.total} campaigns.`);

Delete a Campaign

const campaignIdToDelete = "cmp_old_promo";
await schemaTypeClient.delete("campaign", {
  id: campaignIdToDelete,
});

console.log(`Campaign ${campaignIdToDelete} deleted successfully.`);

Permissions

Access to manage campaigns is controlled by the standard permissions model.

Scope	Description
campaigns:read	Allows viewing campaign details and configurations.
campaigns:write	Allows creating or updating campaign definitions.
campaigns:delete	Allows deleting campaigns.
campaigns:admin	Grants administrative control over campaigns, including scheduling and targeting.

Validation rules

name is required and must be unique within a tenant.
workflowId is required and must reference a valid workflow.
type must be either 'DEFAULT' or 'PERSONAL'.
Channel-specific fields (e.g., smsFromAddress, emailFromAddress) are required if the campaign uses that channel.
Timestamps (createdAt, modifiedAt) must be valid Unix timestamps in milliseconds.

Relationships

Workflows: Campaigns are intrinsically linked to Workflow definitions.
Users: Campaigns are created and modified by Users.
Dispositions: Campaigns can use Dispositions to categorize outcomes.