How to Share Information Between Your Applications

Many telephony use-cases require the ability to associate metadata or other application specific information with a call that is being created. For example, when connecting a customer to an agent, you might want to send the customer's ID or their display name to the agent's application so that they can have more information about the customer that is calling. These use cases are often referred to as contextual calling, as you are providing additional context about the call.

Twilio enables these use cases through the use of custom parameters. Custom parameters can be exchanged between your backend and frontend applications (through Twilio) at call connection time.

This guide will show you how to exchange custom parameters between your backend and frontend applications. The diagram below illustrates where custom parameters can be exchanged.

To parameter:

_10

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxxxxxxxx/Calls.json

_10

--data-urlencode "Url=https://website.com/instructions"

_10

--data-urlencode "To=sip:bob@example.com?displayName=Alice&customerID=375d1d60-083b-404d&selectedProductID=87144192-73e2-45a6"

_10

--data-urlencode "From=+15017122661"

_10

-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

When the callee is a Client endpoint, you can pass custom parameters by appending them to the To parameter:

_10

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json

_10

--data-urlencode "From=+15017122661"

_10

--data-urlencode "To=client:agentBob?displayName=Alice&customerID=375d1d60-083b-404d&selectedProductID=87144192-73e2-45a6"

_10

-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

To pass parameters to your application, you specify the custom parameters in the Url parameter. For example, to pass the caller display name, customerID and selectedProductID:

_10

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACxxxxxxxxxx/Calls.json

_10

--data-urlencode "Url=https://website.com/instructions?displayName=Alice&customerID=375d1d60-083b-404d&selectedProductID=87144192-73e2-45a6"

_10

--data-urlencode "To=+1415555555"

_10

--data-urlencode "From=+15017122661"

See Retrieving Custom Parameters for how you can read these parameters in your endpoint applications.

With the Conference Participant Resource, you connect an end point to a conference. You can pass Custom Parameters during call setup. For example, if a customer called in regarding a product, you can pass the customerID and selectedProductID to the agent with the following request:

See Retrieving Custom Parameters for how you can read these parameters in your endpoint applications.

Twilio retrieves the instructions to connect a call by sending a request to the address you configured. Twilio will populate the request with all the custom parameters that was received from the REST API (or from the end points).

For example, if you configured your TwiML app with the request URL https://webstite.com/instructions, Twilio will append all Custom Parameters https://webstite.com/instructions?displayName=Alice&customerID=12345678&selectedProductId=77788 before sending the request to your server at that URL.

The TwiML instructions you respond with can also include custom parameters that Twilio will forward to the end points. You can send custom parameters to Voice JavaScript SK, Voice Mobile SDKs, SIP user agents, and to MediaStreams.

The following TwiML illustrates how you could send a customerID custom parameter to Voice SDKs:

The following TwiML example illustrates how you can send the same parameter to a SIP user agent:

For more information about using custom parameters with SIP user agents, refer to Sending SIP X-Headers, Receiving SIP X-Headers and Custom Headers.

You can also pass custom parameters when starting a Media Stream:

Once Twilio receives the TwiML instructions to connect a call, it will initiate the call to the end point and pass along the associated custom parameters. The end points can now read these parameters. The following sections show how to read custom parameters in the supporting end points.

Continuing from the previous example, you can use call.customParameters to read the custom parameters you sent to your front-end application.

To read the custom parameters sent to your mobile app, use TVOCallInvite.customParameters (iOS), CallInvite.getCustomParameters() (Android).

The parameters can then be retrieved from the Start Message start.customParameters attribute.

Just like you can pass custom parameters from your infrastructure to your frontend applications, the Twilio Voice SDKs allow you to pass Customer Parameters when connecting to Twilio.

Rate this page:

12345