Update a campaign
Updated
Changes the pacing, schedule, or dialing limits of a campaign.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/campaigns/{campaign_id}Before the campaign starts dialing, you can change pacing, schedule, lifecycle, and transport.call_policy. After it starts, you can change only pacing, and other fields fail with CampaignNotEditable. After the campaign is completed, canceled, or failed, you can't change it. You can never change agent_id, transport.type, transport.from, or contacts.
appidstringThe App ID of your project.
campaign_idstringThe ID of the campaign, returned in campaign_id when you create the campaign.
If-MatchstringThe ETag value from the most recent response for this resource. If the resource has changed since then, the request fails with 412 and reason PreconditionFailed. Retrieve the resource, apply your change again, and retry with the new ETag.
The fields to change. Before the campaign starts dialing, you can change pacing, schedule, lifecycle, and transport.call_policy. After it starts, you can change only pacing.
pacingobjectChanges to the pacing. Pass any of the pacing fields of Create a campaign. Fields you omit keep their saved values.
max_concurrentintegerThe maximum number of calls in progress at the same time.
max_calls_per_secondintegerThe maximum number of new dials in any one-second window.
scheduleImmediate | ScheduledWhen the campaign dials. Pass the fields of one schedule mode only.
modestring(Immediate)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.
weekdaystringThe day of the week. Each day can appear only once.
rangesarray<object>One to 10 windows on this day, which can't overlap.
startstringThe start of the window, as a local time in 24-hour HH:MM format.
endstringThe end of the window, as a local time in HH:MM format, later than start. Use 24:00 for the end of the day.
modestring(Scheduled)scheduled: The campaign dials from start until end.
timezonestring(Scheduled)The IANA time zone for start, end, and days, for example America/New_York. Daylight saving time is handled automatically.
startstring(Scheduled)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)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.
weekdaystringThe day of the week. Each day can appear only once.
rangesarray<object>One to 10 windows on this day, which can't overlap.
startstringThe start of the window, as a local time in 24-hour HH:MM format.
endstringThe end of the window, as a local time in HH:MM format, later than start. Use 24:00 for the end of the day.
lifecycleobjectThe lifecycle settings for each session the campaign starts. They replace the saved settings, and fields you omit use their defaults.
idle_timeout_msintegerHow long in milliseconds the session continues with no participant present: after the subscribed user leaves the RTC channel, or after the other side of a phone call hangs up. It isn't silence detection. Set to 0 to turn off the idle timer. Can't be greater than max_duration_ms.
max_duration_msintegerThe maximum length of each session in milliseconds, measured from start_ts. Defaults to 5 minutes. The maximum is 1 hour.
graceful_stopobjectHow the agent finishes when you stop the session, or when the idle timer expires. It doesn't extend max_duration_ms, and it doesn't add a farewell message.
enabledbooleanWhether the agent finishes what it's saying before it leaves.
timeout_msintegerThe longest time in milliseconds the agent can take to finish.
transportobjectThe transport settings that can change. You can't change type or from.
call_policyobjectLimits and behavior for each call the campaign places. Each limit you omit adds no limit.
max_ring_duration_msintegerThe maximum time in milliseconds from starting the dial until the call is answered. If the call isn't answered in time, the dial attempt ends.
max_call_duration_secondsintegerThe maximum length of the call in seconds, measured from when it's answered. The session's lifecycle limits can end the call earlier.
max_silence_duration_msintegerHang up when nobody on the call has spoken for this many milliseconds. This is separate from pipeline.silence_config, which only prompts the user.
end_callobjectConditions under which the agent can end the call itself. Every condition is off unless you set it to true.
on_user_requestbooleanEnd the call when the caller clearly says goodbye or asks to hang up.
on_voicemailbooleanEnd the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
on_ai_assistantbooleanEnd the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
Response Body
The campaign was updated. The response body contains the full campaign.
Response Headers
campaign_idstringThe ID of the campaign, a UUID.
namestringThe name of the campaign.
statusstringThe 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 infailure.
agent_idstringThe ID of the agent that makes the calls.
transportobjecttypestringAlways telephony.
fromarray<string>The number_id values of the numbers the campaign calls from.
call_policyobjectLimits and behavior for each call the campaign places. Each limit you omit adds no limit.
max_ring_duration_msintegerThe maximum time in milliseconds from starting the dial until the call is answered. If the call isn't answered in time, the dial attempt ends.
max_call_duration_secondsintegerThe maximum length of the call in seconds, measured from when it's answered. The session's lifecycle limits can end the call earlier.
max_silence_duration_msintegerHang up when nobody on the call has spoken for this many milliseconds. This is separate from pipeline.silence_config, which only prompts the user.
end_callobjectConditions under which the agent can end the call itself. Every condition is off unless you set it to true.
on_user_requestbooleanEnd the call when the caller clearly says goodbye or asks to hang up.
on_voicemailbooleanEnd the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
on_ai_assistantbooleanEnd the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
lifecycleobjectWhen each session the campaign starts ends on its own.
idle_timeout_msintegerHow long in milliseconds the session continues with no participant present: after the subscribed user leaves the RTC channel, or after the other side of a phone call hangs up. It isn't silence detection. Set to 0 to turn off the idle timer. Can't be greater than max_duration_ms.
max_duration_msintegerThe maximum length of each session in milliseconds, measured from start_ts. Defaults to 5 minutes. The maximum is 1 hour.
graceful_stopobjectHow the agent finishes when you stop the session, or when the idle timer expires. It doesn't extend max_duration_ms, and it doesn't add a farewell message.
enabledbooleanWhether the agent finishes what it's saying before it leaves.
timeout_msintegerThe longest time in milliseconds the agent can take to finish.
scheduleImmediate | ScheduledWhen the campaign dials. Pass the fields of one schedule mode only.
modestring(Immediate)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.
weekdaystringThe day of the week. Each day can appear only once.
rangesarray<object>One to 10 windows on this day, which can't overlap.
startstringThe start of the window, as a local time in 24-hour HH:MM format.
endstringThe end of the window, as a local time in HH:MM format, later than start. Use 24:00 for the end of the day.
modestring(Scheduled)scheduled: The campaign dials from start until end.
timezonestring(Scheduled)The IANA time zone for start, end, and days, for example America/New_York. Daylight saving time is handled automatically.
startstring(Scheduled)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)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.
weekdaystringThe day of the week. Each day can appear only once.
rangesarray<object>One to 10 windows on this day, which can't overlap.
startstringThe start of the window, as a local time in 24-hour HH:MM format.
endstringThe end of the window, as a local time in HH:MM format, later than start. Use 24:00 for the end of the day.
countsobjectThe number of contacts in each state. Retrieve the campaign to get current counts.
contactsintegerThe total number of contacts.
pendingintegerContacts not called yet, or waiting for a retry.
callingintegerContacts in a call now.
completedintegerContacts whose call has finished.
failedintegerContacts not reached after all attempts.
canceledintegerContacts that won't be called because the campaign was canceled.
create_tsintegerThe time the campaign was created, as a Unix timestamp in seconds.
start_tsinteger | nullThe time the campaign started dialing, as a Unix timestamp in seconds. null before it starts.
complete_tsinteger | nullThe time the campaign finished, as a Unix timestamp in seconds. null until it finishes.
failureobject | nullDetails of the failure when status is failed. Otherwise null.
codestring(object)A stable runtime error code, for example provider_error.
providerstring(object)The model provider that caused the failure, for example openai.
messagestring(object)A human-readable explanation.
tsinteger(object)The time the failure occurred, as a Unix timestamp in seconds.
Request examples
curl -X PATCH 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/campaigns/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'If-Match: string' \ -H 'Content-Type: application/json' \ -d '{ "pacing": { "max_concurrent": 20 }}'Response example
{ "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904", "name": "string", "status": "scheduled", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "transport": { "type": "telephony", "from": [ "string" ], "call_policy": { "max_ring_duration_ms": 1, "max_call_duration_seconds": 1, "max_silence_duration_ms": 30000, "end_call": { "on_user_request": false, "on_voicemail": false, "on_ai_assistant": false } } }, "lifecycle": { "idle_timeout_ms": 30000, "max_duration_ms": 300000, "graceful_stop": { "enabled": false, "timeout_ms": 30000 } }, "schedule": { "mode": "immediate", "timezone": "string", "days": [ { "weekday": "mon", "ranges": [ { "start": "string", "end": "string" } ] } ] }, "counts": { "contacts": 0, "pending": 0, "calling": 0, "completed": 0, "failed": 0, "canceled": 0 }, "create_ts": 0, "start_ts": 0, "complete_ts": 0, "failure": { "code": "string", "provider": "string", "message": "string", "ts": 0 }}