SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site,, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Passing Custom Information via Requests to Twilio

Twilio offers users a number of methods for passing custom information in HTTP query strings and SIP URIs. Please read on for more details.


If you have custom headers or tracking details you want associated with your requests, you can pass the details in the voice request URL. Then, when the API call is answered, you will receive a callback to their server with those details.

For example, if you have two custom headers, let's call them customParameter and customValue, you would construct the voice request URL like this:

Note: Twilio's request to this URL must still be responded to with valid TwiML call processing instructions.

<Dial><Sip> TwiML

Any SIP headers can be sent by appending them to the end of the <Sip> TwiML noun URI with the X- prefix.

For example, you could configure


to send X-customHeader1 and X-customHeader2 on all originated calls.

You can send multiple params and value as part of the same X- header

For example, you could configure


UUI (User-to-User Information) header can be sent without prepending X-


For more details, see below...

Sending SIP X-Headers

Receiving SIP X-Headers

Custom Headers

Voice Javascript (JS) SDK (Formerly Twilio Client)

Sending custom params FROM the SDK to your app

The Voice Javascript (JS) SDK includes a device.connect() function which takes an optional ConnectOptions argument. The ConnectOptions object is a JavaScript object with optional paramsrtcConfiguration, and rtcConstraints properties.

You can use the params property to pass information to the application as POST/GET parameters. 

For example, the following code will pass the params app=Support and location=Seattle to the Twilio application associated with this Device's access token.

var call = Twilio.Device.connect({ app:"Support", location:"Seattle"});

See for more information.

Sending custom params TO the SDK from your app

To deliver parameters to a Client instance using version 1.6 or later, use the <Parameter> noun of the <Client> verb and these parameters will be added to Connection.customParameters. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Parameter name="displayName" value="Alice"/>
<Parameter name="customerID" value="A1285C2E"/>
<Parameter name="selectedProductID" value="00242424"/>
if (connection.customParameters.hasOwnProperty("displayName")) {
    let displayName = connection.customParameters.get("displayName");
    // Do something with displayName

if (connection.customParameters.hasOwnProperty("customerID")) {
    let customerID = connection.customParameters.get("customerID");
    // Do something with customerID

if (connection.customParameters.hasOwnProperty("selectedProductID")) {
   let selectedProductID = connection.customParameters.get("selectedProductID");
   // Do something with selectedProductID 

Note: The following restrictions apply to the Parameter noun:

  • Parameter name must be a string, up to 32 bytes.
  • Parameter value must be a string, up to 128 bytes.
  • Up to 8 parameters can be sent per <Dial>.

Client 1.x/2.x (Mobile)

There is no method to pass custom information via mobile SDK version 1.x/2.x on Android or iOS.

Programmable Voice SDK Android 3.0 (Mobile)

You can now send parameters from the caller to the callee when you make a call. The key/value data is sent from the Voice SDK to your TwiML Server Application, and passed into TwiML to reach the callee.

Custom parameters can be sent to your TwiML Server Application by specifying them in the ConnectOptions builder:

final Map<String, String> params = new HashMap<>();
params.put("caller_first_name", "alice");
params.put("caller_last_name", "smith");

ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)

call = Voice.connect(context, connectOptions, listener);

These will arrive as either HTTP POST parameters or URL query parameters, depending on which HTTP method you configured for your TwiML Server Application in the console.

Once available on your TwiML Server Application you can use them to populate your TwiML response. Parameters can be sent to a callee using the <Dial> TwiML verb with the <Parameter> attribute to specify your key/value parameters:

<?xml version="1.0" encoding="UTF-8"?>
        <Dial answerOnBridge="false" callerId="client:alice">
                <Parameter name="caller_first_name" value="alice"  />
                <Parameter name="caller_last_name" value="smith"  />

The callInvite.getCustomParameters() method returns a map of key-value pair passed in the TwiML.

"caller_first_name" -> "alice"
"caller_last_name" -> "smith" 

Programmable Voice SDK iOS 3.0 (Mobile)

Custom parameters can be added using the customParameters property of TVOCallInvite.

  <?xml version="1.0" encoding="UTF-8"?>
    <Dial callerId="client:alice">
        <Parameter name="caller_first_name" value="alice" />
        <Parameter name="caller_last_name" value="smith" />


    "caller_first_name" = "alice";
    "caller_last_name" = "smith";

Passing Custom Parameters to Client application via Calls API

curl -X POST \
--data-urlencode "Url=" \
--data-urlencode "To=client:alice?displayName=Alice&customerID=A1285C2E&selectedProductID=00242424" \
--data-urlencode "From=+15018675309" \
-u AC1c41896f44563b7c8194235ee6d267b1:your_auth_token

Passing Custom Parameters to Client application via Conference Add Participant API

curl -X POST \ 
--data-urlencode "From=+15017122661" \
--data-urlencode "To=client:alice?displayName=Alice&customerID=A1285C2E&selectedProductID=00242424" \
-u AC1c41896f44563b7c8194235ee6d267b1:your_auth_token
Have more questions? Submit a request
Powered by Zendesk