Issue

In Twilio Flex, each agent (worker) is identified by a unique Worker SID and a contact_uri attribute in TaskRouter. If an agent is unable to accept or make calls such as experiencing constant ringing with no “Accept” button, or outbound call failures, one common cause is a mismatch between the agent’s current identity (especially after SSO migrations) and the contact_uri stored in TaskRouter.

This article explains how to identify and resolve issues caused by a contact URI mismatch, especially after changes to authentication methods or user profiles.

Below is a list of the most common symptoms:

• The affected agent’s Flex UI rings for incoming calls, but the “Accept” button does not appear, or the UI does not respond.
• Outbound calls initiated by the agent fail without clear error messages.
• Other agents are not affected.
• The agent recently migrated to a new SSO provider (e.g., Microsoft Entra) or changed their email/domain.
• The agent’s Worker SID in TaskRouter may have an outdated or mismatched contact_uri.

Cause

• SSO Migration: After switching from Twilio Console credentials to SSO (e.g., Entra), the agent’s identity and contact URI may change.
• Guest Accounts: If the agent’s email domain changes (e.g., using a guest account), the contact URI format may differ.
• Duplicate Worker Profiles: Old worker profiles may remain in TaskRouter, causing tasks to be routed incorrectly.

How to Diagnose

1. Check if the Issue Is Isolated:
   • Confirm that only one agent is affected and others with similar configurations are working as expected.
2. Review Worker Attributes:
   • In the Twilio Console, navigate to TaskRouter > Workspaces > Workers.
   • Compare the contact_uri for the affected worker with those of working agents.
   • Check for duplicate workers with similar names or emails.
3. Check Recent Changes:
   • Was there a recent migration to SSO?
   • Did the agent’s email or domain change?
   • Was the worker profile updated or recreated?

Resolution

1. Update the Worker’s Contact URI:

• In TaskRouter, ensure the Worker SID for the affected agent has a contact_uri that matches their current SSO profile.
• The contact_uri should follow the format used by other working agents (e.g., client:username).

2. Remove or Deactivate Old Worker Profiles:

• If duplicate or outdated worker profiles exist for the agent, remove or deactivate them to prevent routing conflicts.

3. Clear or Reassign Stuck Tasks:

• Check for any pending or stuck tasks assigned to the old profile and clear or reassign them as needed.

4. Test the Solution:

• Have the agent log out and log back in via SSO.
• Test both inbound and outbound calls to confirm the issue is resolved.

Example Scenario

A Flex agent was unable to accept or make calls after their organization migrated to Entra SSO and their email domain changed. Investigation revealed that TaskRouter was still routing tasks to the agent’s old profile with an outdated contact_uri. Updating the worker’s contact_uri to match the new SSO identity and removing the old profile resolved the issue.

Additional Information

• Always keep worker attributes up to date after any changes to authentication or user identity.
• Regularly audit your TaskRouter workers for duplicates or outdated entries.
• If you reference previous support tickets or instructions, ensure all recommended changes have been applied.

Need More Help?

If you continue to experience issues after following these steps, gather the affected Worker SID, current and previous contact URIs, and details of any recent changes, and reach out to your Twilio administrator or support contact for further assistance.