Objective

What is a Flex Location?

A Flex Location represents a physical or logical site used by your agents. This can be an office or general location where your agents work from. Each location is associated with one or more Voice Edges. Voice Edges are Twilio edge locations optimized for real-time voice connectivity.

Locations allow Flex to route voice traffic based on where an agent is assigned, which improves reliability and call quality.

Product

Twilio Flex

Procedure

How to Configure Locations in a Flex Account

To define a new location, specify the following parameters in your Flex Configuration Service under ui_attributes:

name (string)

A unique name for the location. This name is referenced in user settings and used as the default location when Flex launches.

edge (string or array of strings)

A list of Voice Edges associated with this location.

Guidelines:

• The first edge in the list is the default edge.
• Any additional edges operate as fallbacks in the order listed.
• You may include "roaming" as one of the options. Roaming allows Flex to fall back to the public internet if all Interconnect or private edge paths fail.

Example

"locations": [
  {
    "name": "Singapore Office",
    "edge": [
      "singapore-ix",
      "singapore",
      "roaming"
    ]
  },
  {
    "name": "San Francisco Office",
    "edge": [
      "sanjose-ix",
      "ashburn-ix",
      "ashburn"
    ]
  }
]

Getting the Current Configuration

Before making any updates, fetch your existing Flex configuration.

curl --location --request GET 'https://flex-api.twilio.com/v1/Configuration' \
  --header 'Authorization: Basic XXX'

Updating the Configuration

Updates must be merged with the ui_attributes returned from the GET request. You should always include your existing configuration to avoid overwriting unrelated settings.

curl --location --request POST 'https://flex-api.twilio.com/v1/Configuration' \
  --header 'Authorization: Basic XXX' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "account_sid":"AC123",
    "ui_attributes": {
      "locations": [
        {
          "name": "Singapore Office",
          "edge": [
            "singapore-ix",
            "singapore",
            "roaming"
          ]
        },
        {
          "name": "San Francisco Office",
          "edge": [
            "sanjose-ix",
            "ashburn-ix",
            "roaming"
          ]
        }
      ]
    }
  }'

Setting a User's Default Location

A user’s default location is controlled through their TaskRouter worker attributes. Use the flex_location attribute and set it to the location name defined in your account configuration.

Example:

worker.attributes.flex_location = "Singapore Office"

There are two ways to assign default locations:

• Set the attribute using the TaskRouter Worker API.
  • This is suitable for programmatic user provisioning.
• Set the attribute in your Identity Provider (IdP).
  • Map an IdP attribute to flex_location during SSO authentication.

Additional Resources

• https://www.twilio.com/docs/flex/developer/config/flex-configuration-rest-api