Integrate telephony channels with a voice agent

Use Teams Phone extensibility (TPE) or Twilio to connect a phone number to your Microsoft Foundry voice agent. Receive inbound calls and place outbound calls through the call-job API.

Use Choose a configuration method at the top of this article to select your interface. Then select your provider in the tabs below. Your provider selection applies throughout the article. For SIP connectivity, see Connect a voice agent through SIP.

For complete examples, follow the inbound support workflow or the outbound reminder workflow.

Voice agents are generally available, with some features still in preview. See General availability and preview features.

Caution

Teams Phone extensibility and Twilio telephony channels 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.

Prerequisites

  • A saved voice-based agent in a Foundry project that passes browser testing. See Quickstart: Create a voice-based prompt agent.

  • Foundry User role on the project, to create and manage telephony bindings.

    Important

    The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

  • Permission to update the agent and its channels, manage project connections, and create or update telephony bindings.

Teams Phone extensibility prerequisites

For the Teams Phone extensibility path, you need:

  • A Teams Phone service number assigned to a resource account. See Get Microsoft Teams Calling Plan phone numbers for your tenant.
  • The setup in Prepare Teams Phone extensibility, completed with a Teams or Microsoft 365 administrator.
  • Access to the selected Azure Communication Services resource.
  • For inbound calls, Event Grid write permission on that resource.
  • Help from a tenant administrator when secure webhook setup requires Microsoft Entra application or app-role changes.

The current project-managed-identity flow requires the Foundry project and Azure Communication Services resource to be in the same Microsoft Entra tenant.

Compare the channel integrations

Choose the provider that owns your number.

Path Use it when What you provide in Foundry
Teams Phone extensibility Your organization owns a service number in Teams and routes it through a Teams resource account to Azure Communication Services. An Azure Communication Services project connection and the resource-account object ID as a GUID, without the 28:orgid: prefix.
Twilio Your organization owns one or more active voice-capable numbers in Twilio. An existing Twilio project connection, or the Account SID and Primary Auth Token for a new connection.

The Twilio option appears only in supported public-cloud environments.

In azure.yaml, the Teams identifier includes the 28:orgid: prefix. The CLI converts it to the GUID required by the API. See Connect a number with Azure Developer CLI.

Understand the call path

The channel integration determines how an inbound call reaches the agent.

Caller
  -> Teams resource-account number or Twilio number
  -> telephony provider
  -> Foundry project telephony endpoint
  -> telephony binding
  -> voice-based agent

For Teams Phone extensibility, your Teams tenant keeps ownership of the number and Azure Communication Services provides the call automation and media path:

  1. A caller dials the Teams phone number.
  2. Teams routes the call to your resource account.
  3. The resource account routes the call to your Communication Services resource.
  4. Communication Services raises a Microsoft.Communication.IncomingCall event through Event Grid to your agent's telephony callback endpoint.
  5. Foundry matches the callee to a telephony binding, answers the call on your Communication Services resource, and streams the audio to the agent.

Because the Teams number stays in Teams, the agent can act as one destination among others in your existing call flow. You can leave auto attendants and call queues in place and route selected paths to the agent.

Set up your preferred interface

Use Choose a configuration method at the top of this article to select Foundry portal, Python SDK, REST API, or Azure Developer CLI. The Python examples share a client and variables across sections.

Open your project in the Foundry portal. You don't need the Python packages or a manually acquired bearer token for the portal steps.

Use Python 3.10 or later and install the packages:

python -m pip install "azure-ai-projects>=2.11.0" azure-identity

For local development, sign in with az login before using DefaultAzureCredential. Replace the endpoint and agent name, then run this setup once in your Python session:

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>"
agent_name = "my-voice-agent"
credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
telephony = project_client.voice_agents.telephony

Reference: AIProjectClient | DefaultAzureCredential.

The client uses api-version=v1. Teams Phone extensibility and Twilio operations don't need a preview opt-in. To use SIP features, which are in preview, create the client with allow_preview=True so that it sends Foundry-Features: VoiceAgents=V1Preview.

Examples that need response headers use the cls callback to return the model and raw HTTP headers together. After running the examples you need, close project_client and credential with their close() methods.

  1. Sign in with the Azure CLI and obtain a Microsoft Entra access token:

    az login
    az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv
    
  2. Replace {projectEndpoint} with your Foundry project endpoint and {agentName} with the voice agent's name. Use the token as <access-token> in the Authorization: Bearer <access-token> header.

  3. The examples use api-version=v1. Teams Phone extensibility and Twilio requests don't need a preview opt-in. Send Foundry-Features: VoiceAgents=V1Preview for SIP binding, call, and call-job writes, and when configuring SIP transfer destinations. All campaign operations require that opt-in.

Run the commands from the directory that contains your project's azure.yaml. Check that the CLI and agent extension meet the version requirements:

azd version
azd ai agent version

Reference: Verify the Foundry extensions.

Sign in and select the existing environment that contains your voice agent. Replace <environment-name> with that environment's name:

azd auth login
azd env select <environment-name>

Reference: azd auth login | azd env select.

This workflow deploys inbound bindings declared in your voice service. Use Python or REST for outbound jobs, live-call operations, and independent binding management. Teams Phone extensibility and Twilio bindings don't require a voice preview opt-in with these extension versions.

Configure a provider connection

Use a project connection for your provider. The portal number setup flow can create it for you. For CLI, SDK, or REST requests, create or select the connection first.

Prepare Teams Phone extensibility

A Teams or Microsoft 365 administrator usually completes these steps.

  1. Follow Teams Phone System extensibility quick start to provision the application, bot, resource account, and Azure Communication Services association.
  2. Create or select the Azure Communication Services resource that receives calls for the resource account.
  3. Create the Teams resource account with the Phone Extensibility application ID.
  4. Associate the resource account with the Azure Communication Services resource, and synchronize the resource account.
  5. Acquire a Teams service number and assign it to the resource account. The number can use Calling Plan, Operator Connect, or Direct Routing according to your Teams telephony configuration.
  6. Assign the Microsoft Teams Phone Resource Account license when required.
  7. Provide Azure Communication Services server consent for the exact tenant and resource-account object ID.
  8. For inbound calls, place a controlled call and confirm that Azure Communication Services emits Microsoft.Communication.IncomingCall.

Provide the Foundry owner with the callable Teams number, Azure Communication Services ARM resource ID, and resource-account object ID. For inbound setup, also confirm that Azure Communication Services received the test call.

Create a connection to Communication Services

For Teams, use the category AzureCommunicationServices. Set target to the resource's HTTPS endpoint, such as https://<resource-name>.communication.azure.com, not its Azure resource ID. Store the matching resource ID in ResourceId metadata.

Choose an authentication type supported by the connection:

Authentication authType What you provide
Project managed identity ProjectManagedIdentity Grant the project identity access to the Communication Services resource.
Account managed identity AccountManagedIdentity Grant the Foundry account identity access to the resource.
User-assigned managed identity RegistryIdentity Identity resource ID and client ID, with access to the resource.
Service principal ServicePrincipal Tenant ID, client ID, and client secret, with access to the resource.
Connection string CustomKeys The Communication Services connection string in the connectionString credential key.

For a managed identity or service principal, grant the required Communication Services permissions before creating a binding or placing calls.

Use the connection's name as connection_name in binding and outbound requests. Don't include provider credentials in those requests.

Use the existing project connection's name in the YAML connection field. The telephony declaration doesn't create a provider account, phone number, project connection, or Teams Event Grid subscription.

Understand telephony bindings

A binding routes inbound calls to one agent. You don't need a binding for outbound call jobs.

Property Purpose
id Service-generated binding ID for later reads, updates, and deletion.
provider teams_phone_extensibility.
connection_name Foundry project connection name. Secrets stay in the connection.
resource_account_object_id Required Teams resource-account GUID, without 28:orgid:.
phone_number Optional display phone number for the Teams resource account.
label Optional display label.
incoming_call_url Service-generated incoming-call delivery URL.

Create and list bindings at {projectEndpoint}/agents/{agentName}/telephony/bindings. Append /{bindingId} to read, update, or delete one. Use the latest ETag for conditional updates and deletion.

Connect a number in the Foundry portal

Connect your number through the agent's Phone numbers channel.

Open the phone-number channel

  1. In Foundry, select Build > Agents.
  2. Select the voice-based agent.
  3. Open Channels.
  4. In Phone numbers, select Add a number.
  5. Select Microsoft Teams.

Connect a Microsoft Teams number

The Teams Phone extensibility flow creates or updates the Azure Communication Services project connection and telephony binding. Depending on the secure-delivery option, Foundry can also configure the webhook application and IncomingCall Event Grid subscription.

Choose secure incoming-call delivery

When Secure incoming-call delivery is shown, choose the approved mode.

Option Use it when
Automatic configuration (Recommended) Use when the tenant allows Foundry to create or update the webhook app, app-role assignments, and Event Grid subscription.
Manual configuration Use an approved customer-managed application, or select an existing Event Grid and app-registration configuration.

Under Manual configuration, choose the option that matches your setup:

  • Use a customer-managed app registration and let Foundry configure Event Grid: Use a dedicated single-tenant application that you own, or ask an administrator to complete the changes.
  • Event Grid and app registration are already configured: Use only when authenticated Event Grid delivery to the exact Foundry webhook is complete. Foundry skips that bootstrap work.

For a customer-managed application:

  1. Select an eligible single-tenant app registration.
  2. Enter any governance reference required by your organization.
  3. If the application isn't listed, confirm that you're an owner and refresh.
  4. Ask a tenant administrator to complete required API permissions and app-role assignments.

Never disable authentication to work around a webhook validation error.

Select Azure Communication Services

In Azure Communication Services resource, select the resource that receives the calls.

If it isn't listed:

  • Confirm the tenant and subscription.
  • Confirm you can read the resource.
  • Confirm the expected resource provider is registered.
  • Ask an Azure administrator to correct RBAC.

Foundry creates or updates the project connection to the Azure Communication Services endpoint and uses the project managed identity. Don't enter an Azure Communication Services key or connection string.

Enter the Teams number details

Enter the Resource account object ID that the Teams administrator provides. Foundry constructs:

28:orgid:<resource-account-object-id>

Manage a connected number

The Phone numbers card shows each connected number, its optional label, and its provider.

  1. Open the number's actions menu.
  2. Select View details.
  3. Select Edit if the binding supports updates.
  4. Update the displayed phone number or label. The resource-account object ID and connection are read-only.
  5. Select Save.

Connect a number with the Python SDK

Use the client from Set up your preferred interface and your provider connection. Prepare the request model for your selected provider, and then create the binding.

For Teams Phone extensibility, use your resource-account GUID. The phone number is optional display metadata.

from azure.ai.projects.models import (
    TeamsPhoneExtensibilityTelephonyBinding,
)

binding_request = TeamsPhoneExtensibilityTelephonyBinding(
    connection_name="my-acs-connection",
    resource_account_object_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    phone_number="+12065550123",
    label="Support line",
)

Reference: Azure AI Projects client library for Python.

After running the request-model snippet for your provider, create its binding:

binding = telephony.create_binding(
    agent_name=agent_name,
    binding=binding_request,
)
binding_id = binding.id
print(binding_id, binding.incoming_call_url)

Reference: Azure AI Projects client library for Python.

Save binding_id for later requests.

Use incoming_call_url to register the Event Grid subscription.

To update the binding's label, read its latest ETag and pass it to update_binding with MatchConditions.IfNotModified:

from azure.ai.projects.models import UpdateTelephonyBindingRequest
from azure.core import MatchConditions

binding, binding_headers = telephony.get_binding(
    agent_name=agent_name,
    binding_id=binding_id,
    cls=lambda response, result, _: (result, response.http_response.headers),
)
binding = telephony.update_binding(
    agent_name=agent_name,
    binding_id=binding_id,
    body=UpdateTelephonyBindingRequest(label="Customer support"),
    etag=binding_headers["ETag"],
    match_condition=MatchConditions.IfNotModified,
)

Reference: Azure AI Projects client library for Python | MatchConditions.

Read the latest ETag before every update. The binding update rules apply to either interface.

Connect a number by using the API

Use your provider connection and the authentication headers from Set up your preferred interface.

Create the binding

For Teams Phone extensibility, set connection_name to your ACS connection and resource_account_object_id to your Teams resource-account GUID. The optional phone_number is display metadata, not the routing identifier.

POST {projectEndpoint}/agents/{agentName}/telephony/bindings?api-version=v1
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "provider": "teams_phone_extensibility",
  "connection_name": "my-acs-connection",
  "resource_account_object_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "phone_number": "+12065550123",
  "label": "Support line"
}

Replace the example connection name, identifiers, and phone numbers with your values.

The service returns 201 Created, the binding's id and incoming_call_url, and an ETag header. Save the binding ID.

Register the Event Grid subscription with the returned incoming_call_url.

Read or update the binding

Read the binding to get its current properties and ETag:

GET {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1
Authorization: Bearer <access-token>

Use PATCH with application/merge-patch+json to update the binding. For example, change its display label:

PATCH {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1
Authorization: Bearer <access-token>
Content-Type: application/merge-patch+json
If-Match: <etag-from-latest-binding-read>

{
  "label": "Customer support"
}

Read the latest ETag before each update. Don't reuse an ETag after another change.

Connect a number with Azure Developer CLI

Add a binding to the existing voice service, then deploy that service. Deployment also applies the agent's local configuration, so review its model, instructions, and audio settings before continuing.

Declare the binding

In azure.yaml, locate your voice service under services. Add telephony at the same indentation level as kind, model, and name.

Preserve the existing agent settings and any bindings you want to keep. For a service defined through $ref, edit its referenced definition instead.

Use provider: acs and prefix your Teams resource-account GUID with 28:orgid:. Replace the GUID and connection name with your values:

telephony:
  bindings:
    - provider: acs
      identifier: "28:orgid:aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
      connection: my-acs-connection

Reference: Telephony YAML configuration.

The CLI sends provider: teams_phone_extensibility and the GUID as resource_account_object_id to the API. Don't use an ACS-purchased-number identifier such as 4:+14255550123; this workflow doesn't support that format.

Deploy and inspect the binding

  1. Deploy the voice service. Replace <service-name> with the key under services in azure.yaml. This key can differ from the agent's Foundry name:

    azd deploy <service-name>
    

    Reference: azd deploy.

    Deployment creates missing bindings and accepts matching active bindings. It fails on conflicting configuration or duplicate matches rather than changing existing routing. It uses api-version=v1 and service-generated binding IDs.

  2. Read the deployed bindings through REST. azd doesn't expose a standalone binding-list command. Complete the REST authentication setup, then send:

    GET {projectEndpoint}/agents/{agentName}/telephony/bindings?api-version=v1
    Authorization: Bearer <access-token>
    

    Reference: Telephony binding API operations.

    Find the binding by its provider and phone number or Teams resource-account GUID. If has_more is true, repeat the request with &after={lastId}, using the URL-encoded last_id from the response. Save the returned id and incoming_call_url; don't construct the ID from the provider or number.

  3. Complete incoming-call delivery, then test the call. For Teams, use incoming_call_url when configuring Event Grid. For Twilio, Foundry configures the number's voice callbacks when it creates the binding.

Binding update rules

Both providers support updates to label. To stop routing incoming calls to the agent, disconnect the number.

azd deploy doesn't update or delete existing bindings. Select Python SDK or REST API for those operations. If deployment reports configuration drift, inspect and reconcile the existing binding before deploying again.

Teams bindings also support changes to connection_name and the display phone_number. The provider and resource-account object ID are immutable.

Configure incoming-call delivery

After creating a binding, complete the callback setup for your provider.

Register the Event Grid subscription

For inbound calls, create an Event Grid subscription on the Communication Services resource that targets the binding's incoming_call_url. If the portal already configured secure delivery, don't create a duplicate subscription.

Before running the Bash example, sign in with az login and set these variables:

Variable Value
eventSubscriptionName A name for the Event Grid event subscription.
acsResourceId The Azure resource ID of the Communication Services resource.
webhook The incoming_call_url returned when you create the binding.
webhookTenantId The tenant ID configured for the webhook application.
webhookApplicationIdOrUri The webhook application's client ID or Application ID URI.

Complete the application and role setup in Deliver events to Microsoft Entra protected endpoints first. Obtain the webhook tenant and audience from the administrator who configures secure incoming-call delivery. The webhook application identifies the token audience; it isn't the Microsoft Event Grid first-party application.

az eventgrid event-subscription create \
  --name "$eventSubscriptionName" \
  --source-resource-id "$acsResourceId" \
  --endpoint-type webhook \
  --endpoint "$webhook" \
  --included-event-types Microsoft.Communication.IncomingCall \
  --event-delivery-schema eventgridschema \
  --azure-active-directory-tenant-id "$webhookTenantId" \
  --azure-active-directory-application-id-or-uri "$webhookApplicationIdOrUri"

Reference: az eventgrid event-subscription create.

During creation, Event Grid sends a validation event that the endpoint answers automatically.

Foundry validates the Microsoft Entra token that Event Grid attaches to each delivery and matches the event to a binding's project, agent, Communication Services resource, and callee.

Event Grid allows up to 500 event subscriptions per system topic. Plan incoming-call delivery within the Event Grid quotas and limits.

Place outbound calls by using the API

To place an outbound call, create a call job through the API. A call job uses your provider's project connection and doesn't need an inbound binding, so you can use a connection that you created in the portal.

Place outbound calls and manage campaigns covers the complete workflow:

The call-job ID tracks the outbound request and its attempts. To transfer or end a connected call, use the call ID from the Calls API, as described in Manage a live call.

azd deploy doesn't place outbound calls. Use the Python or REST examples in the outbound-call guide.

Configure transfer to a person

Configure named transfer targets so your application can route an active call to a support representative. The application selects a target by name when it calls the transfer API. For agent-selected transfers, configure the separate transfer system tool.

The examples use phone-number destinations.

Select Python SDK or REST API at the top of this article for the transfer-target configuration examples.

Use Python SDK or REST API for the target-management examples in this section. Optional YAML transferTargets declarations can populate an empty agent-level target list only when the same deployment creates a binding. The CLI doesn't overwrite a nonempty target list or apply a changed list when no binding is created.

Read the current target list and its ETag, and then replace the list. Include every target you want to keep. An empty list clears the target list.

from azure.core import MatchConditions

targets, target_headers = telephony.get_transfer_targets(
    agent_name=agent_name,
    cls=lambda response, result, _: (result, response.http_response.headers),
)
targets = telephony.replace_transfer_targets(
    agent_name=agent_name,
    body={
        "transfer_targets": [
            {
                "name": "billing",
                "description": "Billing and payment questions",
                "destination": {
                    "type": "phone_number", "value": "+14255550111"
                },
            },
            {
                "name": "operator",
                "description": "A person at the front desk",
                "destination": {
                    "type": "phone_number", "value": "+14255550112"
                },
            },
        ]
    },
    etag=target_headers["ETag"],
    match_condition=MatchConditions.IfNotModified,
)

Reference: Azure AI Projects client library for Python.

Replace the example destinations with your approved targets.

First, read the current target list and its ETag response header:

GET {projectEndpoint}/agents/{agentName}/telephony/transfer_targets?api-version=v1
Authorization: Bearer <access-token>

Replace the target list with PUT, using the returned ETag in If-Match. Include every target you want to keep: this operation replaces the entire list, and an empty array clears it.

PUT {projectEndpoint}/agents/{agentName}/telephony/transfer_targets?api-version=v1
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: <etag-from-latest-transfer-targets-read>

{
  "transfer_targets": [
    {
      "name": "billing",
      "description": "Billing and payment questions",
      "destination": { "type": "phone_number", "value": "+14255550111" }
    },
    {
      "name": "operator",
      "description": "A person at the front desk",
      "destination": { "type": "phone_number", "value": "+14255550112" }
    }
  ]
}

Use these destination types in REST requests for provider-specific routing:

Destination type Value
phone_number E.164 phone number.
teams Teams user or resource-account GUID, optionally prefixed with 28:orgid:.

For a Teams recipient, use the teams destination type with the recipient's Teams object GUID.

Use the same type and value address fields in the Python request dictionary and REST body.

Give each target a description that explains its purpose, such as billing support or a front-desk operator. Your application uses the configured target name in its transfer request.

Transfer requests select a target from this API collection. The transfer system tool uses the targets in the agent definition.

Manage a live call

Use the Calls API to find a call and request a transfer or end action while it is active. These actions apply to inbound and outbound calls with a call record. Complete Set up your preferred interface before running the examples.

Your application selects the action and supplies the call ID. Use these call management APIs for supervisor controls or actions triggered by your application:

Action REST request Python SDK method
Find calls GET /agents/{agentName}/telephony/calls list_calls
Inspect one call GET /agents/{agentName}/telephony/calls/{callId} get_call
Transfer an active call POST /agents/{agentName}/telephony/calls/{callId}:transfer with a configured target transfer_call
End an active call POST /agents/{agentName}/telephony/calls/{callId}:end end_call

For the outbound example, filter the call list by provider and time, then match the returned phone numbers to your call. Use the matching record's id for call control. The call-job ID tracks the outbound request and its attempts. See Inspect call records and conversations for query filters and diagnostics.

Select Python SDK or REST API at the top of this article to list calls or send a transfer or end-call request.

  1. List calls in progress and select the ID of the call you want to manage. The SDK retrieves more pages as you iterate:

    for call in telephony.list_calls(
        agent_name=agent_name, status="in_progress", limit=20
    ):
        print(call.id, call.status, call.phase)
    

    Reference: Azure AI Projects client library for Python.

  2. Replace <active-call-id> with the selected call ID and read its current details:

    call_id = "<active-call-id>"
    call = telephony.get_call(agent_name=agent_name, call_id=call_id)
    print(call.status, call.phase)
    

    Reference: Azure AI Projects client library for Python.

    The status in_progress includes calls still being set up. Transfer and end-call actions require an active call. Check its phase and current details before sending an action.

  3. Choose one action for the call. To transfer it to the configured operator target:

    call = telephony.transfer_call(
        agent_name=agent_name, call_id=call_id, target="operator"
    )
    

    Reference: Azure AI Projects client library for Python.

    To end the call instead, send an end-call request:

    call = telephony.end_call(agent_name=agent_name, call_id=call_id)
    

    Reference: Azure AI Projects client library for Python.

  4. Inspect the returned call record. Both actions return the updated record. Read it again to check its subsequent status and lifecycle events:

    call = telephony.get_call(agent_name=agent_name, call_id=call_id)
    print(call.status, call.phase, call.end_reason)
    for event in call.events or []:
        print(event.sequence, event.name, event.outcome, event.reason)
    

    Reference: Azure AI Projects client library for Python.

    Check the provider's call status to confirm the transfer outcome.

  1. List calls in progress. Match the call's phone numbers and start time, and copy its id into {callId} for subsequent requests:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls?api-version=v1&status=in_progress&limit=20
    Authorization: Bearer <access-token>
    
  2. Read the selected call. Check its current status and lifecycle details to confirm that it is active:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}?api-version=v1
    Authorization: Bearer <access-token>
    
  3. Choose the action for this call. To transfer it, first configure an API transfer target, then send its name in target. This example uses operator:

    POST {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}:transfer?api-version=v1
    Authorization: Bearer <access-token>
    Content-Type: application/json
    
    { "target": "operator" }
    

    To end the call instead, send an end request with an empty body:

    POST {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}:end?api-version=v1
    Authorization: Bearer <access-token>
    
  4. Inspect the returned call record. Both actions return 200 OK with the updated record. Use the same GET request to read its subsequent status and lifecycle events. Check the provider's call status to confirm the transfer outcome.

Configure audio for phone calls

Phone networks carry narrowband audio, so tune the agent for the channel:

  • Use azure_deep_noise_suppression_headset when background speech causes false turns or interruptions in phone calls. For single-caller sessions with competing nearby speakers, use azure_personal_noise_suppression. Keep azure_deep_noise_suppression for general-purpose background-noise suppression.
  • Increase silence_duration_ms. Callers on a phone pause more than callers at a keyboard.
  • Add phrase_list hints for the identifiers callers read aloud, such as order or policy numbers.
  • Attach the end_conversation system tool so the agent can end a completed call.

See Configure a voice agent.

Test the call

azd ai agent invoke doesn't start voice conversations or phone calls. Use a controlled phone call to verify the binding and provider routing.

Allow time for your provider configuration changes to propagate before testing the number.

  1. Wait for the selected provider and binding changes to propagate.
  2. From a controlled caller, call the configured number.
  3. Confirm the agent answers.
  4. Complete a short conversation.
  5. Interrupt the agent.
  6. Use one safe tool or knowledge path.
  7. Test the approved human-handoff behavior.
  8. End the call.
  9. Confirm that monitoring and trace data appear.

Record:

  • Test timestamp and time zone.
  • Called number.
  • Callee identifier.
  • Telephony provider and provider call ID, such as an Azure Communication Services correlation ID or Twilio Call SID.
  • Agent name and version.

Also record the Azure Communication Services resource ID and Event Grid delivery result.

For an outbound test, create a job for an approved test recipient and record the job ID, status, attempt count, and reason. Don't treat 202 Accepted as proof that the call connected.

Trace phone calls

When a call arrives through telephony, the session's root trace span records the provider, the provider's call ID, and the dialed and calling numbers. You can correlate a Foundry session with a record in your telephony provider.

Caller and callee phone numbers are personal data. Review who can read your project's Application Insights resource before you enable content capture. See Voice agent tracing, monitoring, and evaluation.

Inspect call records and conversations

Use the Calls API for call records and live-call actions, the call-job API for outbound requests and retries, and conversation APIs for stored dialogue. Complete the interface setup for Python or REST. Use the project endpoint and agent name from your call setup.

To run the query examples in this section, select Python SDK or REST API under Choose a configuration method at the top of this article.

Choose the record that matches the question you want to answer:

Question Query Identifier to save
What happened during a call? List and get /agents/{agentName}/telephony/calls. The call's service-generated id.
How is an outbound call progressing? Read the call job. The job id, attempt_count, and any terminal_reason.
How is a recipient batch progressing? Read the campaign and validation operation, then list jobs by campaign_name. The campaign name, operation ID, and recipient job IDs.
What did the caller and agent say? Read the agent's stored voice conversation and items. The conversation_id.
Which stage caused a delay or failure? Inspect the call's lifecycle events and the linked Foundry trace. trace.trace_id and provider_call_id, when available.

Keep these identifiers with your application's request records. Each identifies a different resource: pass a call ID to the Calls API, a job ID to the call-job API, and a conversation ID to the conversation API.

Find a call record

The Calls API returns call records, including calls that ended before a voice session became ready. Call history is available independently of conversation storage. For outbound work, also query the call job to track its schedule and attempts.

  1. List failed calls in your investigation window. The SDK accepts UTC datetime values and retrieves more pages as you iterate:

    from datetime import datetime, timedelta, timezone
    
    end_time = datetime.now(timezone.utc)
    start_time = end_time - timedelta(hours=1)
    for call in telephony.list_calls(
        agent_name=agent_name,
        status="failed",
        started_after_time=start_time,
        started_before_time=end_time,
        order="desc",
        limit=20,
    ):
        print(call.id, call.provider, call.status, call.phase)
    

    Reference: Azure AI Projects client library for Python.

  2. Select the call by its time and provider, and replace <call-id> with its returned id. Read the record and print its lifecycle events in sequence:

    call_id = "<call-id>"
    call = telephony.get_call(agent_name=agent_name, call_id=call_id)
    print(call.status, call.phase, call.end_reason)
    print(call.provider_call_id, call.provider_message)
    for event in sorted(call.events or [], key=lambda item: item.sequence):
        print(event.sequence, event.name, event.outcome, event.reason)
    if call.trace:
        print(call.trace.trace_id, call.trace.conversation_id)
    

    Reference: Azure AI Projects client library for Python.

    Use trace_id for trace lookup and conversation_id to read stored dialogue. These values are available when the call reaches the corresponding stage.

  1. List failed calls for the agent, with the most recent records first:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls?api-version=v1&status=failed&order=desc&limit=20
    Authorization: Bearer <access-token>
    

    The response contains a data array of call summaries and pagination fields. Set status=in_progress to find calls still in progress, or omit status to include all outcomes. Inspect the milestones to confirm whether a call was answered. A call status of success describes the call lifecycle; use conversation or business-service results to assess whether the customer's task succeeded.

  2. Narrow the query with the supported filters:

    Parameter Usage
    provider Select twilio or teams_phone_extensibility for the providers in this article.
    status Select in_progress, success, or failed.
    started_after Include calls that started at or after this Unix timestamp in seconds.
    started_before Include calls that started at or before this Unix timestamp in seconds.
    limit Request 1–100 records per page; the default is 20.
    order Use desc for newest first or asc for oldest first.

    For example, append &provider=twilio&started_after={startTime}&started_before={endTime} to the request. Replace the time placeholders with Unix seconds for your investigation window, with the start at or before the end. Use the project and agent that handled the call.

  3. If has_more is true, copy last_id into after to read the next page. Keep the same filters and order:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls?api-version=v1&status=failed&order=desc&limit=20&after={lastId}
    Authorization: Bearer <access-token>
    

    Pass cursor values exactly as returned, URL-encoded when needed. Use either after or before in a request. To read toward the previous page, use first_id as before. Results reflect current call state, so active-call lists can change between requests.

  4. Copy a call's id from data and read its detailed record:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}?api-version=v1
    Authorization: Bearer <access-token>
    

    Inspect these fields to identify where the call stopped:

    Field What to inspect
    status, phase, end_reason The overall lifecycle result, the phase reached, and the final reason.
    timing Milestones for answering, media connection, session readiness, and first caller or agent audio. Present milestones show which stages were observed.
    events Read events in sequence order. Compare name, outcome, reason, and provider codes to find the failed operation.
    events_truncated If true, the timeline omits older events. Use the trace and provider logs for additional context.
    provider_call_id, provider_status_code, provider_sub_code, provider_message Correlate the result with your provider's call diagnostics. These fields are present when available.
    trace Check status and use trace_id for trace lookup. Use conversation_id for stored conversation reads when a voice session was created.

    Timestamps are Unix seconds; duration_ms is milliseconds. Event observed_at records when the service observed an event. occurred_at, when present, records the provider's event time.

Read the conversation and recording

Conversation APIs apply to stored inbound and outbound voice sessions. Enable store: true in the agent definition to capture transcripts and audio. For the inbound support example, get the conversation ID from the call record's trace.conversation_id when available.

  1. List stored conversations to find the session you want to inspect:

    conversations = project_client.voice_agents.conversations
    for conversation in conversations.list(
        agent_name=agent_name, order="desc", limit=20
    ):
        print(conversation.id, conversation.status)
    

    Reference: AIProjectClient.

  2. Replace <conversation-id> with the selected ID. Read its storage status and items in conversation order:

    conversation_id = "<conversation-id>"
    conversation = conversations.get(
        agent_name=agent_name, conversation_id=conversation_id
    )
    print(conversation.status, conversation.last_error)
    for item in conversations.list_items(
        agent_name=agent_name,
        conversation_id=conversation_id,
        order="asc",
        limit=100,
    ):
        print(item.as_dict())
    

    Reference: AIProjectClient.

  3. To inspect individual model turns, list their responses:

    for response in conversations.list_responses(
        agent_name=agent_name,
        conversation_id=conversation_id,
        order="asc",
        limit=20,
    ):
        print(response.as_dict())
    

    Reference: AIProjectClient.

  4. When the conversation's status is completed, read the recording metadata:

    recording = conversations.get_audio(
        agent_name=agent_name, conversation_id=conversation_id
    )
    print(recording.as_dict())
    

    Reference: AIProjectClient.

    For Foundry-managed storage, stream the WAV to a local file:

    with open("conversation.wav", "wb") as audio_file:
        for chunk in conversations.download_audio(
            agent_name=agent_name, conversation_id=conversation_id
        ):
            audio_file.write(chunk)
    

    Reference: AIProjectClient.

    For bring-your-own storage, read the returned blob_uri with your storage credentials. If the recording is still being prepared, read the conversation status and retry after the response's Retry-After interval when provided.

  1. To discover stored conversations, list the agent's conversation collection:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations?api-version=v1&order=desc&limit=20
    Authorization: Bearer <access-token>
    

    Use the conversation id returned by this API. For an outbound investigation, use the agent, calling time, and your application and provider logs to locate the matching trace and conversation. The job response exposes job progress; conversation IDs come from session telemetry or the conversation API.

  2. Read a selected conversation to check its storage status:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}?api-version=v1
    Authorization: Bearer <access-token>
    

    status: in_progress means the call is active or its conversation data is still being saved. completed means the stored conversation is ready. For failed, inspect last_error; any items and per-turn audio already stored remain available.

  3. Read the stored items in conversation order:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}/items?api-version=v1&order=asc&limit=100
    Authorization: Bearer <access-token>
    

    Inspect each item's type, role, content, and available tool information. Follow has_more and last_id with after to read the complete history. Private collection uses an output_ref; verify the outcome in your business service while keeping the collected value private.

  4. To inspect model turns, list the conversation's responses:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}/responses?api-version=v1&order=asc&limit=20
    Authorization: Bearer <access-token>
    

    A response identifies one model turn. Read a selected response at /agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}/responses/{responseId}?api-version=v1. Its /items subresource provides paged output items when you need the full output. Use the same authorization header.

  5. After the call ends, retrieve metadata for its merged recording:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}/audio?api-version=v1
    Authorization: Bearer <access-token>
    

    The metadata describes the stereo recording, with caller audio on the left and agent audio on the right. For bring-your-own storage, use the returned blob_uri with your storage credentials. For Foundry-managed storage, download the WAV through the authenticated content endpoint:

    GET {projectEndpoint}/agents/{agentName}/endpoint/protocols/voice/conversations/{conversationId}/audio/content?api-version=v1
    Authorization: Bearer <access-token>
    

    For a 409 Conflict, read the error and conversation status. Retry when the recording is still being prepared, honoring Retry-After when supplied. If finalization failed, inspect the conversation's last_error. For bring-your-own storage, use blob_uri to read the recording directly.

    A 404 Not Found can indicate that the conversation or audio wasn't stored or is no longer available. Enabling storage affects subsequent sessions. See Conversation storage and retention.

Troubleshoot telephony

Use call records, conversation data, and traces to find where a call failed and choose the next troubleshooting step.

  1. Record the project, agent name and version, call direction, provider, UTC time window, and available call, job, and operation IDs.
  2. For inbound calls, query the call result. Inspect phase, timing, and events to locate the first failing stage. If the record is absent, confirm the project, agent, and query filters, then inspect binding configuration and provider webhook delivery.
  3. For outbound calls, query the call-job result. Check status, attempt_count, next_attempt_at, terminal_reason, and the schedule. For a campaign, first check its validation operation and row-level errors, then inspect the recipient jobs.
  4. When the call reaches the agent, read the stored conversation and inspect the model and tool spans in the Foundry trace view. Confirm the tool's actual result and the provider or business-service outcome before retrying an action.
  5. Use the symptom table to correct the identified configuration, then verify the affected stage with an approved test call. Keep the original and new identifiers so you can compare results.

Resolve deployment errors

Use the following checks for azd errors. For the call-query examples that follow, select Python SDK or REST API.

Symptom What to check
Voice options aren't available or the extension doesn't load Check for azd version 1.37.0 or later and azure.ai.agents version 1.2.0 or later. Follow the installation guidance to update the tools.
A binding differs from the declaration, or multiple bindings match List the current bindings and confirm the intended provider identity and connection. Reconcile the remote configuration with Python or REST before redeploying.
Deployment reports an unconfirmed write or partial completion Read the remote bindings before retrying. Some bindings might already exist even though deployment didn't finish successfully.
Transfer targets differ from the declaration Inspect the agent-level target list. Reconcile it with Python or REST; deployment doesn't overwrite a nonempty list.

Query an inbound call result

Use the Calls API to find a recent inbound call and read its outcome. Complete the interface setup for Python or REST. The response excerpts use illustrative values; use the identifiers returned by your own requests.

  1. List recent calls and identify the call by its time and provider:

    for call in telephony.list_calls(
        agent_name=agent_name, order="desc", limit=20
    ):
        print(call.id, call.provider, call.started_at, call.status)
    

    Reference: Azure AI Projects client library for Python.

  2. Replace <call-id> with that call's ID and inspect its outcome:

    call = telephony.get_call(agent_name=agent_name, call_id="<call-id>")
    print(call.status, call.phase, call.end_reason)
    print(call.timing.as_dict() if call.timing else {})
    print(call.provider_status_code, call.provider_sub_code)
    print(call.provider_message)
    

    Reference: Azure AI Projects client library for Python.

    For example, status="failed" with end_reason="answer_failed" directs you to the provider's answer operation. Inspect the provider codes and message, then check credentials and connectivity. Use the detailed call record to examine lifecycle events and trace identifiers.

  1. List recent calls, including both successful and failed calls:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls?api-version=v1&order=desc&limit=20
    Authorization: Bearer <access-token>
    

    Find the call in the response's data array by its start time, provider, and available caller details. For a longer investigation window, use the time filters and pagination. Copy that entry's service-generated id into {callId}.

  2. Read the selected call:

    GET {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}?api-version=v1
    Authorization: Bearer <access-token>
    

    A successful query returns 200 OK, even when the call itself failed. For example, this response excerpt shows a failure while answering an inbound call:

    {
      "id": "example-inbound-call-id",
      "provider_call_id": "example-provider-call-id",
      "status": "failed",
      "phase": "failed",
      "started_at": 1794211200,
      "ended_at": 1794211202,
      "end_reason": "answer_failed",
      "timing": {
        "received_at": 1794211200,
        "answer_requested_at": 1794211201,
        "ended_at": 1794211202,
        "timestamp_source": "gateway"
      }
    }
    
  3. Interpret the response body and choose the next check:

    Result Interpretation and next step
    status: in_progress Setup or conversation activity is still in progress. Read the same call again and inspect its milestones.
    answered_at is present The provider reported the call as answered. Check media_connected_at and agent_session_ready_at for media and agent readiness.
    status: success The call lifecycle ended successfully. Read the stored conversation or business-service result to verify the customer's task.
    status: failed Read end_reason, the lifecycle events, and any provider diagnostic fields. Use provider_call_id to locate the call in the provider's logs.

    For an answer_failed result, inspect the provider's answer operation. Read provider_status_code, provider_sub_code, and provider_message when returned, then check credentials and provider connectivity. When trace.trace_id is available, continue with trace lookup.

Query an outbound call result

For a direct outbound call or a campaign recipient, use the call-job ID returned when the job was created. To find a campaign's jobs, filter the job list by campaign_name.

Read the job's outcome and attempt count. Replace <call-job-id> with the selected job ID:

job = telephony.get_call_job(
    agent_name=agent_name, call_job_id="<call-job-id>"
)
print(job.status, job.attempt_count, job.terminal_reason)
print(job.next_attempt_at)

Reference: Azure AI Projects client library for Python.

For example, status="completed", attempt_count=3, and terminal_reason="no_answer" mean the job ended after three attempts without an answer. For a job still in progress, continue monitoring it. For a connected conversation, use its call record and trace to read stored dialogue.

  1. Read the job using the same project endpoint and authentication:

    GET {projectEndpoint}/agents/{agentName}/telephony_call_jobs/{callJobId}?api-version=v1
    Authorization: Bearer <access-token>
    

    This illustrative response excerpt shows a job whose permitted attempts ended without an answer:

    {
      "id": "example-call-job-id",
      "agent_name": "contoso-outbound-reminders",
      "status": "completed",
      "attempt_count": 3,
      "retry_policy": {
        "type": "fixed_interval",
        "max_attempts": 3,
        "interval": 300
      },
      "terminal_reason": "no_answer"
    }
    
  2. Read status together with terminal_reason and attempt_count. Here, the job is complete because all three permitted attempts finished. The no_answer reason identifies the calling outcome. completed alone doesn't establish that the recipient answered or the reminder was delivered.

  3. For a job still in progress, continue reading it using the polling guidance. For a completed conversation, inspect its stored items and recording. Use job IDs for job queries and Calls API IDs for call records and live-call actions.

Find the trace in Azure Monitor

Use this query when the call record provides trace.trace_id and your project has a connected Application Insights resource.

  1. Open Logs in the Log Analytics workspace linked to that Application Insights resource. Set a time range that includes the call and allow time for telemetry ingestion. Your identity needs the trace-viewing permissions.

  2. Replace <trace-id> with the returned W3C trace ID and run this Kusto Query Language (KQL) query:

    let callTraceId = "<trace-id>";
    union AppRequests, AppDependencies
    | where OperationId == callTraceId
    | project TimeGenerated, Name, Success, ResultCode, DurationMs,
        OperationId, ParentId, Id
    | order by TimeGenerated asc
    

    Reference: AppRequests table and AppDependencies table.

  3. Inspect the returned request and dependency spans to find failures or long durations. Use the provider call ID in your provider's diagnostics to compare signaling and media events with the Foundry timeline.

This example uses Log Analytics workspace table names. If the query returns no rows, check the selected workspace, time range, trace availability, ingestion delay, and permissions. Conversation storage and trace capture have separate settings.

Resolve common symptoms

Symptom What to check
Busy signal and no Azure Communication Services event Teams number activation, license, PSTN connectivity, calling bot channel, TPE association, synchronization, and Azure Communication Services consent.
Azure Communication Services receives the call but Foundry reports no binding Compare IncomingCall.data.to.rawId with 28:orgid:<resource_account_object_id> constructed from the binding's GUID. Keep the prefix out of the REST binding field.
Event Grid validation fails Endpoint, tenant, webhook audience, app-role assignment, delivery identity, and Event Grid write access.
Secure setup reports a Graph permission error Ask a tenant administrator to grant the approved application-management permissions and retry.
Azure Communication Services AnswerCall returns 401 or 403 Project connection target, project managed identity, Azure Communication Services role assignment, and RBAC propagation.
Symptom What to check
Call connects but is silent Compare answered_at, media_connected_at, agent_session_ready_at, and first-audio milestones in timing. For the stage that stalls, check media reachability and PCM format, model and voice configuration, or the playback path.
Call disconnects unexpectedly Callback reachability, media errors, service limits, and correlation logs.
The wrong agent answers Confirm the agent that owns the binding collection and inspect that agent's active version.
The number doesn't appear after refresh List the agent's bindings and confirm that the number is connected to the intended agent.
A binding update, deletion, or transfer-target replacement fails with a precondition error Read the resource again, review any concurrent changes, and use the latest ETag in If-Match.
Outbound creation returns 400 Bad Request Check connection_name, the provider-specific source, the E.164 destination, required structured inputs, and the Idempotency-Key header.
Outbound creation returns 409 Conflict The idempotency key was used with a different request. Reuse the original request to recover its job, or use a new key for a new call intent.
Outbound creation returns 503 Service Unavailable Save the response and request details. Contact support if the error persists.
Call-job cancellation returns 409 Conflict Read the latest job and ETag. Retry with the current ETag only if the call hasn't connected and cancellation is still appropriate.
An outbound job is accepted but the destination doesn't ring Read the job's status, attempt count, schedule, and reason. Check caller authorization and provider connectivity; 202 Accepted isn't confirmation of a connected call.
Calls API returns no matching records Confirm the project, agent, provider, time window, and pagination. Use the call-job API to inspect outbound work. Check inbound webhook delivery and binding ownership when the expected inbound record is absent.
Conversation or audio reads return 404 Confirm the agent and conversation ID, that conversation storage was enabled for the session, and that the data is within its retention period. Use call history and provider diagnostics for calls that ended before a conversation was created.
Merged recording reads return 409 Inspect the error and conversation status. Retry pending finalization with Retry-After when supplied. For failed finalization, inspect last_error; for bring-your-own storage, read the returned blob_uri with storage credentials.
A system tool isn't invoked Check that the saved agent definition includes the tool in tools, sets tool_choice to auto, and explains when to use it. See Troubleshoot tool availability.
A transfer or SMS result is uncertain Check the tool result and the provider's call or message status before retrying.

Disconnect a number

Remove the inbound mapping when you no longer want the number to route calls to this agent. Outbound jobs don't require a binding; cancel any unwanted jobs separately.

  1. Remove the binding's declaration from azure.yaml or the referenced service definition so a later deployment doesn't recreate it. If it was the last binding, remove the telephony block. This local edit doesn't delete the remote binding.
  2. Select Python SDK or REST API at the top of this article. Follow the deletion steps with the service-generated binding ID and its current ETag.
  3. Delete test bindings before deleting their agent. Don't use azd down just to disconnect a number; it can delete the environment's Azure resources.
  1. Open the agent Channels tab.
  2. In Phone numbers, open the number's actions menu.
  3. Select Disconnect number.
  4. Confirm.

Read the binding again and use its current ETag to delete it:

from azure.core import MatchConditions

binding_id = "<binding-id>"
binding, binding_headers = telephony.get_binding(
    agent_name=agent_name,
    binding_id=binding_id,
    cls=lambda response, result, _: (result, response.http_response.headers),
)
telephony.delete_binding(
    agent_name=agent_name,
    binding_id=binding_id,
    etag=binding_headers["ETag"],
    match_condition=MatchConditions.IfNotModified,
)

Reference: Azure AI Projects client library for Python.

The method returns None on success.

Read the binding to get its current ETag, and then delete it by using that value in If-Match.

GET {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1
Authorization: Bearer <access-token>
DELETE {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1
Authorization: Bearer <access-token>
If-Match: <etag-from-latest-binding-read>

A successful deletion returns 204 No Content.

Disconnecting removes the Foundry binding. It doesn't:

  • Release the Teams number.
  • Remove the Teams resource account.
  • Delete Azure Communication Services.
  • Remove the bot or app registration.
  • Revoke Teams Phone extensibility consent.

Coordinate upstream cleanup separately.

Security checklist

  • Use Microsoft Entra authentication for Foundry API requests.
  • Use the exact public Foundry project webhook endpoint.
  • Don't persist service-generated call callback or media tokens.
  • Confirm the binding target before update or deletion.
  • Apply recording, consent, disclosure, retention, and privacy requirements.
  • Prevent sensitive caller data from being read aloud or unnecessarily stored.
  • Prefer managed identity for the Azure Communication Services connection.
  • Don't share Azure Communication Services keys, connection strings, tokens, bot secrets, or portal cookies.
  • For inbound calls, validate that the Event Grid topic is the intended Azure Communication Services resource.
  • Keep webhook audience and Event Grid delivery identity concepts separate.
  • Use a dedicated single-tenant webhook application when governance requires it.

Use these guides to configure and validate the agent behind your telephony channel: