Connect a voice agent to a Twilio phone number

Connect a Microsoft Foundry voice-first agent to a Twilio phone number so callers reach the agent over the phone.

You can now directly import a phone number you purchased from Twilio 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

• Existing phone numbers purchased from Twilio.
• Twilio Account SID and Auth Token.
• A saved voice-first agent in a Foundry project that passes browser testing. See Quickstart: Create a voice-first prompt agent.

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": "twilio", "value": "28:orgid:00000000-0000-0000-0000-000000000000" }
    }
  ]
}

A twilio destination can be a Twilio 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 Twilio 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. From a controlled caller, call the configured number.
2. Confirm the agent answers.
3. Complete a short conversation.
4. Interrupt the agent.
5. Use one safe tool or knowledge path.
6. Test the approved human-handoff behavior.
7. End the call.
8. Confirm that monitoring and trace data appear.

Record:

• Test timestamp and time zone.
• Called number.
• Callee identifier.
• Azure Communication Services resource ID.
• Agent name and version.
• Event Grid delivery result.
• Azure Communication Services call correlation ID.

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 services event	Twilio number activation.
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.
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 Twilio number.
• Remove the Twilio resource account.
• Delete Azure Communication Services.
• Remove the bot or app registration.
• Revoke Twilio Phone Extensibility consent.

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.
• 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-first agent
• Voice agent tracing, monitoring, and evaluation.
• Best practices for voice-first agents
• Call automation in Azure Communication Services
• Azure Event Grid security and authentication