How Twilio Flex Uses the TaskRouter Worker contact_uri – Twilio Support

Overview

In Twilio Flex, every agent is represented by a TaskRouter Worker, and each Worker has a contact_uri that acts as the Worker's identity used by Flex and the Twilio Voice SDK. This value is how Flex, TaskRouter, and the Twilio Voice infrastructure know where to send calls and events for that Worker.

Because contact_uri is tightly integrated with Flex orchestration, it must follow a very specific format. Changes to a Worker’s contact_uri can cause voice call failures and other issues, so Flex will automatically generate this value for each Worker.

What You Need To Know

The contact_uri can be found in the Worker's attributes, and behaves as the internal identifier and "address" for the user to receive Voice calls.

The contact_uri is generated from the provided user's email address.

Example of the attribute property:

"contact_uri": "client:ann_2Eveal_40arresteddevelopment_2Ecom"

Frequently Asked Questions

How are Workers created and when is `contact_uri` set?

By default, Flex creates a TaskRouter Worker automatically the first time a user logs into Twilio Flex via SSO:

The SSO identity provides values such as full_name, email, and roles.
Flex uses the Worker's email address to generate the contact_uri.
Flex uses these values to create the TaskRouter Worker, storing these properties in the Worker's attributes.

However, in some implementations, there is a need to create the Worker record before the user's first login. In these cases:

You can create the Worker with the required values (full_name, email, roles, and any other attributes you need).
When the user logs into Flex for the first time, Twilio will automatically generate and add the correct contact_uri for that existing Worker.
- You should not set the contact_uri, as that runs the risk of misconfiguration.

Minimal TaskRouter Worker attributes that need to be supplied:

{
  "email": "ann.veal@arresteddevelopment.com",
  "full_name": "Ann Veal"
  "roles":["admin","wfo.full_access"]
}

Then Twilio will add the necessary contact_uri upon login.

In all cases whether the Worker is created automatically at first login or provisioned in advance Flex should be the component that creates and manages the contact_uri value.

How does Flex uses contact_uri?

The Twilio Voice JavaScript SDK used by the Flex UI registers a client identity with Twilio’s Voice infrastructure based on the Worker’s contact_uri.

If the contact_uri does not match the identity the browser is registered with, incoming and outgoing calls will not reach the agent’s browser, even if the agent appears “available” in the UI.

Why should you not modify contact_uri?

Flex should always handle the creation and management of the TaskRouter Worker contact_uri. Any misconfiguration of this value can prevent Flex users from handling voice calls.

We strongly recommend:

Do not add a contact_uri manually.
Do not change the existing contact_uri.
Do not remove contact_uri from Worker attributes.

Common failure modes when contact_uri is modified:

Agents can log into Flex but never receive or place calls.

If you suspect contact_uri has been altered, you can remove the value entirely so it will be re-created the next time the user logs into Flex.

How is contact_uri derived from the Worker’s email?

Flex uses the Worker's email address as a basis for the client identity, then applies a custom hex-escape encoding to make it safe to use as a client:identifier.

For example:

Email: ann.veal@arresteddevelopment.com

Encoded identity: ann_2Eveal_40arresteddevelopment_2Ecom

Full contact_uri: client:ann_2Eveal_40arresteddevelopment_2Ecom

Encoding rules (for reference only)

This is not standard URL encoding or base64. It is a custom mapping:

Alphanumeric characters (A–Z, a–z, 0–9) → kept as-is.
Non-alphanumeric characters → replaced with _XX, where XX is the uppercase two-digit hexadecimal ASCII code of the character.

Examples:

. (ASCII 0x2E) → _2E
@ (ASCII 0x40) → _40

This design makes the value safe, compact, and reversible, while remaining reasonably human-readable.

Note: This is provided for diagnostics and troubleshooting only. Do not implement your own contact_uri encoding as that could result in misconfigurations and voice degradation for Flex users.

Additional Information

Twilio