Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
A voice agent in Microsoft Foundry can contact one recipient through a call job or a group of recipients through a campaign. This article uses appointment reminders to show both paths with the same agent, provider connection, and customer inputs.
Configure the agent once, test a reminder call, and then reuse the setup for a campaign. The agent confirms the appointment and ends after its farewell. Your application controls scheduling, monitors outcomes, and cancels pending calls and retries.
Use Choose a configuration method at the top of this article to select Python SDK or REST API.
Voice agents are generally available, with some features still in preview. See General availability and preview features. Campaigns and calls over SIP connections are in preview.
Caution
Outbound calls and campaigns aren't currently supported for voice agents in network-isolated projects, such as projects that use virtual network injection or a Foundry resource with public network access disabled. They depend on telephony channels, which aren't supported in these projects.
Prerequisites
- A Foundry project with a voice-capable model and access to outbound calling.
- Permission to create agents and use the project's call-job and campaign operations.
- A supported telephony connection in your project and a caller identity configured for that provider. See Choose the caller and destination.
- For a recipient file, permission to create and read datasets in the project. Follow Use a dataset for a larger batch to prepare and upload the file.
Prepare the reminder agent
Use one agent and provider connection for the individual call and campaign examples. If you already have a tested setup with equivalent inputs, continue to Place one call or Create a campaign.
Set up your preferred interface
Prepare the client or access token for your selected configuration method.
Install the packages and sign in by following the Python setup.
Replace the endpoint, then run this setup once in your Python session. The following examples reuse these clients and the agent name.
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>"
agent_name = "contoso-outbound-reminders"
credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
telephony = project_client.voice_agents.telephony
campaigns = project_client.beta.voice_agents.telephony
Reference: AIProjectClient | DefaultAzureCredential.
The telephony client manages individual call jobs and bindings. The campaigns client comes from the beta namespace and sends the Foundry-Features: VoiceAgents=V1Preview opt-in that campaign operations require.
After running the examples you need, close project_client and credential with their close() methods.
The requests in this article need your project endpoint and an access token. Complete the REST setup to get both.
- Copy your Foundry project endpoint. It looks like
https://<account>.services.ai.azure.com/api/projects/<project>. - In each request, replace
{projectEndpoint}with that endpoint and<access-token>with your token.
Campaign requests include the Foundry-Features: VoiceAgents=V1Preview header because campaigns are in preview.
Choose the caller and destination
Choose your provider to configure the connection and caller identity. All providers use the recipient's E.164 phone number as the destination.
Run the settings for your provider once. The call-job and campaign examples reuse connection_name and source.
Use your Twilio project connection and an E.164 caller number authorized for that connection:
from azure.ai.projects.models import PhoneNumber
connection_name = "contoso-twilio"
source = PhoneNumber(value="+14255550100")
Replace the example connection and caller identity with your values. Use PhoneNumber(value="+14255550123") for the destination, replacing the number with your recipient's number.
Use the settings for your provider in the call-job and campaign request bodies:
Use your Twilio project connection and an E.164 caller number authorized for that connection:
{
"connection_name": "contoso-twilio",
"source": { "type": "phone_number", "value": "+14255550100" }
}
The complete REST examples use contoso-twilio and +14255550100. Replace connection_name and source in each call-job or campaign request with your selected settings. Use "destination": {"type":"phone_number","value":"+14255550123"} for every provider, replacing the number with your recipient's number.
Set connection_name to the project connection name, not a resource ID or URL. Don't send provider, telephony_binding_id, or the legacy connection field in a call-job request.
Create the reminder agent
The example agent uses a template greeting, two customer inputs, and end_conversation. Replace the model and voice with supported choices in your project.
To save transcripts and audio for later review, enable conversation storage by setting store: true in the agent definition. See Voice agent observability for access and retention settings.
Create the reminder agent with its greeting, input definitions, and conversation-ending tool:
from azure.ai.projects.models import (
StructuredInputDefinition,
VoiceAgentAudioConfig,
VoiceAgentAudioOutputConfig,
VoiceAgentDefinition,
VoiceAgentEndConversationSystemTool,
VoiceAgentTemplateGreetingConfig,
)
agent_version = project_client.agents.create_version(
agent_name=agent_name,
definition=VoiceAgentDefinition(
sub_protocol="realtime",
model_type="managed",
model="gpt-4.1",
instructions=(
"You are Contoso's appointment reminder assistant. "
"Confirm that you are speaking with {{customer_name}} and that "
"now is a good time. Then explain the appointment at "
"{{appointment_time}}. When the conversation is complete, "
"say goodbye and use end_conversation in the same response."
),
greeting=VoiceAgentTemplateGreetingConfig(
text=(
"Hello, this is Contoso's virtual assistant calling for "
"{{customer_name}}. Is now a good time?"
),
),
audio=VoiceAgentAudioConfig(
output=VoiceAgentAudioOutputConfig(
voice_type="azure-standard",
voice="en-US-AvaMultilingualNeural",
),
),
structured_inputs={
"customer_name": StructuredInputDefinition(
schema={"type": "string"}, required=True,
),
"appointment_time": StructuredInputDefinition(
schema={"type": "string"}, required=True,
),
},
tool_choice="auto",
tools=[VoiceAgentEndConversationSystemTool()],
),
)
print(agent_version.name, agent_version.version)
Reference: AgentsOperations.create_version.
Review the instructions in the request. They confirm the recipient and appointment, then end the conversation after a farewell.
Create
contoso-outbound-reminders:POST {projectEndpoint}/agents?api-version=v1 Authorization: Bearer <access-token> Content-Type: application/json { "name": "contoso-outbound-reminders", "definition": { "kind": "voice", "sub_protocol": "realtime", "model_type": "managed", "model": "gpt-4.1", "instructions": "You are Contoso's appointment reminder assistant.\nConfirm that you are speaking with {{customer_name}} and that now is a\ngood time. Then explain the appointment at {{appointment_time}}.\nWhen the conversation is complete, say goodbye and use end_conversation\nin the same response.", "greeting": { "type": "template", "text": "Hello, this is Contoso's virtual assistant calling for {{customer_name}}. Is now a good time?" }, "audio": { "output": { "voice_type": "azure-standard", "voice": "en-US-AvaMultilingualNeural" } }, "structured_inputs": { "customer_name": { "schema": { "type": "string" }, "required": true }, "appointment_time": { "schema": { "type": "string" }, "required": true } }, "tool_choice": "auto", "tools": [ { "type": "system", "name": "end_conversation" } ] } }Check the successful response and save the agent name and version. The example creates
contoso-outbound-reminders; use that name wherever later requests show{agentName}.
The service executes the configured system tools during the conversation. Your application supplies the recipient and appointment data when it creates the call job.
Supply conversation inputs
The agent definition declares two required string inputs. Supply values for each call or campaign recipient:
| Input | Used for |
|---|---|
customer_name |
Personalizes the greeting and identifies the intended recipient. |
appointment_time |
Provides the appointment details for the reminder. |
The service validates supplied values against the agent's input definitions. Optional inputs in your own agents can use configured defaults, and their schemas can allow nested JSON values.
Direct calls use the agent version configured for the endpoint. Campaigns select the latest agent version during preparation and use it for all calls and retries.
Place one call
Create a direct call job for one test recipient, then check the conversation outcome. To choose a future calling window, add a schedule and retry policy to the request before submitting it.
Create one call job
Submit the reminder and save the job ID so you can check its progress. Replace the connection, caller identity, and destination with your values. You can also set the optional purpose field to describe why you're placing the call.
Generate a request key and prepare the call. Save the key and request body in your application before submitting the job:
from uuid import uuid4 from azure.ai.projects.models import PhoneNumber, TelephonyCallJobCreate request_key = str(uuid4()) call_request = TelephonyCallJobCreate( connection_name=connection_name, source=source, destination=PhoneNumber(value="+14255550123"), structured_inputs={ "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM", }, )Submit the request and save the returned job ID. The callback also captures the response headers for status polling:
job, job_headers = telephony.create_call_job( agent_name=agent_name, job=call_request, idempotency_key=request_key, cls=lambda response, result, _: (result, response.http_response.headers), ) call_job_id = job.id retry_after = int(job_headers["Retry-After"]) print(call_job_id, job.status)Reuse
request_keyandcall_requestwhen retrying an uncertain submission.
Reference: Azure AI Projects client library for Python.
Generate an
Idempotency-Keyfor this call and save it with the original request body. Reuse both when retrying an uncertain submission.Create the job with the two inputs declared by the reminder agent:
POST {projectEndpoint}/agents/contoso-outbound-reminders/telephony_call_jobs?api-version=v1 Authorization: Bearer <access-token> Content-Type: application/json Idempotency-Key: <stable-reminder-request-key> { "connection_name": "contoso-twilio", "source": { "type": "phone_number", "value": "+14255550100" }, "destination": { "type": "phone_number", "value": "+14255550123" }, "structured_inputs": { "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM" } }Read the
202 Acceptedresponse and save the jobidand these headers:Header Save it for LocationReading this call job. ETagConditional cancellation. Read again before a later cancellation. Retry-AfterWaiting between status reads. The value is in seconds.
The acceptance response confirms that the service saved the job. With the default schedule, it becomes eligible to call immediately, subject to capacity. Answer the test call and confirm that the agent uses the supplied name and appointment time.
| Stage | Expected result |
|---|---|
| Connection | The agent greets the named recipient and asks whether it's a good time. |
| Reminder | The agent explains the supplied appointment details. |
| Completion | The agent speaks its farewell and uses end_conversation to close the call. |
An equivalent request with the same idempotency key returns the original job. Use a new key for each new call you intend to place. Changed requests and previously deleted jobs are covered in Troubleshoot.
Monitor the job
Read the job to follow each attempt and learn when calling finishes.
Read the job at the service's polling interval until it reaches a terminal state:
import time
terminal_statuses = {"completed", "blocked", "expired", "failed", "cancelled"}
while job.status not in terminal_statuses:
time.sleep(retry_after)
job, job_headers = telephony.get_call_job(
agent_name=agent_name,
call_job_id=call_job_id,
cls=lambda response, result, _: (
result, response.http_response.headers
),
)
retry_after = int(job_headers.get("Retry-After", retry_after))
print(job.status, job.attempt_count, job.terminal_reason)
Reference: Azure AI Projects client library for Python.
Wait for the creation response's
Retry-Afterinterval.Follow the returned
Location, or read by the job ID:GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs/{callJobId}?api-version=v1 Authorization: Bearer <access-token>Continue reading at the interval returned by creation, using any newer
Retry-Aftervalue if supplied. Inspectstatus,attempt_count,next_attempt_at, andterminal_reason.
| Status | Meaning |
|---|---|
accepted |
The service saves the call job for processing. |
waiting_for_schedule |
The job is waiting until its schedule.not_before time. |
queued |
The job is waiting for the service to start a call attempt. |
dispatching |
The service is preparing or submitting a call attempt and resolving its submission outcome. |
in_progress |
The provider accepted the call attempt. The call can be ringing or connected. |
waiting_for_retry |
The job is waiting until next_attempt_at to start another attempt. |
cancellation_requested |
The service is processing cancellation. Continue polling the job for its outcome. |
completed |
Calling is complete. Review terminal_reason and conversation data for the outcome. |
blocked |
A configuration or validation issue stops further attempts. Read terminal_reason for details. |
expired |
The deadline for starting new attempts is reached. |
failed |
Processing ends with an error or an unresolved provider result. Read terminal_reason for details. |
cancelled |
Cancellation is complete. |
completed, blocked, expired, failed, and cancelled are terminal job states. A completed job can report no_answer when its permitted attempts are exhausted. Read terminal_reason together with status to understand the result.
attempt_count reports how many attempts have started. Keep the job ID and request details with your application logs when investigating an attempt.
For scheduled calls, use schedule.not_before to check when the first attempt becomes eligible.
To transfer or end an active call, find its call record and use the call ID. Use the call-job API to manage scheduling, retries, and cancellation of future attempts.
Create a campaign
Campaigns are in preview. A campaign validates a recipient batch, creates a call job for each entry, and starts eligible calls automatically. Reuse the tested reminder agent and connection. To call later, include a campaign schedule in the creation request.
Create a campaign with inline recipients
Start with a small batch of recipients supplied directly in the request body. Use the same provider connection and caller identity as the individual call. Supply customer_name and appointment_time for each recipient.
Prepare the campaign and generate an operation ID. Save both in your application so you can recover an interrupted submission:
from uuid import uuid4 from azure.ai.projects.models import ( PhoneNumber, TelephonyCampaign, TelephonyRecipient, ) campaign_name = "appointment-reminders" operation_id = str(uuid4()) campaign_request = TelephonyCampaign( connection_name=connection_name, source=source, recipients=[ TelephonyRecipient( destination=PhoneNumber(value="+14255550123"), structured_inputs={ "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM", }, ), TelephonyRecipient( destination=PhoneNumber(value="+14255550124"), structured_inputs={ "customer_name": "Sam", "appointment_time": "Tuesday at 11 AM", }, ), ], )Create the campaign and wait for preparation to complete:
campaign = campaigns.begin_create( agent_name=agent_name, campaign_name=campaign_name, campaign=campaign_request, operation_id=operation_id, ).result() print(campaign.name, campaign.status)The poller follows the preparation operation and returns the campaign. Read the campaign and its call jobs to follow calling progress.
Reference: AIProjectClient.
Choose a campaign name unique within the project and agent. Names are case-sensitive, contain 1–64 letters, digits, underscores, or hyphens, and start with a letter or digit.
Generate and save an
Operation-Idfor this request. Keep the original request body with it. If the response is lost or interrupted, reuse both values to recover the same campaign creation.Submit the campaign with your connection, caller identity, and recipient phone numbers:
PUT {projectEndpoint}/agents/{agentName}/telephony_campaigns/appointment-reminders?api-version=v1 Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1Preview Content-Type: application/json Operation-Id: <stable-create-operation-id> { "connection_name": "contoso-twilio", "source": { "type": "phone_number", "value": "+14255550100" }, "recipients": [ { "destination": { "type": "phone_number", "value": "+14255550123" }, "structured_inputs": { "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM" } }, { "destination": { "type": "phone_number", "value": "+14255550124" }, "structured_inputs": { "customer_name": "Sam", "appointment_time": "Tuesday at 11 AM" } } ] }Replace the connection, numbers, and appointment details with your values. The reminder agent's input definitions apply to each entry.
Choose one recipient source:
recipientsfor an inline array orrecipient_datasetfor a dataset reference. Place that property at the top level of the request body.Inline arrays support 1–100 recipients within the total 1 MiB decoded UTF-8 request limit.
Each entry creates a separate call job, including entries that repeat a phone number. Each recipient's
structured_inputsfollow the agent's required fields, defaults, and input schemas.Read the response. An initial create returns
201 Createdwith a campaign invalidating. Save these values:Response value Purpose LocationheaderRead the campaign's configuration and progress. Operation-LocationheaderPoll this specific validation operation. Operation-IdheaderIdentify this request when retrying or checking its progress. Retry-AfterheaderWait this many seconds between operation reads. Body etagProtect a later update, cancellation, or deletion from concurrent changes. Read the campaign again before using it.
During preparation, the service selects the latest agent version and keeps it for the campaign's calls and retries. It validates the recipients and creates a call job for each entry before calling begins.
Successful preparation automatically starts eligible calls. Immediate calls can therefore begin while your application is still polling validation status. If preparation fails, the campaign remains available for correction and its call jobs stay inactive.
Use a dataset for a larger batch
Create a dataset in the same Foundry project by uploading a recipient file. The following steps create appointment-recipients, version 1, and use it in a campaign. Use a single CSV, JSON array, or JSONL file.
Save your recipient list as
recipients.csv. This example supplies the same two inputs as the inline recipients:destination_type,destination_value,customer_name,appointment_time phone_number,+14255550123,Alex,Tuesday at 10 AM phone_number,+14255550124,Sam,Tuesday at 11 AMYou can also save the same recipients as
recipients.jsonl:{"destination_type":"phone_number","destination_value":"+14255550123","customer_name":"Alex","appointment_time":"Tuesday at 10 AM"} {"destination_type":"phone_number","destination_value":"+14255550124","customer_name":"Sam","appointment_time":"Tuesday at 11 AM"}destination_typeanddestination_valueidentify the recipient's address. Usephone_numberwith an E.164 value.scheduled_atis reserved for per-recipient scheduling; other fields become agent inputs.CSV cells remain strings, including leading zeros and empty strings. JSON and JSONL preserve nested objects, arrays, numbers, booleans, and null. Choose the format that matches the agent's input schemas and use unique column headers or property names.
Create the dataset by uploading the file with the Azure AI Projects client library. Install the packages and sign in as described in the Python setup. Replace the endpoint, and run this example from the folder containing
recipients.csv:from azure.ai.projects import AIProjectClient from azure.identity import DefaultAzureCredential upload_endpoint = ( "https://<account>.services.ai.azure.com/api/projects/<project>" ) with ( DefaultAzureCredential() as upload_credential, AIProjectClient( endpoint=upload_endpoint, credential=upload_credential, ) as upload_client, ): dataset = upload_client.datasets.upload_file( name="appointment-recipients", version="1", file_path="./recipients.csv", ) print(dataset.name, dataset.version)Reference: DatasetsOperations.upload_file.
The upload creates a
uri_filedataset and prints its name and version. It uses the project's default Azure Storage connection. To choose another storage connection, pass its name asconnection_nametoupload_file.For JSONL, change
file_pathto./recipients.jsonl. When you change the recipient file, upload it with a new dataset version.Use the returned name and version in the campaign creation request. Replace the inline
recipientsarray withrecipient_dataset.
Use a new campaign name and save a new operation ID for this batch:
from uuid import uuid4
from azure.ai.projects.models import (
TelephonyCampaign,
TelephonyCampaignDatasetReference,
)
campaign_name = "appointment-reminders-file"
operation_id = str(uuid4())
campaign_request = TelephonyCampaign(
connection_name=connection_name,
source=source,
recipient_dataset=TelephonyCampaignDatasetReference(
name=dataset.name,
version=dataset.version,
),
)
campaign = campaigns.begin_create(
agent_name=agent_name,
campaign_name=campaign_name,
campaign=campaign_request,
operation_id=operation_id,
).result()
print(campaign.name, campaign.status)
Reference: AIProjectClient.
{
"connection_name": "contoso-twilio",
"source": {
"type": "phone_number",
"value": "+14255550100"
},
"recipient_dataset": {
"name": "appointment-recipients",
"version": "1"
}
}
Submit this body with the campaign PUT request, using your connection and caller identity. Use a new campaign name and a fresh Operation-Id for this batch. The service validates the file and creates a call job for each recipient.
Supply version to select a specific dataset version, or omit it to select the latest version during preparation. The campaign uses that recipient data for its calls and retries.
Datasets support 1–1,000,000 recipients, up to 256 MiB of decoded content, and up to 1 MiB per logical row.
Keep your original recipient data to match results to submitted rows. Use the campaign's configuration and progress for a batch summary, and query its call jobs for individual recipients.
Poll validation and read execution progress
Use the validation operation to track preparation, then read the campaign to follow its calls. The service can continue processing a campaign while a status request fails. Use the saved operation ID to resume checking the existing operation.
The creation example waits for preparation with result(). Read the campaign again to refresh its execution state and recipient counts:
campaign = campaigns.get(
agent_name=agent_name,
campaign_name=campaign_name,
operation_id=operation_id,
)
print(campaign.status, campaign.progress.as_dict())
Reference: AIProjectClient.
Pass the creation operation_id to check that you're reading the campaign you submitted. Call get again when your application needs updated progress.
If result() reports an unsupported API version or another status-request error, read the operation directly:
operation = campaigns.get_operation(
agent_name=agent_name,
campaign_name=campaign_name,
operation_id=operation_id,
)
print(operation.status, operation.error)
Reference: AIProjectClient.
Repeat this read at the service's polling interval until the operation is succeeded, failed, or cancelled. After successful preparation, use the preceding campaigns.get example to read progress. For a failed operation, inspect operation.error and the campaign's validation errors.
Wait for the response's
Retry-Afterinterval. Read the operation using its savedOperation-Idandapi-version=v1:GET {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}/operations/{operationId}?api-version=v1 Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1PreviewOperation statuses are
queued,in_progress,succeeded,failed, andcancelled. A successful validation operation confirms that preparation is complete and eligible calls can start. The campaign's status and progress fields track the subsequent calls.Continue polling that operation until its status is terminal. If it fails, inspect its error and the campaign's validation errors.
After validation succeeds, read the campaign:
GET {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}?api-version=v1&operation_id={validationOperationId} Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1Preview
Use the optional operation_id query parameter to check that you're reading the campaign you submitted. If its configuration was replaced or its name was reused, the request returns 409 campaign_operation_mismatch.
If a returned Operation-Location reports an unsupported API version, use the preceding operation URL with api-version=v1 and the same operation ID. Each later cancellation or deletion has its own operation, and the campaign body's operation_id identifies the latest action.
Use the saved creation ID to recover preparation polling. For cancellation or deletion, use that action's saved operation ID instead. A successful deletion operation confirms completion; for creation or cancellation, read the campaign after the operation succeeds.
Inspect the campaign lifecycle and progress:
| Campaign status | Meaning |
|---|---|
validating |
The service is selecting versions, validating recipients, and creating jobs. Calls wait for preparation to finish. |
running |
Preparation succeeded; calls can be waiting for schedule, capacity, or retries. |
cancelling |
The service stops preparation and new attempts, then waits for calls already started to finish. |
completed |
Every recipient job is terminal, including jobs that failed or expired. |
failed |
Preparation failed. Review the errors and submit a corrected configuration; the batch's calls remain inactive. |
cancelled |
Cancellation is complete and all campaign work has stopped. |
deleting |
The service is deleting campaign data and its call-job records. |
progress reports total_recipients when known, plus pending, active, completed, failed, cancelled, and expired. The execution counts start at zero. After preparation succeeds, they account for every recipient and sum to total_recipients.
active includes jobs that are dispatching, in progress, or processing cancellation. failed includes failed and blocked jobs. completed counts finished jobs, including those with no_answer; use each job's terminal_reason to understand its calling outcome.
Use the campaign's progress for a batch summary and the call-job queries in the following section for each recipient's result.
Check each recipient's call-job status
After validation succeeds, query the jobs created for the campaign. The list returns each job's status, destination, input values, and attempt count.
Iterate over the campaign's jobs. The SDK reads subsequent pages automatically:
for recipient_job in telephony.list_call_jobs(
agent_name=agent_name,
campaign_name=campaign_name,
limit=100,
order="asc",
):
print(
recipient_job.id,
recipient_job.destination.value,
recipient_job.status,
recipient_job.attempt_count,
recipient_job.terminal_reason,
)
Reference: Azure AI Projects client library for Python.
Save each job's id to refresh it with get_call_job. Start a new list_call_jobs iteration to refresh the batch. Add status="failed" for a filtered view.
List the campaign's recipient jobs:
GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs?api-version=v1&campaign_name=appointment-reminders&limit=100&order=asc Authorization: Bearer <access-token>Replace
appointment-reminderswith your campaign name. The following illustrative response excerpt shows two recipient jobs:{ "data": [ { "id": "example-call-job-1", "campaign_name": "appointment-reminders", "destination": { "type": "phone_number", "value": "+14255550123" }, "structured_inputs": { "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM" }, "status": "in_progress", "attempt_count": 1 }, { "id": "example-call-job-2", "campaign_name": "appointment-reminders", "destination": { "type": "phone_number", "value": "+14255550124" }, "structured_inputs": { "customer_name": "Sam", "appointment_time": "Tuesday at 11 AM" }, "status": "completed", "attempt_count": 1, "terminal_reason": "no_answer" } ], "first_id": "example-call-job-1", "last_id": "example-call-job-2", "has_more": false }Track each job by
id, and usedestinationandstructured_inputsto match it to the recipient and reminder. In this example, Alex's call is in progress, while Sam's job finished withno_answer.If
has_moreistrue, uselast_idasafterto read the next page. Keep the same campaign and order:GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs?api-version=v1&campaign_name=appointment-reminders&limit=100&order=asc&after={lastId} Authorization: Bearer <access-token>To refresh one job, copy its returned
idinto{callJobId}:GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs/{callJobId}?api-version=v1 Authorization: Bearer <access-token>This request returns the job's current details. Use the same job status meanings for direct and campaign-created jobs.
To refresh the whole batch, start another list query from the first page and follow its pagination. Track updates by job ID until the jobs reach terminal states. For a focused view, add a filter such as
status=failedto the list request.
Diagnose preparation errors
Read row-level errors when preparation fails:
for validation_error in campaigns.list_validation_errors(
agent_name=agent_name,
campaign_name=campaign_name,
limit=20,
):
print(
validation_error.row_number,
validation_error.error.param,
validation_error.error.code,
validation_error.error.message,
)
Reference: AIProjectClient.
GET {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}/validation_errors?api-version=v1&limit=20
Authorization: Bearer <access-token>
Foundry-Features: VoiceAgents=V1Preview
Each error identifies the recipient's one-based row_number. Use error.param to locate the affected field and error.code to identify the validation issue. For CSV files, the first data row after the header is row 1.
For example, this response excerpt identifies a mismatch between row 1's inputs and the agent's declared input schemas:
{
"data": [
{
"row_number": 1,
"error": {
"code": "agent_structured_inputs_mismatch",
"message": "Recipient input is invalid for this Campaign.",
"param": "structured_inputs"
}
}
],
"has_more": false
}
Compare that row in your original input with the agent's required names and types. When the response includes agent_version, use that version's definition for the comparison.
During validating, errors become available as rows are processed. Check the validation operation's status to confirm completion. File-access and other preparation failures appear in the campaign's error; failures during calls appear in the individual jobs.
Add SMS confirmation (optional)
To offer an SMS confirmation during a call, use a telephony provider that supports the send_sms system tool. The following example uses Twilio.
Configure the SMS sender
The send_sms tool uses an SMS-capable number that's bound to the agent on the current call. In this example, the outbound call and SMS sender share the same Twilio connection and number.
If the sender number already has a binding to this agent, use that binding. Otherwise, create one and save its ID:
from azure.ai.projects.models import TwilioTelephonyBinding
binding = telephony.create_binding(
agent_name=agent_name,
binding=TwilioTelephonyBinding(
connection_name="contoso-twilio",
phone_number="+14255550100",
label="Contoso reminder sender",
),
)
print(binding.id)
Reference: Azure AI Projects client library for Python.
Use a number with voice and SMS capabilities. If you already bound that number to this agent, keep its existing binding. Otherwise, create one:
POST {projectEndpoint}/agents/contoso-outbound-reminders/telephony/bindings?api-version=v1 Authorization: Bearer <access-token> Content-Type: application/json { "provider": "twilio", "connection_name": "contoso-twilio", "phone_number": "+14255550100", "label": "Contoso reminder sender" }Save the binding ID returned with
201 Created. Use this connection and number as the caller for the SMS-enabled reminder.
Use a dedicated test number for this example. Creating a binding also routes incoming calls to this reminder agent, which expects the customer inputs supplied by a call job.
Enable SMS in the reminder agent
Update the reminder agent before placing calls that offer SMS. Keep the model, voice, greeting, and other settings from the base definition.
Use the Twilio connection and number from the sender binding for sms_call_request.connection_name and sms_call_request.source in this example.
Update the definition you created earlier, save it as a new version, and prepare the SMS call request:
from copy import deepcopy from datetime import timedelta from uuid import uuid4 from azure.ai.projects.models import ( PhoneNumber, StructuredInputDefinition, VoiceAgentEndConversationSystemTool, VoiceAgentSendSmsSystemTool, ) definition = agent_version.definition definition.instructions = ( "You are Contoso's appointment reminder assistant. " "Confirm that you are speaking with {{customer_name}} and that now is " "a good time. Explain the appointment at {{appointment_time}} and ask " "whether the customer wants an SMS confirmation. If they agree, use " "send_sms with to_phone_number={{recipient_phone_number}} and a short " "message containing the appointment details. Describe the SMS as " "submitted when the provider accepts it. When the conversation is " "complete, say goodbye and use end_conversation in the same response." ) definition.structured_inputs["recipient_phone_number"] = ( StructuredInputDefinition(schema={"type": "string"}, required=True) ) definition.tools = [ VoiceAgentEndConversationSystemTool(), VoiceAgentSendSmsSystemTool(timeout=timedelta(seconds=60)), ] agent_version = project_client.agents.create_version( agent_name=agent_name, definition=definition, ) sms_call_request = deepcopy(call_request) sms_call_request.connection_name = "contoso-twilio" sms_call_request.source = PhoneNumber(value="+14255550100") sms_call_request.structured_inputs["recipient_phone_number"] = ( sms_call_request.destination.value ) sms_request_key = str(uuid4())Reference: AgentsOperations.create_version.
Save
sms_request_keyandsms_call_requestin your application, and then submit the call:job, job_headers = telephony.create_call_job( agent_name=agent_name, job=sms_call_request, idempotency_key=sms_request_key, cls=lambda response, result, _: (result, response.http_response.headers), ) call_job_id = job.id retry_after = int(job_headers["Retry-After"]) print(call_job_id, job.status)Reference: Azure AI Projects client library for Python.
The destination comes from the earlier direct-call example. For later calls with this updated agent, include recipient_phone_number in the inputs.
Replace
instructions,structured_inputs, andtoolsin the agent definition with these values:{ "instructions": "You are Contoso's appointment reminder assistant.\nConfirm that you are speaking with {{customer_name}} and that now is a good time.\nExplain the appointment at {{appointment_time}} and ask whether the customer wants an SMS confirmation.\nIf they agree, use send_sms with to_phone_number={{recipient_phone_number}} and a short message containing the appointment details.\nDescribe the SMS as submitted when the provider accepts it.\nWhen the conversation is complete, say goodbye and use end_conversation in the same response.", "structured_inputs": { "customer_name": { "schema": { "type": "string" }, "required": true }, "appointment_time": { "schema": { "type": "string" }, "required": true }, "recipient_phone_number": { "schema": { "type": "string" }, "required": true } }, "tools": [ { "type": "system", "name": "end_conversation" }, { "type": "system", "name": "send_sms", "timeout_seconds": 60 } ] }Save and test the updated agent. Use the updated version for the next direct call or a new campaign.
Submit a call with the example connection, bound caller number, and the extra SMS input:
POST {projectEndpoint}/agents/contoso-outbound-reminders/telephony_call_jobs?api-version=v1 Authorization: Bearer <access-token> Content-Type: application/json Idempotency-Key: <stable-sms-reminder-request-key> { "connection_name": "contoso-twilio", "source": { "type": "phone_number", "value": "+14255550100" }, "destination": { "type": "phone_number", "value": "+14255550123" }, "structured_inputs": { "customer_name": "Alex", "appointment_time": "Tuesday at 10 AM", "recipient_phone_number": "+14255550123" } }
Answer the call and ask for an SMS. provider_accepted confirms submission; check delivery through the provider.
For a campaign using this updated agent, use the same connection and caller number as the SMS example. Supply recipient_phone_number for every recipient, with a value that matches the call destination.
After testing, remove the temporary SMS sender binding if you created one and no longer need it.
Schedule calls and retries
Choose a schedule when you create a job or campaign. Direct jobs use not_before; campaigns use a schedule type and, when needed, scheduled_at. Both use the same retry policy.
Set retry_policy.type to fixed_interval, max_attempts to 1–5 including the initial attempt, and interval in seconds. The default is one attempt; returned jobs represent it as max_attempts: 1 and interval: 0.
Schedule and retry a call
For a direct call job, set schedule.not_before and schedule.expires_at to define the calling window.
- Choose the start and expiry times for new attempts, and the maximum number of attempts. Set
expires_atto a future time andnot_beforeto an earlier time thanexpires_at. - Add the schedule and retry policy before submitting the call job:
Use timezone-aware datetime values for the calling window and a timedelta for the retry interval:
from datetime import datetime, timedelta, timezone
from azure.ai.projects.models import (
FixedIntervalRetryPolicy,
TelephonyCallJobSchedule,
)
call_request.schedule = TelephonyCallJobSchedule(
not_before=datetime(2030, 1, 1, 10, tzinfo=timezone.utc),
expires_at=datetime(2030, 1, 1, 11, tzinfo=timezone.utc),
)
call_request.retry_policy = FixedIntervalRetryPolicy(
max_attempts=3,
interval=timedelta(minutes=5),
)
Reference: AIProjectClient.
{
"schedule": {
"not_before": 1893492000,
"expires_at": 1893495600
},
"retry_policy": {
"type": "fixed_interval",
"max_attempts": 3,
"interval": 300
}
}
Use Unix seconds for timestamps and seconds for retry intervals.
Replace the example times with your calling window. The example covers January 1, 2030, from 10:00 to 11:00 UTC.
- With the default schedule, the job becomes eligible immediately, subject to service capacity.
not_beforesets the earliest time the service can start placing the call. The actual start time also depends on capacity.expires_atcloses the window for new attempts, including retries. Active calls continue to completion.
The service checks the provider's outcome before retrying. If a result is uncertain, continue monitoring the existing job to learn how the attempt was resolved.
Schedule a campaign
Choose when the batch becomes eligible to call. The default is immediately after successful preparation. You can also set one start time for the batch or a time for each recipient:
| Mode | Configuration |
|---|---|
| Immediate | Omit schedule, or use {"type":"immediate"}. |
| Common time | {"type":"scheduled","scheduled_at":1893492000}. |
| Per recipient | {"type":"recipient"} and a scheduled_at value on every recipient or dataset row. |
In REST requests, timestamp values are Unix seconds. 1893492000 is January 1, 2030, at 10:00 UTC; replace it with your intended time. The Python SDK accepts timezone-aware datetime values. Dataset scheduling fields use RFC 3339 strings with an explicit UTC offset or Z, such as 2030-01-01T10:00:00Z.
Include each recipient's scheduled_at exclusively with type: recipient, supplying a value for every recipient. For the other modes, use the campaign-level schedule. A time in the past makes the call eligible after preparation succeeds, subject to available capacity.
Add expires_at to any schedule to set a deadline for starting new attempts, including retries. Choose a value later than every scheduled start. Active calls can finish after that deadline.
For example, this configuration allows calls within a one-hour window, with up to three attempts per recipient:
Set these properties before submitting campaign_request with begin_create:
from datetime import datetime, timedelta, timezone
from azure.ai.projects.models import AtTimeSchedule, FixedIntervalRetryPolicy
campaign_request.schedule = AtTimeSchedule(
scheduled_at=datetime(2030, 1, 1, 10, tzinfo=timezone.utc),
expires_at=datetime(2030, 1, 1, 11, tzinfo=timezone.utc),
)
campaign_request.retry_policy = FixedIntervalRetryPolicy(
max_attempts=3,
interval=timedelta(minutes=5),
)
Reference: AIProjectClient.
{
"schedule": {
"type": "scheduled",
"scheduled_at": 1893492000,
"expires_at": 1893495600
},
"retry_policy": {
"type": "fixed_interval",
"max_attempts": 3,
"interval": 300
}
}
Add these properties to the complete campaign body.
Query jobs and campaigns
Use jobs to inspect individual calling outcomes and campaigns to inspect a batch's preparation and aggregate progress. Follow the same pagination rules for both resources.
List or delete job records
Use the job list to review calling activity, and delete completed records when you finish inspecting them.
List retained jobs and their outcomes. Add
campaign_name=campaign_nameto select one campaign, orstatus="failed"to filter by status:for retained_job in telephony.list_call_jobs( agent_name=agent_name, limit=20, order="desc", ): print(retained_job.id, retained_job.status, retained_job.terminal_reason)Optional: Select a job from the list to delete after it reaches a terminal state and its call attempts finish. Replace
<call-job-id>with that job's returnedid:selected_call_job_id = "<call-job-id>" telephony.delete_call_job( agent_name=agent_name, call_job_id=selected_call_job_id )
Reference: Azure AI Projects client library for Python.
List retained jobs under the agent:
GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs?api-version=v1&limit=20 Authorization: Bearer <access-token>The list includes direct jobs and campaign-created jobs. Campaign-created jobs identify their campaign in
campaign_name.Use
statusto select a job lifecycle state. Addcampaign_nameto select the reminder campaign. For example, list that campaign's failed jobs:GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs?api-version=v1&campaign_name=appointment-reminders&status=failed&limit=20&order=desc Authorization: Bearer <access-token>Read the jobs in
data. Each job includes itsid,status,attempt_count, and any availableterminal_reason. Omitcampaign_nameto include both direct and campaign-created jobs.When
has_moreistrue, copylast_idfrom the response intoafterto continue. Keep the same agent, filters, and order:GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs?api-version=v1&campaign_name=appointment-reminders&status=failed&limit=20&order=desc&after={lastId} Authorization: Bearer <access-token>For pagination and request recovery rules, see Handle retries, conflicts, and pagination.
Optional: After a job reaches a terminal state and its call attempts finish, delete its record:
DELETE {projectEndpoint}/agents/{agentName}/telephony_call_jobs/{callJobId}?api-version=v1 Authorization: Bearer <access-token>Check for
204 No Contentto confirm deletion. A subsequent GET returns404, and repeating DELETE returns204. If deletion returns409 Conflict, read the job and check the provider's result for any outstanding attempt before trying again.
Deleting a job record preserves the campaign's outcome counts. Read call history and stored conversations through their respective APIs.
List campaigns
Use the campaign list to find batches that need attention. Then, read a selected campaign or its jobs for details.
Iterate over running campaigns and check their progress. The SDK handles pagination:
for running_campaign in campaigns.list(
agent_name=agent_name,
status="running",
limit=20,
order="desc",
):
print(
running_campaign.name,
running_campaign.status,
running_campaign.progress.as_dict(),
)
Reference: AIProjectClient.
To check a batch, use a returned name with campaigns.get or use the call-job list's campaign_name filter.
List running campaigns under your agent:
GET {projectEndpoint}/agents/{agentName}/telephony_campaigns?api-version=v1&status=running&limit=20&order=desc Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1PreviewInspect
name,status, andprogresson each entry indata. Changestatusto another campaign lifecycle value, such asfailed, or omit it to include all retained campaigns.If
has_moreistrue, pass the response'slast_idasafterto read the next page:GET {projectEndpoint}/agents/{agentName}/telephony_campaigns?api-version=v1&status=running&limit=20&order=desc&after={lastId} Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1PreviewKeep the same agent, status filter, and order. Follow the shared pagination rules.
Use a returned
nameas{campaignName}to read its progress. To examine recipient outcomes, filter the call-job list by that campaign name.
Handle retries, conflicts, and pagination
Use the token for the resource and action you're submitting:
| Request | Retry identifier | Concurrency token |
|---|---|---|
| Create a direct call job | Save the Idempotency-Key and original body. Reuse them to recover an uncertain submission. |
The created job returns an HTTP ETag for later cancellation. |
| Cancel a call job | Read the latest job before requesting cancellation. | Send the job's HTTP ETag in If-Match. |
| Create, replace, cancel, or delete a campaign | Save the Operation-Id, original body, and any original If-Match. Reuse them to recover the same request. |
Replacement, cancellation, and deletion use the campaign body's etag in If-Match. |
For new campaign work or a retry of a failed operation, use a fresh operation ID. After a concurrency conflict, read the current campaign and confirm the intended action. Reusing an operation ID with different inputs, action, or precondition returns 409 operation_id_conflict.
Send the exact campaign etag returned by the latest read. If a new request returns 412, read the current campaign and check whether the action is still appropriate before retrying. Keep each action's Operation-Location to track its progress.
For job, campaign, and validation-error lists, use these pagination rules:
- Set
limitto 1–100. Useorder=ascororder=descto choose the sort order. - When
has_moreistrue, passlast_idasafterfor the next page. Usefirst_idasbeforeto read backward. Choose one direction per request. - Keep the same agent, filters, and order. URL-encode cursor values and pass them unchanged; campaign and validation-error cursors are opaque.
- If a cursor returns
400 invalid_cursor, start a new query. Lists reflect current state and can change between requests.
Cancel future calls
Cancel an individual job before it connects, or cancel a campaign to stop future work across its recipients. Connected calls follow the behavior described for each operation.
Cancel a call job
Cancel a job before the call connects to stop future attempts.
Read the current job and its response headers, and then pass the ETag when canceling the job:
from azure.core import MatchConditions
job, job_headers = telephony.get_call_job(
agent_name=agent_name,
call_job_id=call_job_id,
cls=lambda response, result, _: (result, response.http_response.headers),
)
job = telephony.cancel_call_job(
agent_name=agent_name,
call_job_id=call_job_id,
etag=job_headers["ETag"],
match_condition=MatchConditions.IfNotModified,
)
print(job.status)
Reference: Azure AI Projects client library for Python.
Continue monitoring the job until it reaches a terminal state.
Read the job again and copy its current HTTP
ETagheader.Send the ETag unchanged in the
If-Matchheader of a bodyless cancellation request:POST {projectEndpoint}/agents/{agentName}/telephony_call_jobs/{callJobId}:cancel?api-version=v1 Authorization: Bearer <access-token> If-Match: <etag-from-latest-call-job-read>Continue reading until the job reaches a terminal state. The service cancels future attempts and confirms the result of any attempt already underway.
A cancellation request returns 202 Accepted while cancellation is pending. For a terminal job, a request with the current ETag returns 200 OK and the job's existing state. A connected call can finish naturally, and a new cancellation while that call is still active returns 409 Conflict.
For a precondition failure, read the latest job and check whether cancellation is still appropriate. Use that job's current ETag for the next cancellation request.
The reminder agent uses its configured end_conversation tool to finish a connected conversation after its farewell.
Cancel a campaign
Cancel a campaign to stop new calls and retries while connected calls finish.
Read the campaign's current ETag and generate an operation ID for cancellation. Save both values so your application can recover an interrupted request:
from uuid import uuid4
from azure.core import MatchConditions
campaign = campaigns.get(
agent_name=agent_name,
campaign_name=campaign_name,
)
cancellation_etag = campaign.etag
cancellation_operation_id = str(uuid4())
campaign = campaigns.begin_cancel(
agent_name=agent_name,
campaign_name=campaign_name,
etag=cancellation_etag,
match_condition=MatchConditions.IfNotModified,
operation_id=cancellation_operation_id,
).result()
print(campaign.status)
Reference: AIProjectClient.
The poller waits for the cancellation operation and returns the campaign's final state. To recover an interrupted status request, read the existing operation with cancellation_operation_id.
Read the campaign and copy the exact
etagvalue from its response body. This token stays valid through progress-only updates.Submit a bodyless cancellation request:
POST {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}:cancel?api-version=v1 Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1Preview If-Match: <etag-from-latest-campaign-body> Operation-Id: <new-cancellation-operation-id>Save the cancellation operation returned with
202 Acceptedand read its status until it finishes. Then read the campaign. Connected calls finish naturally while cancellation waits for all campaign work to stop.
If cancellation fails, the campaign remains cancelling with new attempts blocked. Read its error and latest etag, then use a fresh operation ID to retry cancellation. To recover a lost response to the same request, reuse the original ID and token.
Cancellation is available while a campaign is validating or running, and it permanently stops that campaign's future work. To run another batch after cancellation, create a new campaign. To defer calls, choose their schedule when you create the campaign.
Correct or delete a campaign
Replace a failed configuration to validate the recipients again. Delete a terminal campaign when you finish inspecting its recipient data and jobs.
Correct a failed campaign
For a campaign in failed state, submit a complete corrected configuration to validate the recipients again.
Upload the corrected recipient file with a new dataset version. Read the campaign's current ETag and prepare the corrected configuration. Replace the dataset name and version with the values from your upload:
from uuid import uuid4 from azure.ai.projects.models import ( TelephonyCampaign, TelephonyCampaignDatasetReference, ) from azure.core import MatchConditions campaign = campaigns.get( agent_name=agent_name, campaign_name=campaign_name, ) replacement_etag = campaign.etag operation_id = str(uuid4()) campaign_request = TelephonyCampaign( connection_name=connection_name, source=source, recipient_dataset=TelephonyCampaignDatasetReference( name="corrected-appointment-recipients", version="2", ), )Reference: AIProjectClient.
Save
campaign_request,replacement_etag, andoperation_idin your application, and then submit the replacement:campaign = campaigns.begin_create( agent_name=agent_name, campaign_name=campaign_name, campaign=campaign_request, etag=replacement_etag, match_condition=MatchConditions.IfNotModified, operation_id=operation_id, ).result() print(campaign.status)Reference: AIProjectClient.
Correct the recipient source and read the campaign's current body
etag.Submit a complete corrected body with that exact token in
If-Matchand a freshOperation-Id:PUT {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}?api-version=v1 Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1Preview Content-Type: application/json If-Match: <etag-from-latest-campaign-body> Operation-Id: <new-validation-operation-id> { "connection_name": "contoso-twilio", "source": { "type": "phone_number", "value": "+14255550100" }, "recipient_dataset": { "name": "corrected-appointment-recipients", "version": "2" } }Save the new operation URL and poll validation. The accepted replacement returns
200 OK. Eligible calls start after validation succeeds.
Include all intended configuration; omitted optional fields reset to defaults. The updated campaign uses the latest agent version and replaces its previous jobs, validation errors, and progress. Start new queries to read its jobs and validation results.
Replacement is available for failed preparation. To change a batch that's already running, cancel its future work and create a new campaign. Use a new campaign for another batch after completion.
Delete a terminal campaign
Delete a completed, failed, or canceled campaign to remove its recipient data and call-job records.
Read the current campaign and save its ETag with a new operation ID. After confirming that its status is completed, failed, or cancelled, delete it:
from uuid import uuid4
from azure.core import MatchConditions
campaign = campaigns.get(
agent_name=agent_name,
campaign_name=campaign_name,
)
deletion_etag = campaign.etag
deletion_operation_id = str(uuid4())
campaigns.begin_delete(
agent_name=agent_name,
campaign_name=campaign_name,
etag=deletion_etag,
match_condition=MatchConditions.IfNotModified,
operation_id=deletion_operation_id,
).result()
print("Campaign deleted.")
Reference: AIProjectClient.
To recover an interrupted status request, read the existing operation with deletion_operation_id until it succeeds.
Confirm that the campaign is completed, failed, or canceled. Check that its work has stopped, and read its current body
etag.Send a conditional deletion request:
DELETE {projectEndpoint}/agents/{agentName}/telephony_campaigns/{campaignName}?api-version=v1 Authorization: Bearer <access-token> Foundry-Features: VoiceAgents=V1Preview If-Match: <etag-from-latest-campaign-body> Operation-Id: <new-deletion-operation-id>Save the returned
Operation-Idand read its status until deletion finishes. The initial response is202 Acceptedwith an empty body. Deleting an absent campaign returns204 No Content, unless the service is replaying a previously accepted request.
Deletion removes the campaign's recipient data, validation errors, and call-job records. The source dataset, provider connection, and agent remain available for other campaigns.
During deleting, the name stays reserved and the campaign's jobs are hidden from reads. Deletion is irreversible. If cleanup fails, you can retry the operation.
A failed cleanup stays in deleting; retry with a fresh operation ID and the latest etag. After cleanup succeeds, you can reuse the name with a new operation ID for a new campaign.
Troubleshoot
Use the response status and resource details to choose the next step. To inspect dialogue and audio, follow Read the conversation and recording. For an investigation workflow, see Troubleshoot telephony.
| Symptom | Action |
|---|---|
Call-job creation returns 400 |
Check the typed addresses, connection name, required agent inputs, and 1–256 character idempotency key. |
Call-job creation returns 409 for a reused key |
Reuse the saved key with its original request to recover the same job. A different request requires a fresh key. |
Call-job creation returns call_job_deleted |
The key belongs to a deleted job. Use a fresh key when you intend to place a new call. |
| Accepted job is waiting to ring | Inspect its schedule, status, reason, attempt count, caller authorization, and provider connectivity. |
Outbound calling returns 503 Service Unavailable |
Keep the request details and contact support if the error persists. |
| SMS submission result is uncertain | Check the provider outcome before repeating the send to avoid duplicate messages. |
| SMS tool is unavailable | Confirm that the sender number is bound to this agent and supports SMS. |
| Call-job cancellation conflicts | Read the latest state and token. Check whether the call has connected. |
A paged query returns 400 invalid_cursor |
Start again from the first page with the intended agent, campaign, filters, and order. Use a new query after replacing a campaign or reusing its name. |
| Job completed and the business outcome needs review | Inspect the conversation and your application's result to assess whether the agent achieved its goal. |
| Campaign validation fails | Read the validation operation, campaign error, and row-level errors. Correct the source and replace the failed configuration. |
| Campaign status polling reports an unsupported API version | Resume the existing operation with get_operation or the REST operation URL using api-version=v1. Keep the original operation ID to track the batch already submitted. |
Campaign action returns 409 operation_id_conflict or 412 |
Check the saved request and current etag using request recovery rules. |
Campaign status is completed, but some recipients weren't reached |
Review each recipient job's status and terminal_reason, including completed jobs with no_answer. Campaign completion means every job is terminal. |