Skip to main content
POST
Create Campaign

Authorizations

X-API-KEY
string
header
required

Your API key for authentication.

x-org-id
string
header
required

Org impersonation via x-org-id. Superadmins may impersonate any org; admins may impersonate their direct sub-organizations. Enter the target organization ID to act as that org.

Body

application/json
name
string
required

The name of the campaign. Only used for your own reference.

status
enum<string>
required
Available options:
CREATED,
ACTIVE,
INACTIVE,
PAUSED,
PROCESSED
agents
string[]

A list of agent IDs that will be assigned to this campaign, you can query them using GET v1/agents. For inbound and outbound calls and SMS, a random agent will be selected from this list for every conversation. For the chat widget, you can select which Agent will be assigned to conversations.

distribution_strategy
enum<string> | null
default:random

How calls are distributed among agents in a campaign.

Available options:
round_robin,
custom_percentage,
random
distribution_settings
DistributionSettings · object | null

Settings for the distribution strategy. Required for custom_percentage distribution strategy.

distribution_by_medium
Distribution By Medium · object | null

Per-medium agent pools and distribution; mediums without an entry use the default distribution.

initial_contact_medium
enum<string> | null

What medium will be used for the initial contact with a lead.

Available options:
web_voice,
telephony,
sms,
email,
chatbot,
api_text,
chat_app,
softphone
rules
Rules · object | null

The rules for the campaign.

disable_system_dispositioning
boolean | null
default:false

If true, system will not disposition conversations from this campaign. Calls made in this campaign will have disposition_level_2 and disposition_level_3 fields as null. You can use this to create your own dispositioning system using post call tasks.

dispositions
DispositionModel · object[]

A list of categories that LLM can use to categorize the outcome of a call. You can use this to setup Task rules based on the dispositions or track the performance of your agents and campaigns.

disposition_level_3_prompt
string | null

Prompt to be shown to the agent when selecting a disposition. If not provided, a default prompt will be used.

call_summary_description
string | null

Optional instructions for this campaign's call summary. If omitted or blank, the system default summary instructions are used.

disposition_level_3_reasoning
enum<string> | null

Reasoning effort for disposition classification and its call summary. Null inherits the agent's reasoning setting, then the system default.

Available options:
none,
low,
medium,
high
disposition_level_3_model

Model to use for disposition level 3 classification. If not provided, the default model will be used.

Available options:
gpt-5.4,
gpt-5.4-pro,
gpt-5.2,
gpt-5.2-pro,
gpt-5.1,
gpt-5,
gpt-5-pro,
gpt-5-mini,
gpt-5-nano,
gpt-4.1,
gpt-4.1-mini,
gpt-4.1-nano,
gpt-4o,
gpt-4o-mini,
o3,
o3-pro,
o3-mini,
o4-mini,
claude-opus-4-6-20260205,
claude-sonnet-4-6-20260205,
claude-opus-4-5-20251101,
claude-sonnet-4-5-20250929,
claude-haiku-4-5-20251001,
claude-opus-4-20250514,
claude-sonnet-4-20250514,
gemini-3.1-pro-preview,
gemini-3-flash-preview,
gemini-2.5-pro,
deepseek-chat,
deepseek-reasoner,
gpt-5-chat-latest,
gpt-5.1-chat-latest,
gpt-5.2-chat-latest,
gpt-5.3-chat-latest
Example:

"gpt-4o-2024-08-06"

tasks
CallTask · object[]

Tasks allow you to do some processing before and/or after a call. They can be used to retry a call, send a webhook or send a text message. You can also set conditions to execute the task based on the call count or disposition status.

call_now_threshold_recall_time
integer | null

The minimum amount of time, in seconds, that must elapse before a lead can be recalled in a campaign using Call Now feature. If provided in the Call Now request, that value takes precedence over the campaign's call_now_threshold_recall_time. When provided, Call Now will return a 400 status code if the lead was last called within this time frame.

If omitted, the lead can be recalled immediately.

external_context_template
string | null

Allows you to add additional context to the Agent during the ongoing conversation. You can provide a template string with placeholders for the custom fields. For example, you can provide template: User purchased {{product_id}} Then, during the Conversation you can hit the Call Context API to replace the placeholders with actual values and provide it to the Agent.

Example:

"customer has purchased their order."

system_prompt
EmbeddedSystemPromptModel · object | null

Advanced setting to override the Eqho default system prompt. In most cases, you should not need to use this.

Example:

null

campaign_duration
CampaignDuration · object | null
disable_amd
boolean | null
default:false
deprecated

Deprecated legacy AMD toggle for old carriers. New voice engines use per-agent amd settings instead. Do not remove this field from clients yet; it remains in responses for backwards compatibility.

answering_machine_detection
AnsweringMachineDetectionSettings · object
deprecated

Deprecated campaign-level answering machine detection settings. Use per-agent amd settings instead. Existing old engines may still read this field.

custom_fields
Custom Fields · object | null

Allows you to add variables to the campaign that can be used by Agents during the conversation. It is a dictionary where the key is the Mention display_name and the value is the value you want to use. You first need to create a Mention with the tag campaign and the display name you want to use.

Example:
precall_tasks_execution_mode
enum<string> | null
default:prolonged_ringing

The mode in which the inbound precall tasks will be executed. If set to prolonged_ringing, the precall tasks will be executed while the phone is ringing. This is ideal for short tasks, as the maximum time to execute the precall tasks is 10 seconds. It's also the default mode.

If set to caller_on_hold, Eqho will answer the call and play hold music to the caller while the precall tasks are executed. Once the tasks are executed, the Agent will pick up the call. The maximum time to execute the precall tasks is 5 minutes.

The outbound precall tasks will always be executed before the call is made.

Available options:
prolonged_ringing
telephony_outbound_caller_id
string | null
sip_proxy_settings
SipProxySettingsInput · object | null
v3_voice_routing_percentage
integer
default:0

Percent of inbound SIP-proxy calls routed to voice engine v3.

Required range: 0 <= x <= 100
v3_voice_redirect_campaign_id
string | null

Response

Successful Response

name
string
required
status
enum<string>
required
Available options:
CREATED,
ACTIVE,
INACTIVE,
PAUSED,
PROCESSED
id
string | null
account_id
string | null
agents
string[]
agent_snapshot_map
Agent Snapshot Map · object | null

Optional mapping of agent_id to snapshot_id or 'latest'. Keys must be agent IDs present in the campaign's agents array. Values are either ObjectId strings referencing agent snapshots, or 'latest' to auto-resolve the newest snapshot.

distribution_strategy
enum<string>
default:random

How calls are distributed among agents in a campaign.

Available options:
round_robin,
custom_percentage,
random
distribution_settings
DistributionSettings · object | null

Settings for the distribution strategy. Required for custom_percentage distribution strategy.

distribution_by_medium
Distribution By Medium · object | null

Per-medium agent pools and distribution; mediums without an entry use the default distribution.

phone_numbers
string[] | null
inbound_phone_numbers
string[] | null
claimed_phone_numbers
Claimed Phone Numbers · object | null

Phone numbers used by this campaign. Keyed by phone number. Using dict to ensure uniqueness. Stored also in phone_numbers and inbound_phone_numbers for backwards compatibility.

dispositions
DispositionModel · object[]
disposition_instructions
string | null
deprecated

scheduled for removal

disposition_level_2_instructions
string | null
deprecated

scheduled for removal

disposition_level_3_prompt
string | null

Custom prompt to classify call outcome. If not provided, a default prompt will be used.

call_summary_description
string | null

Instructions for this campaign's call summary. Blank uses the system default.

disposition_level_3_reasoning
enum<string> | null

Reasoning effort for disposition classification and its call summary. Null inherits the agent's reasoning setting, then the system default.

Available options:
none,
low,
medium,
high
disposition_level_3_model

Model to use for disposition level 3 classification. If not provided, the default model will be used.

Available options:
gpt-5.4,
gpt-5.4-pro,
gpt-5.2,
gpt-5.2-pro,
gpt-5.1,
gpt-5,
gpt-5-pro,
gpt-5-mini,
gpt-5-nano,
gpt-4.1,
gpt-4.1-mini,
gpt-4.1-nano,
gpt-4o,
gpt-4o-mini,
o3,
o3-pro,
o3-mini,
o4-mini,
claude-opus-4-6-20260205,
claude-sonnet-4-6-20260205,
claude-opus-4-5-20251101,
claude-sonnet-4-5-20250929,
claude-haiku-4-5-20251001,
claude-opus-4-20250514,
claude-sonnet-4-20250514,
gemini-3.1-pro-preview,
gemini-3-flash-preview,
gemini-2.5-pro,
deepseek-chat,
deepseek-reasoner,
gpt-5-chat-latest,
gpt-5.1-chat-latest,
gpt-5.2-chat-latest,
gpt-5.3-chat-latest
rules
Rules · object | null
enabled
boolean | null
default:true
history
HistoryModel · object | null
tasks
CallTask · object[]
call_now_threshold_recall_time
integer | null
external_context_template
string | null
system_prompt
EmbeddedSystemPromptModel · object | null
disable_system_dispositioning
boolean | null
default:false
campaign_duration
CampaignDuration · object | null
disable_amd
boolean | null
default:false
deprecated

Deprecated legacy AMD toggle for old carrier paths. New voice engines use per-agent amd settings.

answering_machine_detection
AnsweringMachineDetectionSettings · object
deprecated

Deprecated campaign-level answering machine detection settings. Use per-agent amd settings instead. Existing old engines may still read this field.

custom_fields
Custom Fields · object | null
a2p_status
enum<string> | null
deprecated

Use organization.twilio.a2p_status instead.

Available options:
rejected,
verified,
pending,
unknown
initial_contact_medium
enum<string> | null
Available options:
web_voice,
telephony,
sms,
email,
chatbot,
api_text,
chat_app,
softphone
precall_tasks_execution_mode
enum<string> | null
default:prolonged_ringing

Inbound PreCallTasks can be executed:

  1. During the ringing phase (prolonged_ringing) - the tasks will be executed while the call is ringing. Agent will pick up the call only after the tasks are completed. Max duration is 10 seconds.
Available options:
prolonged_ringing
inbound_lead_list
string | null

The ID of the lead list associated with this campaign. Used to track and manage inbound leads.

telephony_outbound_caller_id
string | null

Optional ObjectId referencing the caller ID to be used when making outbound phone calls for this campaign.

sip_proxy_settings
SipProxySettings · object | null
v3_voice_routing_percentage
integer
default:0

Percent of inbound SIP-proxy calls for this campaign routed to voice engine v3.

Required range: 0 <= x <= 100
v3_voice_redirect_campaign_id
string | null

Optional campaign the v3-routed fraction resolves to (via that campaign's inbound lead list). None keeps v3 calls on this campaign.

source
CampaignSourceModel · object | null

Tracks the source campaign this was cloned from.