TelephonyCampaigns

Create or replace a failed telephony campaign

PUT /agents/{agent_name}/telephony_campaigns/{campaign_name}

Creates a Campaign or fully replaces failed preparation; no PATCH. All recipients must validate and have CallJobs before dialing. Immediate calls may begin before the preparation poller returns.

Header parameters

Foundry-Features enum required

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

VoiceAgents=V1Preview

Operation-Id string

Retry key: matching submitted inputs and original If-Match replay the saved monitor before current-state checks. Conflicting reuse returns 409 operation_id_conflict; retained creation keys after deletion return 409 campaign_deleted.

If-Match string

Required with a fresh Operation-Id for failed-state replacement; no wildcards. Changed input without it returns 409. Missing replacement ID: 400; stale token/absent resource: 412; other states: 409.

Path parameters

agent_name string required

Owning Agent; never overridden in recipient inputs.

campaign_name string required

Name chosen by the caller; only a failed Campaign permits full replacement.

Query parameters

api-version string required

The API version to use for this operation.

Request Body

Complete connection, source, recipients/Dataset, schedule and retry configuration. Omitted optional fields reset to defaults; Agent/name and response-only fields cannot change.

Content-Type: application/json

connection_name string required

Human-readable name of the provider connection in the current project.

source phone_number | teams | sip required

Shared source, recipient and transfer address. Connections validate each role before dialing; unsupported types fail. New types may be added.

One of the following:

phone_number PhoneNumber

Phone-number address used by supported source and destination roles.

type enum required

The phone-number address type.

phone_number

value string required

E.164 phone number.

teams TeamsAddress

Teams source/transfer identity, validated by role and provider. Not supported for outbound recipients.

type enum required

The Microsoft Teams address type.

teams

value string required

Source: nonempty resource-account GUID. Transfer: user/resource-account GUID or 28:orgid:{guid}.

sip SipAddress

SIP/SIPS transfer address, subject to provider validation. SIP outbound sources and recipients use phone_number, not SIP URIs.

type enum required

The SIP address type.

sip

value string required

The SIP or SIPS URI to call.

recipients TelephonyRecipient[]

1-100 recipients, exclusive with recipient_dataset. The whole UTF-8 request is limited to 1 MiB. Omitted from reads; retain the submission for row correlation.

recipient_dataset DatasetReference

Reference to a Foundry Dataset in the current project. Consuming operations define supported Dataset kinds and resolution behavior.

name string required

Dataset name.

version string

Optional Dataset version. Omit to select latest when the consuming operation resolves the reference.

schedule immediate | scheduled | recipient

Creation authorizes dialing; every scheduling mode waits for successful preparation.

One of the following:

immediate ImmediateSchedule

Dispatch automatically as soon as preparation succeeds and capacity permits.

type enum required

Identifies immediate scheduling after successful preparation.

immediate

scheduled AtTimeSchedule

Uses one earliest dispatch time for all recipients. Past times are allowed; preparation must still succeed.

type enum required

Identifies scheduling with one common earliest dispatch time.

scheduled

scheduled_at integer required

recipient PerRecipientSchedule

Uses each recipient's scheduled_at: RFC 3339 with timezone in Datasets, Unix seconds for inline recipients.

type enum required

Identifies scheduling with a separate earliest dispatch time for each recipient.

recipient

retry_policy fixed_interval

The retry policy for one durable outbound call intent. max_attempts includes the first attempt. Strategy-specific settings are defined by the derived policy.

One of the following:

fixed_interval FixedIntervalRetryPolicy

Shared direct-call/Campaign retry policy. Omission means one attempt; CallJobs return max_attempts=1 and interval=0 seconds.

type enum required

The fixed-interval retry strategy.

fixed_interval

interval integer required

A duration encoded as an integer number of seconds.

Responses

The request has succeeded.

Headers

Cache-Control enum required

Prevents caches from treating the control token as a validator for changing progress.

no-store

Location string required

URI of the Campaign business resource.

Operation-Location string required

Preparation monitor URI, including api-version. Completion does not mean all calls have finished.

Operation-Id string required

This request's preparation ID, unchanged on retries; may differ from Campaign.operation_id.

Retry-After integer required

Suggested polling delay in seconds.

Body

Content-Type: application/json

connection_name string required

Human-readable name of the provider connection in the current project.

source phone_number | teams | sip required

Shared source, recipient and transfer address. Connections validate each role before dialing; unsupported types fail. New types may be added.

One of the following:

phone_number PhoneNumber

Phone-number address used by supported source and destination roles.

type enum required

The phone-number address type.

phone_number

value string required

E.164 phone number.

teams TeamsAddress

Teams source/transfer identity, validated by role and provider. Not supported for outbound recipients.

type enum required

The Microsoft Teams address type.

teams

value string required

Source: nonempty resource-account GUID. Transfer: user/resource-account GUID or 28:orgid:{guid}.

sip SipAddress

SIP/SIPS transfer address, subject to provider validation. SIP outbound sources and recipients use phone_number, not SIP URIs.

type enum required

The SIP address type.

sip

value string required

The SIP or SIPS URI to call.

recipient_dataset DatasetReference

Reference to a Foundry Dataset in the current project. Consuming operations define supported Dataset kinds and resolution behavior.

name string required

Dataset name.

version string

Optional Dataset version. Omit to select latest when the consuming operation resolves the reference.

schedule immediate | scheduled | recipient

Creation authorizes dialing; every scheduling mode waits for successful preparation.

One of the following:

immediate ImmediateSchedule

Dispatch automatically as soon as preparation succeeds and capacity permits.

type enum required

Identifies immediate scheduling after successful preparation.

immediate

scheduled AtTimeSchedule

Uses one earliest dispatch time for all recipients. Past times are allowed; preparation must still succeed.

type enum required

Identifies scheduling with one common earliest dispatch time.

scheduled

scheduled_at integer required

recipient PerRecipientSchedule

Uses each recipient's scheduled_at: RFC 3339 with timezone in Datasets, Unix seconds for inline recipients.

type enum required

Identifies scheduling with a separate earliest dispatch time for each recipient.

recipient

retry_policy fixed_interval

The retry policy for one durable outbound call intent. max_attempts includes the first attempt. Strategy-specific settings are defined by the derived policy.

One of the following:

fixed_interval FixedIntervalRetryPolicy

Shared direct-call/Campaign retry policy. Omission means one attempt; CallJobs return max_attempts=1 and interval=0 seconds.

type enum required

The fixed-interval retry strategy.

fixed_interval

interval integer required

A duration encoded as an integer number of seconds.

status string | enum required

Campaign execution state, separate from preparation/cancel/delete LROs. All recipients terminal means completed, not necessarily successful.

Any of the following:

string

enum

validatingrunningcancellingcompletedfailedcancelleddeleting

error OpenAI.Error

code string | null required

message string required

param string | null

type string

misalignment OpenAI.MisalignmentErrorDetailsResource

review_target string | null

error_type string | enum

Any of the following:

string

enum

potentially_unintended_data_transferpotentially_unintended_data_accesspotentially_unintended_destructive_activityother

detailed_explanation string

The public explanation for this block.

steer OpenAI._MisalignmentSteer

message string required

The public continuation instruction.

details OpenAI.Error[]

Additional errors that contributed to this failure.

additionalInfo object

Additional structured information about the failure.

debugInfo object

Diagnostic information supplied by the service for troubleshooting.

name string required

Immutable customer-chosen Campaign name within a project and Agent.

created_at integer required

updated_at integer required

etag string required

The ETag (or entity tag) HTTP response header is an identifier for a specific version of a resource. It lets caches be more efficient and save bandwidth, as a web server does not need to resend a full response if the content was not changed. It is a string of ASCII characters placed between double quotes, like "675af34563dc-tr34".

operation_id string required

Latest accepted action, for discovery only. Poll the initiating response's Operation-Id/Operation-Location instead.

finished_at integer

locked_agent_version string

Latest Agent version pinned once per preparation and shared by retries/calls. Omitted until resolved; replacement clears it. Unavailable pins fail without fallback.

progress TelephonyCampaignProgress required

Recipient execution counts, zero until preparation succeeds; then mutually exclusive and summing to total_recipients.

total_recipients integer

Total input rows, including invalid rows. Omitted until known; never an estimate.

pending integer required

Recipients waiting for their schedule, capacity or retry after preparation has completed.

active integer required

Recipients with a durable origination reservation or unresolved provider attempt, including dispatching before a call ID is received.

completed integer required

Recipients whose CallJob completed; not proof of business success.

failed integer required

Recipients whose CallJob exhausted retries or failed.

cancelled integer required

Recipients cancelled before completion. Does not include dispatch-window expiry.

expired integer required

Recipients whose dispatch deadline elapsed before a new attempt could start.

The request has succeeded and a new resource has been created as a result.

Headers

Cache-Control enum required

Prevents caches from treating the control token as a validator for changing progress.

no-store

Location string required

URI of the Campaign business resource.

Operation-Location string required

Preparation monitor URI, including api-version. Completion does not mean all calls have finished.

Operation-Id string required

This request's preparation ID, unchanged on retries; may differ from Campaign.operation_id.

Retry-After integer required

Suggested polling delay in seconds.

Body

Content-Type: application/json

connection_name string required

Human-readable name of the provider connection in the current project.

source phone_number | teams | sip required

Shared source, recipient and transfer address. Connections validate each role before dialing; unsupported types fail. New types may be added.

One of the following:

phone_number PhoneNumber

Phone-number address used by supported source and destination roles.

type enum required

The phone-number address type.

phone_number

value string required

E.164 phone number.

teams TeamsAddress

Teams source/transfer identity, validated by role and provider. Not supported for outbound recipients.

type enum required

The Microsoft Teams address type.

teams

value string required

Source: nonempty resource-account GUID. Transfer: user/resource-account GUID or 28:orgid:{guid}.

sip SipAddress

SIP/SIPS transfer address, subject to provider validation. SIP outbound sources and recipients use phone_number, not SIP URIs.

type enum required

The SIP address type.

sip

value string required

The SIP or SIPS URI to call.

recipient_dataset DatasetReference

Reference to a Foundry Dataset in the current project. Consuming operations define supported Dataset kinds and resolution behavior.

name string required

Dataset name.

version string

Optional Dataset version. Omit to select latest when the consuming operation resolves the reference.

schedule immediate | scheduled | recipient

Creation authorizes dialing; every scheduling mode waits for successful preparation.

One of the following:

immediate ImmediateSchedule

Dispatch automatically as soon as preparation succeeds and capacity permits.

type enum required

Identifies immediate scheduling after successful preparation.

immediate

scheduled AtTimeSchedule

Uses one earliest dispatch time for all recipients. Past times are allowed; preparation must still succeed.

type enum required

Identifies scheduling with one common earliest dispatch time.

scheduled

scheduled_at integer required

recipient PerRecipientSchedule

Uses each recipient's scheduled_at: RFC 3339 with timezone in Datasets, Unix seconds for inline recipients.

type enum required

Identifies scheduling with a separate earliest dispatch time for each recipient.

recipient

retry_policy fixed_interval

The retry policy for one durable outbound call intent. max_attempts includes the first attempt. Strategy-specific settings are defined by the derived policy.

One of the following:

fixed_interval FixedIntervalRetryPolicy

Shared direct-call/Campaign retry policy. Omission means one attempt; CallJobs return max_attempts=1 and interval=0 seconds.

type enum required

The fixed-interval retry strategy.

fixed_interval

interval integer required

A duration encoded as an integer number of seconds.

status string | enum required

Campaign execution state, separate from preparation/cancel/delete LROs. All recipients terminal means completed, not necessarily successful.

Any of the following:

string

enum

validatingrunningcancellingcompletedfailedcancelleddeleting

error OpenAI.Error

code string | null required

message string required

param string | null

type string

misalignment OpenAI.MisalignmentErrorDetailsResource

review_target string | null

error_type string | enum

Any of the following:

string

enum

potentially_unintended_data_transferpotentially_unintended_data_accesspotentially_unintended_destructive_activityother

detailed_explanation string

The public explanation for this block.

steer OpenAI._MisalignmentSteer

message string required

The public continuation instruction.

details OpenAI.Error[]

Additional errors that contributed to this failure.

additionalInfo object

Additional structured information about the failure.

debugInfo object

Diagnostic information supplied by the service for troubleshooting.

name string required

Immutable customer-chosen Campaign name within a project and Agent.

created_at integer required

updated_at integer required

etag string required

operation_id string required

Latest accepted action, for discovery only. Poll the initiating response's Operation-Id/Operation-Location instead.

finished_at integer

locked_agent_version string

Latest Agent version pinned once per preparation and shared by retries/calls. Omitted until resolved; replacement clears it. Unavailable pins fail without fallback.

progress TelephonyCampaignProgress required

Recipient execution counts, zero until preparation succeeds; then mutually exclusive and summing to total_recipients.

total_recipients integer

Total input rows, including invalid rows. Omitted until known; never an estimate.

pending integer required

Recipients waiting for their schedule, capacity or retry after preparation has completed.

active integer required

Recipients with a durable origination reservation or unresolved provider attempt, including dispatching before a call ID is received.

completed integer required

Recipients whose CallJob completed; not proof of business success.

failed integer required

Recipients whose CallJob exhausted retries or failed.

cancelled integer required

Recipients cancelled before completion. Does not include dispatch-window expiry.

expired integer required

Recipients whose dispatch deadline elapsed before a new attempt could start.