Flex Configuration REST API

The Flex Configuration REST API resource contains a collection of properties that control the appearance and functionality of your Flex instance.

(information)

Info

For self-hosted Flex UI instances, any configuration values specified in your server's appConfig.js object will take precedence over corresponding values in the REST API Configuration resource.

Fetch Your Current Configuration

To review your account's current Flex Configuration properties, fetch the resource instance by making a GET request to the /Configuration endpoint.

The response contains a complete JSON representation of the configuration.

Example Fetch RequestSample response

1curl -X GET "https://flex-api.twilio.com/v1/Configuration" \
2    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

1{
2  "flex_insights_hr": null,
3  "crm_type": null,
4  "date_updated": "2023-01-18T18:28:33Z",
5  "integrations": null,
6  "markdown": {
7    "enabled": true,
8    "mode": "readWrite"
9  },
10  "debugger_integration": {
11    "enabled": true
12  },
13  "crm_callback_url": null,
14  "serverless_service_sids": null,
15  "queue_stats_configuration": null,
16  "plugin_service_enabled": null,
17  "crm_attributes": null,
18  "ui_version": "2.n",
19  "crm_fallback_url": null,
20  "service_version": null,
21  "taskrouter_target_workflow_sid": "WW74da98d61ff7d3c47d163eb6830dd61a",
22  "messaging_service_instance_sid": null,
23  "plugin_service_attributes": null,
24  "call_recording_enabled": null,
25  "call_recording_webhook_url": null,
26  "public_attributes": null,
27  "crm_enabled": null,
28  "status": "ok",
29  "taskrouter_worker_attributes": null,
30  "chat_service_instance_sid": "IS6562209199cc4fb7b2ebfd7de02f5f95",
31  "taskrouter_worker_channels": null,
32  "ui_dependencies": null,
33  "taskrouter_offline_activity_sid": "WA7e7d193ff7ecd9a1a5234292b64789c6",
34  "notifications": {
35    "enabled": true,
36    "mode": "whenNotInFocus"
37  },
38  "taskrouter_workspace_sid": "WS75619e5ea77e8e1dd01b40d65ff7d8c0",
39  "channel_configs": [
40    {
41      "cbm_attachments": {
42        "max_file_size": 16777216,
43        "max_total_file_size": 67108864,
44        "accepted_extensions": [
45          "jpg",
46          "jpeg",
47          "png",
48          "amr",
49          "mp3",
50          "mp4",
51          "pdf",
52          "heic",
53          "txt",
54          "gif"
55        ],
56        "enabled": true,
57        "number_of_attachments": 1
58      },
59      "address_type": "web"
60    },
61    {
62      "cbm_attachments": {
63        "max_file_size": 2097152,
64        "max_total_file_size": 5242880,
65        "accepted_extensions": [
66          "jpg",
67          "jpeg",
68          "png",
69          "amr",
70          "mp3",
71          "mp4",
72          "pdf",
73          "heic"
74        ],
75        "enabled": true,
76        "number_of_attachments": 1
77      },
78      "address_type": "sms"
79    },
80    {
81      "cbm_attachments": {
82        "max_file_size": 16777216,
83        "max_total_file_size": 67108864,
84        "accepted_extensions": [
85          "jpg",
86          "jpeg",
87          "png",
88          "amr",
89          "mp3",
90          "mp4",
91          "pdf",
92          "heic",
93          "oga"
94        ],
95        "enabled": true,
96        "number_of_attachments": 1
97      },
98      "address_type": "whatsapp"
99    },
100    {
101      "cbm_attachments": {
102        "max_file_size": 157286400,
103        "max_total_file_size": 157286400,
104        "accepted_extensions": [
105          "jpg",
106          "jpeg",
107          "png",
108          "amr",
109          "mp3",
110          "mp4",
111          "pdf",
112          "heic",
113          "txt",
114          "gif"
115        ],
116        "enabled": true,
117        "number_of_attachments": 10
118      },
119      "address_type": "email"
120    }
121  ],
122  "date_created": "2023-01-18T18:28:19Z",
123  "taskrouter_skills": null,
124  "taskrouter_taskqueues": null,
125  "ui_attributes": {
126    "warmTransfers": {
127      "enabled": true
128    },
129    "notifications": {
130      "browser": true
131    }
132  },
133  "flex_insights_drilldown": true,
134  "url": "https://flex-api.twilio.com/v1/Configuration",
135  "outbound_call_flows": null,
136  "taskrouter_target_taskqueue_sid": "WQc9fb6967e9d4675df72b99bc1cadeb62",
137  "account_sid": "AC8e0ce685xxxxxxxxxxxxxxxxxxxxxxxx",
138  "runtime_domain": "iris-macaw-7585.twil.io",
139  "flex_url": null,
140  "ui_language": null,
141  "attributes": null,
142  "flex_service_instance_sid": "ISb194bb2b0f24efb3f4ef73d225af7b0d",
143  "flex_ui_status_report": {
144    "enabled": true
145  }
146}

(information)

Info

Not sure where to find your account SID or auth token? Check out this intro to using Twilio's REST APIs for help.

Update Your Configuration

Issue a POST request to the /Configuration endpoint to update Flex Configuration values. Include a JSON object in the request body that contains your Twilio account SID along with any configuration items that you wish to update.

The following example request illustrates how to update a single configuration property with a Boolean value.

1JSON_PAYLOAD=$(cat <<EOF
2{
3    "account_sid": "ACXXXXXXXXXXXXXXXXX",
4    "call_recording_enabled": true
5}
6EOF
7)
8
9curl -X POST https://flex-api.twilio.com/v1/Configuration \
10    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
11    -H 'Content-Type: application/json' \
12    -d $JSON_PAYLOAD

(information)

Info

Some properties expect a type as the value (Boolean, string, integer, etc), while other properties expect a value that is itself a full JSON object. When updating a JSON type property, the existing value of the property will be completely replaced by the JSON object that you provide as the new value.

To prevent accidentally overriding existing fields of a JSON type property when performing an update, you should always first fetch the existing value of the property first. Then make any desired adjustments to the JSON object before sending it in the body of a POST request to update the property. You'll see an illustration of this in the following example.

Let's see how to update a property that uses a JSON object rather than a scalar as its value.

Suppose we want to update the ui_attributes property in order to disable browser notifications. Since the value of ui_attributes is a JSON object and it might contain fields other than the one we want to modify, we will first fetch the Configuration to get the complete current state of the object. Let's say that the current value of ui_attributes that we see in the response looks like this:

1{
2    "warmTransfers": {
3      "enabled": true
4    },
5    "notifications": {
6      "browser": true
7    }
8}
9

Here's how we can send a request to update the property with our adjustment to one field within the JSON object value.

1JSON_PAYLOAD=$(cat <<EOF
2{
3    "account_sid": "ACXXXXXXXXXXXXXXXXX",
4    "ui_attributes": {
5        "warmTransfers": {
6            "enabled": true
7        },
8        "notifications": {
9            "browser": false
10         }
11    }
12}
13EOF
14)
15
16curl -X POST 'https://flex-api.twilio.com/v1/Configuration' \
17    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
18    -H 'Content-Type: application/json' \
19    -d $JSON_PAYLOAD

The existing value for the ui_attributes property will be entirely replaced by the JSON object we provided in the POST request.

(warning)

Warning

Some fields are read-only. If you attempt to update a read-only field, the API will return an HTTP 400 response with an error message:

1{
2  "code": 45004,
3  "message": "You are not allowed to modify property for [flex_service_instance_sid].",
4  "more_info": "https://www.twilio.com/docs/errors/45004",
5  "status": 400
6}

Configuration properties reference

Following is a description of some of the Configuration properties that you may wish to change.

ui_attributes

JSON object

These configuration values control some aspects of the appearance and functionality of the Flex UI web application.

For self-hosted Flex UI instances, properties specified here are merged with any properties present in the server's appConfig.js object. Values specified in appConfig.js take precedence over corresponding values in the ui_attributes field of the REST API Configuration resource.

Check out the appConfig.js guide to learn more about the available Flex UI configuration options.

(information)

Info

Example value

1{
2    "warmTransfers": {
3        "enabled": true
4    },
5    "notifications": {
6        "browser": true
7    },
8    "logLevel": "debug",
9    "theme": {
10        "isLight": false
11    }
12}

taskrouter_skills

JSON object

This field allows you to define custom skills-based routing parameters for your Flex instance.

(information)

Info

Example value

1[
2  {
3    "name": "voice",
4    "multivalue": false,
5    "minimum": null,
6    "maximum": null
7  },
8  {
9    "name": "language_fr",
10    "multivalue": false,
11    "minimum": null,
12    "maximum": null
13  },
14  {
15    "name": "language_ge",
16    "multivalue": false,
17    "minimum": null,
18    "maximum": null
19  },
20  {
21    "name": "messaging",
22    "multivalue": false,
23    "minimum": null,
24    "maximum": null
25  },
26  {
27    "name": "special_language",
28    "multivalue": true,
29    "minimum": 1,
30    "maximum": 10
31  }
32]