Twilio Voice connects phone calls to workflows. Use this integration to place outbound calls, list calls, retrieve recordings, and receive call events through a webhook. Supply the call instructions and phone numbers required by the selected operation.
Integrate Twilio Voice into the workflow. Make outbound calls, redirect or hang up live calls, stream call audio to a voice agent over Media Streams, check a number's line type before dialing, and retrieve call details, recordings, and transcriptions.
Make an outbound phone call using Twilio Voice API. Run TwiML from a URL or inline, or connect the call audio to a wss:// WebSocket with Media Streams for a live voice agent.
| Parameter | Type | Required | Description |
|---|
to | string | Yes | Phone number to call in E.164 format (e.g., +14155551234) |
from | string | Yes | Your Twilio phone number to call from in E.164 format (e.g., +14155559876) |
url | string | No | Webhook URL that returns TwiML instructions for the call (e.g., https://example.com/twiml) |
twiml | string | No | TwiML instructions to execute. Use square brackets instead of angle brackets (e.g., [Response][Say]Hello[/Say][/Response]) |
streamUrl | string | No | wss:// URL of a WebSocket server to stream the call audio to, both ways. Builds <Connect><Stream> TwiML; use instead of URL or TwiML. |
streamParameters | json | No | Custom parameters sent to the WebSocket in the stream start message, as a JSON object (e.g., {"leadId": "123"}) |
statusCallback | string | No | Webhook URL for call status updates |
statusCallbackEvent | string | No | Call progress events sent to the status callback, separated by spaces or commas: initiated, ringing, answered, completed (default completed) |
statusCallbackMethod | string | No | HTTP method for status callback (GET or POST) |
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
record | boolean | No | Whether to record the call |
recordingStatusCallback | string | No | Webhook URL for recording status updates |
timeout | number | No | Time to wait for answer before giving up (seconds, default: 60) |
machineDetection | string | No | Answering machine detection: Enable or DetectMessageEnd |
| Parameter | Type | Description |
|---|
success | boolean | Whether the call was successfully initiated |
callSid | string | Unique identifier for the call |
status | string | Call status (queued, ringing, in-progress, completed, etc.) |
direction | string | Call direction (outbound-api) |
from | string | Phone number the call is from |
to | string | Phone number the call is to |
duration | number | Call duration in seconds |
price | string | Cost of the call |
priceUnit | string | Currency of the price |
error | string | Error message if call failed |
Retrieve a list of calls made to and from an account.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
to | string | No | Filter by calls to this phone number in E.164 format (e.g., +14155551234) |
from | string | No | Filter by calls from this phone number in E.164 format (e.g., +14155559876) |
status | string | No | Filter by call status (e.g., queued, ringing, in-progress, completed, busy, failed, no-answer, canceled) |
startTimeAfter | string | No | Filter calls that started on or after this date (YYYY-MM-DD) |
startTimeBefore | string | No | Filter calls that started on or before this date (YYYY-MM-DD) |
pageSize | number | No | Number of records to return (max 1000, default 50) |
| Parameter | Type | Description |
|---|
success | boolean | Whether the calls were successfully retrieved |
calls | array | Array of call objects |
total | number | Total number of calls returned |
page | number | Current page number |
pageSize | number | Number of calls per page |
error | string | Error message if retrieval failed |
Retrieve call recording information and transcription (if enabled via TwiML).
| Parameter | Type | Required | Description |
|---|
recordingSid | string | Yes | Recording SID to retrieve (e.g., RExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx) |
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
| Parameter | Type | Description |
|---|
success | boolean | Whether the recording was successfully retrieved |
recordingSid | string | Unique identifier for the recording |
callSid | string | Call SID this recording belongs to |
duration | number | Duration of the recording in seconds |
status | string | Recording status (completed, processing, etc.) |
channels | number | Number of channels (1 for mono, 2 for dual) |
source | string | How the recording was created |
mediaUrl | string | URL to download the recording media file |
file | file | Downloaded recording media file |
price | string | Cost of the recording |
priceUnit | string | Currency of the price |
uri | string | Relative URI of the recording resource |
transcriptionText | string | Transcribed text from the recording (if available) |
transcriptionStatus | string | Transcription status (completed, in-progress, failed) |
transcriptionPrice | string | Cost of the transcription |
transcriptionPriceUnit | string | Currency of the transcription price |
error | string | Error message if retrieval failed |
Get one call by SID: its status, numbers, start and end time, duration, price, and answering machine detection result.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
callSid | string | Yes | SID of the call to fetch (starts with CA) |
| Parameter | Type | Description |
|---|
success | boolean | Operation success status |
callSid | string | Call unique identifier |
status | string | Call or recording status |
direction | string | Call direction |
duration | number | Call/recording duration in seconds |
price | string | Cost of the operation |
priceUnit | string | Currency of the price |
recordingSid | string | Recording unique identifier |
channels | number | Number of recording channels |
source | string | Recording source |
mediaUrl | string | URL to download recording |
uri | string | Resource URI |
transcriptionText | string | Transcribed text (only if TwiML includes <Record transcribe="true">) |
transcriptionStatus | string | Transcription status (completed, in-progress, failed) |
calls | array | Array of call objects (for list_calls operation) |
total | number | Total number of calls returned |
page | number | Current page number |
pageSize | number | Number of calls per page |
error | string | Error message if operation failed |
accountSid | string | Twilio Account SID from webhook |
from | string | Caller's phone number (E.164 format) |
to | string | Recipient phone number (your Twilio number) |
callStatus | string | Status of the incoming call (queued, ringing, in-progress, completed, etc.) |
apiVersion | string | Twilio API version |
callerName | string | Caller ID name if available |
forwardedFrom | string | Phone number that forwarded this call |
digits | string | DTMF digits entered by caller (from <Gather>) |
speechResult | string | Speech recognition result (if using <Gather>) |
recordingUrl | string | URL of call recording if available |
raw | string | Complete raw webhook payload as JSON string |
parentCallSid | string | SID of the call that created this leg |
toFormatted | string | Called number, formatted for display |
fromFormatted | string | Caller number, formatted for display |
phoneNumberSid | string | SID of the Twilio number used |
startTime | string | When the call was answered |
endTime | string | When the call ended |
answeredBy | string | Answering machine detection result |
queueTime | number | Milliseconds the call waited in queue |
dateCreated | string | When the resource was created |
dateUpdated | string | When the resource was last updated |
recordings | array | Recordings on this page, newest first (List Recordings) |
count | number | Number of recordings on this page |
nextPageToken | string | Page token for the next page |
nextPage | number | Page index for the next page |
nextPageUri | string | Relative URI of the next page |
conferenceSid | string | Conference SID of a recording |
errorCode | number | Error code of a failed recording |
transcriptionSid | string | Transcription SID |
type | string | Transcription type |
phoneNumber | string | Looked-up number in E.164 format |
nationalFormat | string | Number in national format |
countryCode | string | ISO country code of the number |
callingCountryCode | string | International dialing prefix |
valid | boolean | Whether the number is valid |
validationErrors | array | Reasons the number is invalid |
lineType | string | Line type: mobile, landline, fixedVoip, nonFixedVoip, tollFree, ... |
isLandline | boolean | True when the line type is landline |
isMobile | boolean | True when the line type is mobile |
carrierName | string | Carrier name |
mobileCountryCode | string | Mobile country code of the carrier |
mobileNetworkCode | string | Mobile network code of the carrier |
lineTypeErrorCode | number | Line type lookup error code |
callerType | string | BUSINESS or CONSUMER (US only) |
callerNameErrorCode | number | Caller name lookup error code |
Change a live call: redirect it to a new TwiML URL or inline TwiML, connect its audio to a WebSocket with Media Streams (wss://), or end it with status completed or canceled.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
callSid | string | Yes | SID of the live call to update (starts with CA) |
url | string | No | Absolute URL that returns the TwiML the call should run next |
method | string | No | HTTP method Twilio uses to fetch the TwiML URL: GET or POST (default POST) |
twiml | string | No | TwiML the call should run next (max 4000 characters). Square brackets work in place of angle brackets (e.g., [Response][Say]Hello[/Say][/Response]). |
streamUrl | string | No | wss:// URL of a WebSocket server to stream the call audio to, both ways. Builds <Connect><Stream> TwiML; use instead of TwiML URL or TwiML. |
streamParameters | json | No | Custom parameters sent to the WebSocket in the stream start message, as a JSON object (e.g., {"leadId": "123"}) |
status | string | No | End the call: completed (hangs up any call) or canceled (only cancels a queued or ringing call) |
fallbackUrl | string | No | URL Twilio requests if fetching or running the TwiML URL fails |
statusCallback | string | No | URL for call status updates. Twilio only applies it together with a TwiML URL. |
statusCallbackMethod | string | No | HTTP method for the status callback: GET or POST (default POST) |
timeLimit | number | No | Maximum call duration in seconds |
| Parameter | Type | Description |
|---|
success | boolean | Operation success status |
callSid | string | Call unique identifier |
status | string | Call or recording status |
direction | string | Call direction |
duration | number | Call/recording duration in seconds |
price | string | Cost of the operation |
priceUnit | string | Currency of the price |
recordingSid | string | Recording unique identifier |
channels | number | Number of recording channels |
source | string | Recording source |
mediaUrl | string | URL to download recording |
uri | string | Resource URI |
transcriptionText | string | Transcribed text (only if TwiML includes <Record transcribe="true">) |
transcriptionStatus | string | Transcription status (completed, in-progress, failed) |
calls | array | Array of call objects (for list_calls operation) |
total | number | Total number of calls returned |
page | number | Current page number |
pageSize | number | Number of calls per page |
error | string | Error message if operation failed |
accountSid | string | Twilio Account SID from webhook |
from | string | Caller's phone number (E.164 format) |
to | string | Recipient phone number (your Twilio number) |
callStatus | string | Status of the incoming call (queued, ringing, in-progress, completed, etc.) |
apiVersion | string | Twilio API version |
callerName | string | Caller ID name if available |
forwardedFrom | string | Phone number that forwarded this call |
digits | string | DTMF digits entered by caller (from <Gather>) |
speechResult | string | Speech recognition result (if using <Gather>) |
recordingUrl | string | URL of call recording if available |
raw | string | Complete raw webhook payload as JSON string |
parentCallSid | string | SID of the call that created this leg |
toFormatted | string | Called number, formatted for display |
fromFormatted | string | Caller number, formatted for display |
phoneNumberSid | string | SID of the Twilio number used |
startTime | string | When the call was answered |
endTime | string | When the call ended |
answeredBy | string | Answering machine detection result |
queueTime | number | Milliseconds the call waited in queue |
dateCreated | string | When the resource was created |
dateUpdated | string | When the resource was last updated |
recordings | array | Recordings on this page, newest first (List Recordings) |
count | number | Number of recordings on this page |
nextPageToken | string | Page token for the next page |
nextPage | number | Page index for the next page |
nextPageUri | string | Relative URI of the next page |
conferenceSid | string | Conference SID of a recording |
errorCode | number | Error code of a failed recording |
transcriptionSid | string | Transcription SID |
type | string | Transcription type |
phoneNumber | string | Looked-up number in E.164 format |
nationalFormat | string | Number in national format |
countryCode | string | ISO country code of the number |
callingCountryCode | string | International dialing prefix |
valid | boolean | Whether the number is valid |
validationErrors | array | Reasons the number is invalid |
lineType | string | Line type: mobile, landline, fixedVoip, nonFixedVoip, tollFree, ... |
isLandline | boolean | True when the line type is landline |
isMobile | boolean | True when the line type is mobile |
carrierName | string | Carrier name |
mobileCountryCode | string | Mobile country code of the carrier |
mobileNetworkCode | string | Mobile network code of the carrier |
lineTypeErrorCode | number | Line type lookup error code |
callerType | string | BUSINESS or CONSUMER (US only) |
callerNameErrorCode | number | Caller name lookup error code |
End a live call by setting its status to completed. Works for queued, ringing, and in-progress calls, including a parent call running a Dial.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
callSid | string | Yes | SID of the call to end (starts with CA) |
| Parameter | Type | Description |
|---|
success | boolean | Operation success status |
callSid | string | Call unique identifier |
status | string | Call or recording status |
direction | string | Call direction |
duration | number | Call/recording duration in seconds |
price | string | Cost of the operation |
priceUnit | string | Currency of the price |
recordingSid | string | Recording unique identifier |
channels | number | Number of recording channels |
source | string | Recording source |
mediaUrl | string | URL to download recording |
uri | string | Resource URI |
transcriptionText | string | Transcribed text (only if TwiML includes <Record transcribe="true">) |
transcriptionStatus | string | Transcription status (completed, in-progress, failed) |
calls | array | Array of call objects (for list_calls operation) |
total | number | Total number of calls returned |
page | number | Current page number |
pageSize | number | Number of calls per page |
error | string | Error message if operation failed |
accountSid | string | Twilio Account SID from webhook |
from | string | Caller's phone number (E.164 format) |
to | string | Recipient phone number (your Twilio number) |
callStatus | string | Status of the incoming call (queued, ringing, in-progress, completed, etc.) |
apiVersion | string | Twilio API version |
callerName | string | Caller ID name if available |
forwardedFrom | string | Phone number that forwarded this call |
digits | string | DTMF digits entered by caller (from <Gather>) |
speechResult | string | Speech recognition result (if using <Gather>) |
recordingUrl | string | URL of call recording if available |
raw | string | Complete raw webhook payload as JSON string |
parentCallSid | string | SID of the call that created this leg |
toFormatted | string | Called number, formatted for display |
fromFormatted | string | Caller number, formatted for display |
phoneNumberSid | string | SID of the Twilio number used |
startTime | string | When the call was answered |
endTime | string | When the call ended |
answeredBy | string | Answering machine detection result |
queueTime | number | Milliseconds the call waited in queue |
dateCreated | string | When the resource was created |
dateUpdated | string | When the resource was last updated |
recordings | array | Recordings on this page, newest first (List Recordings) |
count | number | Number of recordings on this page |
nextPageToken | string | Page token for the next page |
nextPage | number | Page index for the next page |
nextPageUri | string | Relative URI of the next page |
conferenceSid | string | Conference SID of a recording |
errorCode | number | Error code of a failed recording |
transcriptionSid | string | Transcription SID |
type | string | Transcription type |
phoneNumber | string | Looked-up number in E.164 format |
nationalFormat | string | Number in national format |
countryCode | string | ISO country code of the number |
callingCountryCode | string | International dialing prefix |
valid | boolean | Whether the number is valid |
validationErrors | array | Reasons the number is invalid |
lineType | string | Line type: mobile, landline, fixedVoip, nonFixedVoip, tollFree, ... |
isLandline | boolean | True when the line type is landline |
isMobile | boolean | True when the line type is mobile |
carrierName | string | Carrier name |
mobileCountryCode | string | Mobile country code of the carrier |
mobileNetworkCode | string | Mobile network code of the carrier |
lineTypeErrorCode | number | Line type lookup error code |
callerType | string | BUSINESS or CONSUMER (US only) |
callerNameErrorCode | number | Caller name lookup error code |
List call recordings on the account, newest first, optionally for one call or a creation date range, with paging.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
callSid | string | No | Only recordings of this call (starts with CA) |
dateCreated | string | No | Only recordings created on this date (YYYY-MM-DD, GMT) |
dateCreatedAfter | string | No | Only recordings created on or after this date (YYYY-MM-DD, GMT) |
dateCreatedBefore | string | No | Only recordings created on or before this date (YYYY-MM-DD, GMT) |
pageSize | number | No | Number of records per page (1 to 1000, default 50) |
page | number | No | Page index to request; pass the nextPage value from a previous call |
pageToken | string | No | Page token to request; pass the nextPageToken value from a previous call |
| Parameter | Type | Description |
|---|
recordings | array | Recordings on this page, newest first |
count | number | Number of recordings on this page |
Get the text of a recording transcription by SID, created by <Record transcribe="true">. Twilio has deprecated Recording Transcriptions in favor of its newer transcription products.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
transcriptionSid | string | Yes | SID of the transcription to fetch (starts with TR) |
| Parameter | Type | Description |
|---|
transcriptionSid | string | Transcription SID (starts with TR) |
recordingSid | string | SID of the recording that was transcribed |
status | string | Transcription status: in-progress, completed, or failed |
transcriptionText | string | Transcribed text, once the status is completed |
duration | number | Length of the transcribed audio in seconds |
price | string | Amount billed for the transcription |
priceUnit | string | Currency of the price (ISO 4217) |
type | string | Transcription type |
dateCreated | string | When the transcription was created (RFC 2822) |
dateUpdated | string | When the transcription was last updated (RFC 2822) |
Validate and format a phone number with Twilio Lookup v2, and optionally get its line type (mobile, landline, VoIP), carrier, and US caller name. Use the line type to skip landlines before placing AI calls or sending SMS. Line type and caller name are paid Lookup packages.
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Twilio Account SID |
authToken | string | Yes | Twilio Auth Token |
phoneNumber | string | Yes | Phone number to look up, in E.164 format (e.g., +14155552671) or national format with Country Code |
fields | string | No | Comma-separated Lookup data packages: line_type_intelligence (paid), caller_name (paid, US only), validation. Leave empty for free basic validation and formatting only. |
countryCode | string | No | ISO 3166-1 alpha-2 country code used when the number is in national format (default US) |
| Parameter | Type | Description |
|---|
phoneNumber | string | Number in E.164 format |
nationalFormat | string | Number in national format |
countryCode | string | ISO 3166-1 alpha-2 country code of the number |
callingCountryCode | string | International dialing prefix |
valid | boolean | Whether the number is a valid phone number |
validationErrors | array | Reasons the number is invalid (e.g., TOO_SHORT, INVALID_COUNTRY_CODE) |
lineType | string | Line type from line_type_intelligence: landline, mobile, fixedVoip, nonFixedVoip, personal, tollFree, premium, sharedCost, uan, voicemail, pager, or unknown |
isLandline | boolean | True when the line type is landline; null when line type was not requested |
isMobile | boolean | True when the line type is mobile; null when line type was not requested |
carrierName | string | Name of the carrier |
mobileCountryCode | string | Three-digit mobile country code of the carrier |
mobileNetworkCode | string | Mobile network code of the carrier (mobile numbers only) |
lineTypeErrorCode | number | Error code for the line type lookup, if it failed |
callerName | string | Name of the number owner (US carriers only) |
callerType | string | BUSINESS or CONSUMER (US carriers only) |
callerNameErrorCode | number | Error code for the caller name lookup, if it failed |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow when a phone call is received via Twilio Voice, or when a call you placed reports a status change (status callback)
| Parameter | Type | Required | Description |
|---|
accountSid | string | Yes | Your Twilio Account SID from the Twilio Console |
authToken | string | Yes | Your Twilio Auth Token for webhook signature verification |
twimlResponse | string | No | TwiML instructions to return immediately to Twilio. Use square brackets instead of angle brackets (e.g., [Response] instead of <Response>). This controls what happens when the call comes in (e.g., play a message, record, gather input). Your workflow will execute in the background. |
| Parameter | Type | Description |
|---|
callSid | string | Unique identifier for this call |
accountSid | string | Twilio Account SID |
from | string | Caller's phone number (E.164 format) |
to | string | Recipient phone number (your Twilio number) |
callStatus | string | Status of the call (queued, ringing, in-progress, completed, etc.) |
direction | string | Call direction: inbound or outbound |
apiVersion | string | Twilio API version |
callerName | string | Caller ID name if available |
forwardedFrom | string | Phone number that forwarded this call |
digits | string | DTMF digits entered by caller (from <Gather>) |
speechResult | string | Speech recognition result (if using <Gather> with speech) |
recordingUrl | string | URL of call recording if available |
recordingSid | string | Recording SID if available |
called | string | Phone number that was called (same as "to") |
caller | string | Phone number of the caller (same as "from") |
toCity | string | City of the called number |
toState | string | State/province of the called number |
toZip | string | Zip/postal code of the called number |
toCountry | string | Country of the called number |
fromCity | string | City of the caller |
fromState | string | State/province of the caller |
fromZip | string | Zip/postal code of the caller |
fromCountry | string | Country of the caller |
calledCity | string | City of the called number (same as toCity) |
calledState | string | State of the called number (same as toState) |
calledZip | string | Zip code of the called number (same as toZip) |
calledCountry | string | Country of the called number (same as toCountry) |
callerCity | string | City of the caller (same as fromCity) |
callerState | string | State of the caller (same as fromState) |
callerZip | string | Zip code of the caller (same as fromZip) |
callerCountry | string | Country of the caller (same as fromCountry) |
callToken | string | Twilio call token for authentication |
parentCallSid | string | SID of the call that created this call leg, if any |
callDuration | string | Call length in seconds, on terminal status callbacks (completed, busy, failed, no-answer, canceled) |
duration | string | Billed call length in minutes, on the completed status callback |
sipResponseCode | string | SIP response code of the call, on terminal status callbacks |
timestamp | string | When the status callback event fired (UTC, RFC 2822) |
callbackSource | string | Source of a status callback (call-progress-events) |
sequenceNumber | string | Order of this status callback among the events of the call, starting at 0 |
answeredBy | string | Answering machine detection result when detection is enabled: human, machine_start, machine_end_beep, machine_end_silence, machine_end_other, fax, or unknown |
machineDetectionDuration | string | Milliseconds answering machine detection took, on async detection callbacks |
recordingDuration | string | Recording length in seconds, when a recording is attached |
recordingStatus | string | Recording status on recording status callbacks (in-progress, completed, absent) |
stirStatus | string | STIR/SHAKEN attestation of the call, when Twilio provides it |
raw | string | Complete raw webhook payload from Twilio as JSON string |