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.

TwiML

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:

https://website.com/twiml.php?customParameter=xxxxxxxxx&customValue=true

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

<Dial><Sip>sip:+14158675309@your.doma.in?X-customParameter=xxxxxxxx&X-customValue=true</Sip></Dial>

to send X-customParameter and X-customValue on all originated calls.

Client (JavaScript)

Twilio.Device.connect() has an optional params argument which allows for a JavaScript object to be passed 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 capability token.

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

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"?>
<Response>
  <Dial>
    <Client>
      <Identity>alice</Identity>
      <Parameter name="foo" value="bar"/>
      <Parameter name="baz" value="123"/>
    </Client>
  </Dial>
</Response>

device.on('incoming', connection => {
  assert.equal(connection.customParameters.get('foo'), 'bar');
  assert.equal(connection.customParameters.get('baz'), '123');
});

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)

Custom parameters can be added to CallInvite via the getCustomParamaters()method:

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

callInvite.getCustomParameters() 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"?>
  <Response>
    <Dial callerId="client:alice">
      <Client>
        <Identity>bob</Identity>
        <Parameter name="caller_first_name" value="alice" />
        <Parameter name="caller_last_name" value="smith" />
      </Client>
    </Dial>
  </Response>

callInvite.customParameters:

  {
    "caller_first_name" = "alice";
    "caller_last_name" = "smith";
  }

SIP Domains

Add the custom headers to the SIP URI:

sip:username@yourdomain.us1.sip.twilio.com?customParameter=xxxxxxxxxx&customValue=true

SIP Trunking Origination

It is possible to send any SIP header by appending them to the origination SIP URI beginning with the X- prefix.

For example, you could configure

sip:+14158675309@your.doma.in?X-customParameter=xxxxxxxx&X-customValue=true

to send X-customParameter and X-customValue on all originated calls.