Scheduling Campaigns

A SCHEDULING campaign is designed specifically for booking meetings with candidates. Unlike other campaign types, SCHEDULING campaigns focus solely on getting candidates to book a time slot—no screening questions, no rejection flows.

Overview

SCHEDULING campaigns:

• Send a booking link to candidates
• Auto-close when a booking is confirmed (or after 1 week if no booking)
• Support SMS, WhatsApp, and Email channels
• Require a calendarMeetingTemplateId for booking configuration

Quick Start

curl -X POST "https://api.popp.ai/v1/campaigns" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "SCHEDULING",
    "channel": "SMS",
    "campaignTitle": "Interview Scheduling",
    "campaignDescription": "Schedule interviews with engineering candidates",
    "calendarMeetingTemplateId": "your-meeting-template-id",
    "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, please book your interview here: {{MEETING_URL}}. Reply STOP to opt out.",
    "agentName": "Alex",
    "agentTone": "FRIENDLY"
  }'

Note: closingMethod is automatically set to CALENDAR_MEETING_INTEGRATION for SCHEDULING campaigns—you don't need to specify it.

Field Restrictions

SCHEDULING campaigns have specific field restrictions to keep the flow focused on booking.

Disallowed Fields

The following fields are NOT allowed for SCHEDULING campaigns:

Example Error Response

If you include a disallowed field:

{
  "error": "closingMessage is not allowed for SCHEDULING campaigns - booking confirmation serves as the closing message"
}

Channel-Specific Rules

WhatsApp

WhatsApp SCHEDULING campaigns require an approved template (openingMessageTemplateId). Custom messages are not allowed.

Template Requirements:

• Template must be of type SCHEDULING
• Template content must include {{MEETING_URL}} placeholder
• Template content must include STOP opt-out instruction
• Template must belong to your organization

Example Request (WhatsApp):

{
  "campaignType": "SCHEDULING",
  "channel": "WHATSAPP",
  "campaignTitle": "Technical Interview",
  "campaignDescription": "Schedule technical interviews",
  "closingMethod": "CALENDAR_MEETING_INTEGRATION",
  "calendarMeetingTemplateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "openingMessageTemplateId": "your-whatsapp-scheduling-template-id"
}

SMS

SMS SCHEDULING campaigns require either openingMessageTemplateId OR customTemplatedMessage (not both).

Template Requirements (if using templateId):

• Template must be of type SCHEDULING
• Template content must include {{MEETING_URL}} placeholder
• Template content must include STOP opt-out instruction
• Template must belong to your organization

Custom Template Requirements (if using customTemplatedMessage):

• Must include {{MEETING_URL}} placeholder
• Must include STOP opt-out instruction

Available Placeholders (for SMS and Email):

• {{CANDIDATE_FIRST_NAME}} - Candidate's first name
• {{MEETING_URL}} - Booking link (required in message body)
• {{MEETING_TITLE}} - Meeting title from calendar template
• {{AGENT_NAME}} - AI agent's name
• {{JOB_TITLE}} - Job title
• {{EMPLOYER_NAME}} - Employer name
• {{LOCATION}} - Job location
• {{ORGANIZATION_NAME}} - Organization name

Example Request (SMS with Template ID):

{
  "campaignType": "SCHEDULING",
  "channel": "SMS",
  "campaignTitle": "Phone Screen Scheduling",
  "campaignDescription": "Schedule phone screens with candidates",
  "closingMethod": "CALENDAR_MEETING_INTEGRATION",
  "calendarMeetingTemplateId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "openingMessageTemplateId": "your-sms-scheduling-template-id"
}

Example Request (SMS with Custom Template):

{
  "campaignType": "SCHEDULING",
  "channel": "SMS",
  "campaignTitle": "Phone Screen Scheduling",
  "campaignDescription": "Schedule phone screens with candidates",
  "closingMethod": "CALENDAR_MEETING_INTEGRATION",
  "calendarMeetingTemplateId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "customTemplatedMessage": "Hi {{CANDIDATE_FIRST_NAME}}, we'd love to chat! Book your interview here: {{MEETING_URL}}\n\nReply STOP to opt out."
}

Email

Email SCHEDULING campaigns require customTemplatedMessage. Template IDs are not supported for Email.

Custom Template Requirements:

• customTemplatedMessage must include {{MEETING_URL}} placeholder
• customTemplatedMessage must include STOP opt-out instruction
• customTemplatedSubjectLine is required for Email SCHEDULING campaigns

Note: Email supports the same placeholders as SMS (see Available Placeholders above).

Custom Subject Line (Email only):

You can also specify a custom email subject line using customTemplatedSubjectLine. This field supports the same placeholders as the message body (but none are required).

Example Request (Email with Custom Subject):

{
  "campaignType": "SCHEDULING",
  "channel": "EMAIL",
  "campaignTitle": "Executive Interview",
  "campaignDescription": "Schedule executive interviews",
  "closingMethod": "CALENDAR_MEETING_INTEGRATION",
  "calendarMeetingTemplateId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "customTemplatedSubjectLine": "Schedule Your {{MEETING_TITLE}} with {{ORGANIZATION_NAME}}",
  "customTemplatedMessage": "Hello {{CANDIDATE_FIRST_NAME}},\n\nWe're excited to move forward with your application! Please select a time that works for you: {{MEETING_URL}}\n\nLooking forward to speaking with you.\n\nBest regards,\n{{AGENT_NAME}}\n\nReply STOP to unsubscribe."
}

Default Behaviors

Auto-Close Duration

SCHEDULING campaigns default to 168 hours (1 week) for timeToAutoCloseConversationsInHours if not specified.

Note: If a candidate books a meeting, the conversation closes immediately upon booking confirmation. The 1-week timeout only applies if no booking is made.

Calendar Meeting Template

A calendarMeetingTemplateId is required for SCHEDULING campaigns. You can provide it:

1. On the campaign - All conversations use this template
2. On each conversation - Override the campaign-level template per conversation

If neither is provided, the API returns an error:

{
  "message": "calendarMeetingTemplateId is required for SCHEDULING campaigns. Provide it on the campaign or in the conversation payload."
}

Opening Message Override

The openingMessage field is not supported for SCHEDULING campaigns at the conversation level. This is because SCHEDULING campaigns require variable substitution (e.g., {{MEETING_URL}}, {{CANDIDATE_FIRST_NAME}}), which is only processed for campaign-level customTemplatedMessage.

To customize messages for SCHEDULING campaigns, use customTemplatedMessage and customTemplatedSubjectLine when creating the campaign.

Validation Summary

Complete Example

Create a SCHEDULING Campaign (SMS)

curl -X POST "https://api.popp.ai/v1/campaigns" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "SCHEDULING",
    "channel": "SMS",
    "campaignTitle": "Engineering Interview",
    "campaignDescription": "Schedule interviews for senior engineering roles",
    "closingMethod": "CALENDAR_MEETING_INTEGRATION",
    "calendarMeetingTemplateId": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "agentName": "Sarah",
    "agentTone": "FRIENDLY"
  }'

Create a Conversation

curl -X POST "https://api.popp.ai/v1/conversations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign-id-from-above",
    "phoneNumber": "+14155551234",
    "firstName": "John",
    "lastName": "Doe"
  }'

Related Guides

• Meeting Templates - Configure meeting duration, participants, and rules
• Auto-Schedule Conversations - Create conversations that book meetings
• Scheduling Events - Webhook payloads for booking events