Create conversation

post

https://api.joinpopp.com/v1/conversations

Creates a conversation in Popp application

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

The input to create a conversation

Either campaignId or externalCampaignId is required.

phoneNumber

string

required

The phone number of the candidate, in E.164 format.

shouldSendDuringBusinessHours

boolean

Whether to send the message during business hours. The timezone is inferred from the phone number.

countryCode

string

The country code in ISO 3166-1 alpha-2 format. This is used to format the phone number if it is not in E.164 format.

firstName

string

required

The first name of the candidate.

lastName

string

The last name of the candidate.

emailAddress

string

The email address of the candidate.

campaignId

string

required

The unique identifier for the campaign.

externalId

string

The unique identifier for the conversation in the external system.

externalCampaignId

string

The unique identifier for the campaign in the external system.

applicationSource

string

The source where the application was submitted from (e.g., 'careers-page', 'job-board', 'referral').

skipDuplicationCheck

boolean

Defaults to false

When true, closes ongoing conversation with the same phone number/email in the SAME CAMPAIGN, then creates a new one. Use for re-engaging a candidate within the same campaign. Note: queuing behavior is still respected if conversations exist in other campaigns.

closePreviousConversations

boolean

Defaults to false

When true, closes all ongoing conversations (CREATED, QUEUED, ONGOING) with the same contact identifier (phone number for SMS/WhatsApp, email address for Email) and channel across ALL CAMPAIGNS before creating the new conversation. This completely disables queuing behavior. Applies to SMS, WhatsApp, and Email channels.

openingMessage

string

length ≤ 600

A custom opening message that overrides the campaign's default opening message. Must be 600 characters or less. Additional validation: For SMS campaigns, must include the 'STOP' keyword (uppercase) for opt-out compliance. Not supported for WhatsApp campaigns (will return 400 error).

additionalContext

string

length ≥ 1

Custom context to provide to the AI agent for this specific conversation. This context is used alongside campaign-level and organization-level context when generating replies. Useful for passing candidate-specific information that should influence the conversation.

Responses

200

400