POST
/
v1
/
campaigns
Create Campaign
curl --request POST \
  --url https://api.eqho.ai/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "name": "<string>",
  "status": "CREATED",
  "agents": [
    "<string>"
  ],
  "initial_contact_medium": "web_voice",
  "rules": {
    "call_limit": 123,
    "call_window": [
      {
        "weekday": 1,
        "start_time": 1179,
        "end_time": 1179
      }
    ],
    "messenger_disposition_threshold_in_minutes": 123,
    "medium_response_settings": {},
    "api_text_disposition_threshold_in_minutes": 123
  },
  "disable_system_dispositioning": true,
  "dispositions": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "parent_disposition": "<string>",
      "color": "<string>",
      "contacted": true,
      "conversion": true,
      "enabled": true
    }
  ],
  "call_transfer_phone_number": "<string>",
  "tasks": [
    {
      "task_type": "try_again",
      "task_settings": {},
      "type": "post_call",
      "condition": {
        "call_count": [
          123
        ],
        "dispositions": [
          {
            "field": "twilio_status",
            "values": [
              "<string>"
            ]
          }
        ]
      },
      "required": false
    }
  ],
  "call_now_threshold_recall_time": 123,
  "external_context_template": "customer has purchased their order.",
  "system_prompt": null,
  "campaign_duration": {
    "campaign_start_date": "2023-11-07T05:31:56Z",
    "campaign_end_date": "2023-11-07T05:31:56Z"
  },
  "disable_amd": true,
  "custom_fields": {
    "postal_code": "1234"
  },
  "precall_tasks_execution_mode": "prolonged_ringing"
}'
{
  "_id": "<string>",
  "name": "<string>",
  "status": "CREATED",
  "account_id": "<string>",
  "agents": [
    "<string>"
  ],
  "phone_numbers": [
    "<string>"
  ],
  "inbound_phone_numbers": [
    "<string>"
  ],
  "claimed_phone_numbers": {},
  "dispositions": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "parent_disposition": "<string>",
      "color": "<string>",
      "contacted": true,
      "conversion": true,
      "enabled": true
    }
  ],
  "disposition_instructions": "<string>",
  "disposition_level_2_instructions": "<string>",
  "rules": {
    "call_limit": 123,
    "call_window": [
      {
        "weekday": 1,
        "start_time": 1179,
        "end_time": 1179
      }
    ],
    "messenger_disposition_threshold_in_minutes": 123,
    "medium_response_settings": {},
    "api_text_disposition_threshold_in_minutes": 123
  },
  "enabled": true,
  "history": {
    "revision": 0,
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": "unknown",
    "last_modified_at": "2023-11-07T05:31:56Z",
    "last_modified_by": "unknown"
  },
  "call_transfer_phone_number": "<string>",
  "tasks": [
    {
      "task_type": "try_again",
      "task_settings": {},
      "type": "post_call",
      "condition": {
        "call_count": [
          123
        ],
        "dispositions": [
          {
            "field": "twilio_status",
            "values": [
              "<string>"
            ]
          }
        ]
      },
      "required": false
    }
  ],
  "call_now_threshold_recall_time": 123,
  "external_context_template": "<string>",
  "system_prompt": {
    "inbound": {
      "sections": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ],
      "conversation_seeder": [
        "<string>"
      ],
      "structured_conversation_seeder": [
        {
          "role": "system",
          "content": "<string>",
          "tool_calls": [
            "<any>"
          ]
        }
      ],
      "type": "outbound",
      "medium": "web_voice",
      "extend_sections": false,
      "extend_conversation_seeder": false
    },
    "outbound": {
      "sections": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ],
      "conversation_seeder": [
        "<string>"
      ],
      "structured_conversation_seeder": [
        {
          "role": "system",
          "content": "<string>",
          "tool_calls": [
            "<any>"
          ]
        }
      ],
      "type": "outbound",
      "medium": "web_voice",
      "extend_sections": true,
      "extend_conversation_seeder": true
    }
  },
  "disable_system_dispositioning": true,
  "campaign_duration": {
    "campaign_start_date": "2023-11-07T05:31:56Z",
    "campaign_end_date": "2023-11-07T05:31:56Z"
  },
  "disable_amd": true,
  "custom_fields": {},
  "a2p_status": "rejected",
  "initial_contact_medium": "web_voice",
  "precall_tasks_execution_mode": "prolonged_ringing",
  "inbound_lead_list": "<string>",
  "llm_judge_settings": [
    {
      "name": "Agent Performance Judge",
      "enabled": true,
      "execution_type": "on_conversation_completion",
      "judge_instructions": "Evaluate the agent's performance based on the following criteria. Provide a concise evaluation and a rationale for each. Focus on whether the agent achieved the primary goal.",
      "criteria": {
        "description": "Rate the agent's politeness on a scale of 1-5.",
        "name": "politeness_score"
      },
      "llm_model": "gpt-4o-mini"
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

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.

​
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
​
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.

​
call_transfer_phone_number
string | null
​
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
object | null

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

Examples:

null

​
campaign_duration
object | null
​
disable_amd
boolean | null
default:false

With Answering Machine Detection (AMD), you can determine if a human answering machine or fax machine has picked up an outbound call. If omitted or set to false, AMD will be enabled for this campaign. In that case, when the agent detects the call is answered by a machine, it will hang up. If set to true, your agents will continue the conversation with the answering machine. This is useful for navigating IVR or leaving a voicemail message to the user.

​
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:
{ "postal_code": "1234" }
​
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.

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

Response

Successful Response

Container for a single campaign record.

​
name
string
required
​
status
enum<string>
required
Available options:
CREATED,
ACTIVE,
INACTIVE,
PAUSED,
PROCESSED
​
_id
string | null
​
account_id
string | null
​
agents
string[]
​
phone_numbers
string[] | null
​
inbound_phone_numbers
string[] | null
​
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

​
rules
object | null
​
enabled
boolean | null
default:true
​
history
object | null
​
call_transfer_phone_number
string | null
​
tasks
CallTask · object[]
​
call_now_threshold_recall_time
integer | null
​
external_context_template
string | null
​
system_prompt
object | null
​
disable_system_dispositioning
boolean | null
default:false
​
campaign_duration
object | null
​
disable_amd
boolean | null
default:false
​
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
​
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.

​
llm_judge_settings
LLMJudgeSettings · object[] | null

List of LLM Judge configurations