Create a campaign

Updated

Creates an outbound campaign that dials a list of contacts with a saved agent.

Preview documentation

You're reading the Conversational AI Platform (Preview) docs. Switch to Main.
POST
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/campaigns

Each contact is one dial task, and each dial starts a telephony session with the agent in agent_id. You supply the contacts when you create the campaign, and you can't change them afterward.

Before you create a campaign, create the agent and register the phone number to call from.

Caution

A campaign places real phone calls. When schedule.mode is immediate, dialing starts as soon as the campaign is created. To test, create a scheduled campaign with a start time in the future, then cancel it.

Path Parameters

appidstring
Required

The App ID of your project.

Request Body

namestring
Required

A name for the campaign that helps you identify it, 1 to 255 characters.

agent_idstring
Required

The ID of the saved agent that makes the calls.

transportobject
Required

How the campaign reaches its contacts.

typestring
Required

telephony: The campaign places phone calls.

fromOne number | Several numbers
Required

The number_id of the number to call from, or a list of up to 100 unique number_id values. With a list, the campaign rotates across the numbers.

call_policyobject

Limits and behavior for each call the campaign places. Each limit you omit adds no limit.

contactsarray<object>
Required

The contacts to call, from 1 to 50,000. The whole request body can be at most 10 MiB. You can't change the list after you create the campaign. A phone number that appears more than once is called once for each entry.

phonestring
Required

The phone number to call, in E.164 format, for example +12025550123.

valuesobject

Values for the agent's variables for this contact, keyed by variable name, up to 100. Each key must be a variable the agent declares, and each value must match its type and options. Pass a value for every required variable. If any contact breaks these rules, the whole request fails with 400, and no campaign is created. null values are rejected.

scheduleImmediate | Scheduled
Required

When the campaign dials. Pass the fields of one schedule mode only.

modestring(Immediate)
Required

immediate: The campaign starts dialing as soon as it's created.

timezonestring(Immediate)

The IANA time zone for days, for example America/New_York. Daylight saving time is handled automatically. Required when you pass days.

daysarray<object>(Immediate)

The weekly hours when new calls can start. Outside these hours, no new calls start. A day you don't list has no dialing. Omit days to dial at any time.

modestring(Scheduled)
Required

scheduled: The campaign dials from start until end.

timezonestring(Scheduled)
Required

The IANA time zone for start, end, and days, for example America/New_York. Daylight saving time is handled automatically.

startstring(Scheduled)
Required

When the campaign can start dialing, as a local date and time in YYYY-MM-DDTHH:MM format with no offset, for example 2026-11-02T09:00. A local time that doesn't exist or occurs twice because of a daylight saving change is rejected.

endstring(Scheduled)
Required

When the campaign stops placing new calls, as a local date and time in YYYY-MM-DDTHH:MM format, later than start. Calls in progress continue. A local time that doesn't exist or occurs twice because of a daylight saving change is rejected.

daysarray<object>(Scheduled)

The weekly hours when new calls can start. Outside these hours, no new calls start. A day you don't list has no dialing. Omit days to dial at any time.

lifecycleobject

The lifecycle settings for each session the campaign starts. Each session can last up to 1 hour, and lasts up to 5 minutes by default.

pacingobject

How fast the campaign dials. Each contact is called once.

data_policyobject

The data policy for each session the campaign starts. Defaults to 30-day retention.

Response Body

The campaign was created. The response body contains the campaign.

Response Headers

Agora-Request-Idstring

A unique ID for the request. Include it when you contact Agora support.

ETagstring

The current version of the resource. Pass this value in the If-Match header of your next update or delete request for this resource.

campaign_idstring

The ID of the campaign, a UUID.

namestring

The name of the campaign.

statusstring

The status of the campaign:

  • scheduled: The campaign is waiting for its start time.
  • running: The campaign is dialing, or can dial during its schedule.
  • paused: You paused the campaign.
  • completed: The campaign has finished.
  • canceled: You canceled the campaign.
  • failed: The campaign failed. The details are in failure.
agent_idstring

The ID of the agent that makes the calls.

transportobject
lifecycleobject

When each session the campaign starts ends on its own.

scheduleImmediate | Scheduled

When the campaign dials. Pass the fields of one schedule mode only.

countsobject

The number of contacts in each state. Retrieve the campaign to get current counts.

create_tsinteger

The time the campaign was created, as a Unix timestamp in seconds.

start_tsinteger | null

The time the campaign started dialing, as a Unix timestamp in seconds. null before it starts.

complete_tsinteger | null

The time the campaign finished, as a Unix timestamp in seconds. null until it finishes.

failureobject | null

Details of the failure when status is failed. Otherwise null.

Authorization

This endpoint requires authentication.

Request examples

curl -X POST 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/campaigns' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "q3-renewals",
  "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
  "transport": {
    "type": "telephony",
    "from": "92e68758-3d3a-4f27-8b93-3fd8d834467c"
  },
  "contacts": [
    {
      "phone": "+12025550123",
      "values": {
        "name": "Ava",
        "renewal_year": 2027
      }
    }
  ],
  "lifecycle": {
    "idle_timeout_ms": 30000
  },
  "pacing": {
    "max_concurrent": 10,
    "max_calls_per_second": 2
  },
  "schedule": {
    "mode": "scheduled",
    "timezone": "America/New_York",
    "start": "2026-11-02T09:00",
    "end": "2026-11-13T17:00",
    "days": [
      {
        "weekday": "mon",
        "ranges": [
          {
            "start": "09:00",
            "end": "12:00"
          },
          {
            "start": "13:00",
            "end": "17:00"
          }
        ]
      },
      {
        "weekday": "wed",
        "ranges": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ]
      }
    ]
  }
}'

Response example

Example Response
{
  "campaign_id": "b4f0581e-f138-43a2-851c-a8f8d228bb37",
  "name": "q3-renewals",
  "status": "scheduled",
  "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
  "transport": {
    "type": "telephony",
    "from": [
      "92e68758-3d3a-4f27-8b93-3fd8d834467c"
    ]
  },
  "lifecycle": {
    "idle_timeout_ms": 30000,
    "max_duration_ms": 300000,
    "graceful_stop": {
      "enabled": false,
      "timeout_ms": 30000
    }
  },
  "schedule": {
    "mode": "scheduled",
    "timezone": "America/New_York",
    "start": "2026-11-02T09:00",
    "end": "2026-11-13T17:00"
  },
  "counts": {
    "contacts": 1,
    "pending": 1,
    "calling": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0
  },
  "create_ts": 1787673602,
  "start_ts": null,
  "complete_ts": null,
  "failure": null
}