Integrate telephony channels with a voice agent

Integrate Microsoft Teams Phone or Twilio with a Microsoft Foundry voice-first agent so callers can reach the agent over the phone.

You can now directly import a phone number you purchased from Teams and connect it to your voice agent.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Prerequisites

• Get Microsoft Teams Calling Plan phone numbers for your tenant.
• Follow the setup for Teams Phone System extensibility.
• A saved voice-first agent in a Foundry project that passes browser testing. See Quickstart: Create a voice-first prompt agent.
• Foundry User role on the project, to create and manage telephony bindings.

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.
• Access to the selected Azure Communication Services resource.
• Permission to create or update a Foundry project connection.
• Permission to create or update telephony bindings.
• Event Grid write permission on the Azure Communication Services 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.

Twilio prerequisites

For the Twilio path, you need:

• A Twilio account with at least one active, voice-capable phone number.
• The Twilio Account SID and Primary Auth Token if you need to create a Foundry project connection.
• Permission to create or read connections in the Foundry project.
• Permission to create telephony bindings for the agent.

Treat the Twilio Auth Token as a secret. Enter it only in the Foundry connection dialog, and don’t include it in documentation, logs, screenshots, or support requests.

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 Microsoft Teams, 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.

For Twilio, Foundry uses the selected project connection to discover the numbers in your Twilio account and create a binding for each number you select. You don’t create an Azure Communication Services resource or Event Grid subscription for the Twilio path.

Compare the channel integrations

Path	Use it when	What you provide in Foundry
Microsoft Teams Phone Extensibility	Your organization owns a service number in Teams and routes it through a Teams resource account to Azure Communication Services.	28:orgid:<resource-account-object-id>
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.

Direct SIP and Azure Communication Services purchased numbers aren’t supported customer options in the current Add a number menu. The Twilio option appears only in supported public-cloud environments.

Understand telephony bindings

A telephony binding connects a provider-specific destination to one voice agent in your project. For a Teams Phone REST binding, set provider to teams_phone_extension and pass the resource account GUID in resource_account_object_id. The incoming-call identifier 28:orgid:{resource-account-guid} isn’t the value of that REST property.

A binding holds:

• A service-generated binding id.
• The provider and its destination, such as the Teams resource account object ID.
• A status of active or suspended, which lets you take a number offline without deleting the mapping.
• A connection that names the Foundry project connection for your provider. Secrets aren’t stored in the binding itself.
• An incoming_call_url that the service generates for incoming-call delivery.

The agent that owns the binding is identified by the request path. Create and list bindings at {projectEndpoint}/agents/{agentName}/telephony/bindings. To get, update, or delete one binding, append /{bindingId}.

Binding reads return an ETag. Send that value in If-Match when updating or deleting the binding to avoid overwriting a concurrent change. Transfer targets are configured separately for the agent, not on each binding.

Prepare Microsoft 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. Place a controlled call and confirm that Azure Communication Services emits Microsoft.Communication.IncomingCall.

Provide the Foundry owner with:

• The callable Teams number.
• The Azure Communication Services ARM resource ID.
• The resource-account object ID.
• Confirmation that Azure Communication Services received the test call.

The expected incoming destination is:

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

Configure transfer to a person

An agent that can’t complete a request should reach a human rather than end the call. Configure named transfer targets for the agent. These targets are separate from its telephony bindings.

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>
Foundry-Features: VoiceAgents=V1Preview

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>
Foundry-Features: VoiceAgents=V1Preview
Content-Type: application/json
If-Match: <etag-from-latest-transfer-targets-read>

{
  "transfer_targets": [
    {
      "name": "billing",
      "description": "Billing and payment questions",
      "destination": { "kind": "pstn", "value": "[phone]" }
    },
    {
      "name": "operator",
      "description": "A person at the front desk",
      "destination": { "kind": "teams", "value": "28:orgid:00000000-0000-0000-0000-000000000000" }
    }
  ]
}

A teams destination can be a Teams user, or the resource account of a call queue or auto attendant. That’s how a voice agent hands a caller back into an existing Teams call flow.

Give each target a description that says when to use it. The agent chooses based on that text.

Transfer requests select a target from the agent’s configured list rather than supplying an arbitrary destination.

Manage a live call

List the agent’s calls, and use the service-generated call id as {callId} in subsequent requests:

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

To transfer an active call to the configured operator target:

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

{ "target": "operator" }

To end an active call, send a separate request with no request body:

POST {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}:end?api-version=v1
Authorization: Bearer <access-token>
Foundry-Features: VoiceAgents=V1Preview

Both operations return the call record. To inspect the call’s current status and lifecycle events, use GET {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}?api-version=v1.

Configure audio for phone calls

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

• Set noise_reduction to azure_deep_noise_suppression for contact center traffic.
• 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

1. Wait for the selected provider and binding changes to propagate. For Microsoft Teams, also allow time for Azure Communication Services and Event Grid propagation.
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.
• For Microsoft Teams, the Azure Communication Services resource ID and Event Grid delivery result.
• For Twilio, the Foundry project connection name.

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.

Troubleshoot telephony

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 the full binding identifier, including prefix and formatting.
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.
Call connects but is silent	Media endpoint reachability, selected model and voice, output device path, and required PCM media format.
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	Query active bindings and confirm provisioning completed; don’t rely only on temporary browser state.
Twilio numbers don’t load	Confirm the project connection uses the correct Account SID and Primary Auth Token, and that you can read the connection credentials.
No Twilio numbers can be selected	Confirm the Twilio account owns an active number with the Voice capability.
Twilio rejects the credentials	Update or recreate the project connection with the current Account SID and Primary Auth Token.
A Twilio number is already bound	Use the existing binding or disconnect it from the other agent before retrying.
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.

Disconnect a number

Disconnecting removes the Foundry binding. It doesn’t:

• Release the Teams or Twilio number.
• Remove the Teams resource account.
• Delete Azure Communication Services.
• Remove the bot or app registration.
• Revoke Teams Phone Extensibility consent.
• Delete the Twilio account or the Foundry project connection.

Coordinate upstream cleanup separately.

Security checklist

• Use Microsoft Entra authentication and managed identities.
• Don’t share Azure Communication Services keys, connection strings, tokens, bot secrets, or portal cookies.
• Don’t share Twilio Account SIDs together with Auth Tokens, and rotate an Auth Token if it is exposed.
• Validate that the Event Grid topic is the intended Azure Communication Services resource.
• Use the exact public Foundry project webhook endpoint.
• Keep webhook audience and Event Grid delivery identity concepts separate.
• Use a dedicated single-tenant webhook application when governance requires it.
• 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.

Related content

• Configure a voice agent
• Publish and share a voice-based agent
• Voice agent tracing, monitoring, and evaluation.
• Best practices for voice-based agents
• Call automation in Azure Communication Services
• Manage resource accounts in Microsoft Teams
• Azure Event Grid security and authentication