# Get chat settings > GET /v1/chat/settings ยท Settings and configurations API Source: https://developer.kustomer.com/api/settings-and-configurations/get-chat-settings ```http GET https://{orgname}.api.kustomerapp.com/v1/chat/settings Authorization: Bearer ``` ## Authorization Any API key or signed-in user. No specific role is required; any valid credential works. Retrieves the display options for the chat channel. ## About Chat settings Chat settings control how the Kustomer chat widget looks and behaves on your website and in your apps, such as the team name and greeting customers see, what happens outside business hours, and whether customers can see past conversations. Chat settings are the configuration behind the Kustomer chat widget. Admins edit them on the chat pages of the Kustomer admin settings, and the web widget and the mobile chat SDKs load them when they start, to decide what to show the customer. Each brand has its own chat settings. These endpoints read and write the settings of your org's default brand. There is always exactly one settings record per brand, so there is nothing to create or delete: you read it and update it. #### Key fields | Field | Meaning | | --- | --- | | `enabled` | Whether chat is turned on. | | `teamName`, `teamIconUrl` | The name and icon of the team the customer is talking to. | | `greeting` | The welcome text shown before the customer starts a conversation. | | `autoreply` | The automatic reply to the customer's first message. | | `embedIconUrl`, `embedIconColor` | The icon and color of the button that opens chat. | | `offhoursDisplay` | What the widget shows outside business hours: `online`, `offline` or `none`. `offhoursMessage` and `offhoursImageUrl` set the content of the off-hours screen. | | `noHistory` | Hide the customer's past conversations. | | `singleSessionChat` | Allow only one open conversation per customer. | | `closableChat` | Let customers end a conversation themselves. | | `domainCriteria` | `and` or `or` rules on the page URL that decide which pages may show the widget. | | `activeForm` | The ID of a form to show in chat. It must be an existing form. | The text fields `teamName`, `greeting`, `autoreply`, `offhoursMessage` and `volumeControl.customWaitMessage` can contain [snippet](https://developer.kustomer.com/api/settings-and-configurations#snippets) references such as `[[sn.org.chat.greeting]]`, so the widget can show them in the customer's language. #### Volume control `volumeControl` handles busy periods by offering customers an alternative to waiting in chat for an agent. Turn it on with `enabled`. `mode` is `delayed` (the default), where the offer appears after the customer has waited `promptDelay` seconds, or `upfront`, where it appears at the start when the wait is longer than `upfrontWaitThreshold` seconds. `followUpChannels` lists how your team can follow up instead (`email`, `sms` or `voice`), and `hideWaitOption` removes the choice to keep waiting. `useDynamicWaitMessage` and `customWaitMessage` control the waiting text, and `markDoneAfterTimeout` closes the conversation after `timeout` seconds. Every duration is in seconds, up to 86,400 (24 hours). #### Which endpoint to use | To | Call | | --- | --- | | Read the current chat configuration | [`GET /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-chat-settings) | | Change one or more settings | [`PATCH /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/set-chat-settings) | `PATCH` changes only the fields you send and returns the updated record. `volumeControl` is merged with its current value, so you can send just the sub-fields you want to change. A request body with no settings fields fails with `400`. Reading chat settings only requires a signed-in user or API key, but changing them requires an admin role with permission to manage apps. Related: [Web chat](https://developer.kustomer.com/docs/chat/web), [Web Core API](https://developer.kustomer.com/docs/chat/web-core-api), [Brands](https://developer.kustomer.com/api/core-resources#brands), [Snippets](https://developer.kustomer.com/api/settings-and-configurations#snippets) ### Recipes #### 1. Turn on volume control for a busy period Offer chat customers a follow-up by email instead of a long wait during a sale or an outage, then switch it off again without losing the configuration. **Step 1.** [`GET /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-chat-settings.md). Read the current `volumeControl` so you know what you're changing and can restore it later. ```bash title="cURL" curl "https://api.kustomerapp.com/v1/chat/settings" \ --header "Authorization: Bearer $KUSTOMER_API_KEY" ``` ```bash title="kusty" kusty api GET /v1/chat/settings --fields attributes.volumeControl > volume-control-before.json ``` **Step 2.** [`PATCH /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/set-chat-settings.md). Send only the `volumeControl` sub-fields you want to change; Kustomer merges them with the current value. With `mode: "upfront"`, customers get the offer as soon as they start a chat if the wait is longer than `upfrontWaitThreshold` seconds. `followUpChannels` lists how your team will follow up. Changing settings needs an admin role with permission to manage apps. ```bash title="cURL" curl --request PATCH "https://api.kustomerapp.com/v1/chat/settings" \ --header "Authorization: Bearer $KUSTOMER_API_KEY" \ --header "Content-Type: application/json" \ --data '{"volumeControl": {"enabled": true, "mode": "upfront", "upfrontWaitThreshold": 600, "followUpChannels": ["email"]}}' ``` ```bash title="kusty" kusty api PATCH /v1/chat/settings \ --data '{"volumeControl": {"enabled": true, "mode": "upfront", "upfrontWaitThreshold": 600, "followUpChannels": ["email"]}}' ``` **Step 3.** [`PATCH /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/set-chat-settings.md). When the rush is over, send just `enabled: false`. The rest of `volumeControl` stays as it is, ready for next time. ```bash title="cURL" curl --request PATCH "https://api.kustomerapp.com/v1/chat/settings" \ --header "Authorization: Bearer $KUSTOMER_API_KEY" \ --header "Content-Type: application/json" \ --data '{"volumeControl": {"enabled": false}}' ``` ```bash title="kusty" kusty api PATCH /v1/chat/settings --field volumeControl.enabled:=false ``` > Every duration in `volumeControl` (`promptDelay`, `upfrontWaitThreshold`, `timeout`) is in seconds, up to 86,400. #### 2. Copy chat settings from a sandbox org to production Design the chat widget's text and behavior in a test org, then apply the same settings to production in one reviewed step. **Step 1.** [`GET /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-chat-settings.md). Read the settings from the source org, using that org's API key. ```bash title="cURL" curl "https://api.kustomerapp.com/v1/chat/settings" \ --header "Authorization: Bearer $SANDBOX_API_KEY" ``` ```bash title="kusty" kusty api GET /v1/chat/settings --profile sandbox > sandbox-chat-settings.json ``` **Step 2.** Keep only fields that `PATCH` accepts. The request rejects any other field, including read-only ones such as `updatedAt` and `modifiedAt`, with `400`. Drop empty values, and leave out `enabled` so the copy can't turn chat on or off by accident. Snippet references such as `[[sn.org.chat.greeting]]` only work if the same snippets exist in the target org. ```bash title="kusty" jq '.data.attributes | {teamName, teamIconUrl, greeting, autoreply, embedIconUrl, embedIconColor, offhoursDisplay, offhoursMessage, offhoursImageUrl, closableChat, noHistory, singleSessionChat, showTypingIndicatorWeb, showTypingIndicatorCustomerWeb, showBrandingIdentifier, volumeControl} | with_entries(select(.value != null)) | if .volumeControl then .volumeControl |= with_entries(select(.value != null)) else . end' \ sandbox-chat-settings.json > chat-settings-patch.json ``` **Step 3.** [`PATCH /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/set-chat-settings.md). Review the file, then send it to production. Only the fields in the body change, and the response is the updated record. ```bash title="cURL" curl --request PATCH "https://api.kustomerapp.com/v1/chat/settings" \ --header "Authorization: Bearer $KUSTOMER_API_KEY" \ --header "Content-Type: application/json" \ --data @chat-settings-patch.json ``` ```bash title="kusty" kusty api PATCH /v1/chat/settings --data @chat-settings-patch.json --profile production ``` > These endpoints read and write the default brand's chat settings only. ### Example object A real record from [`GET /v1/chat/settings`](https://developer.kustomer.com/api/settings-and-configurations/get-chat-settings.md): ```json { "type": "chat_settings", "id": "57504f64d76808100089eb44", "attributes": { "teamName": "Jeremy", "greeting": "We're here. Let us know if we can help.", "autoreply": "Thanks for messaging us! We'll get back to you soon.", "embedIconUrl": "", "embedIconColor": "", "enabled": true, "updatedAt": "2018-04-24T16:08:17.586Z", "modifiedAt": "2017-11-17T14:38:48.581Z", "offhoursMessage": "", "offhoursImageUrl": "", "closableChat": false, "noHistory": false, "volumeControl": { "enabled": false, "markDoneAfterTimeout": false, "mode": "delayed", "useDynamicWaitMessage": false, "followUpChannels": [], "hideWaitOption": false }, "singleSessionChat": false, "showTypingIndicatorWeb": false, "showTypingIndicatorCustomerWeb": false, "showBrandingIdentifier": true }, "relationships": { "org": { "data": { "type": "org", "id": "57504f64d76808100089eb44" }, "links": { "self": "/v1/orgs/57504f64d76808100089eb44" } }, "modifiedBy": { "data": { "type": "user", "id": "57504f644c80120f00f3c378" }, "links": { "self": "/v1/users/57504f644c80120f00f3c378" } } } } ``` Fields: - `id` (string): The ID of this settings record. These endpoints always act on the default brand's record, so you never send it. - `attributes.teamName` (string): The name of the team customers see they're talking to. Up to 128 characters, and can contain snippet references for translated text. - `attributes.greeting` (string): The welcome text shown before the customer starts a conversation. Up to 512 characters, and can contain snippet references. - `attributes.autoreply` (string): The automatic reply to the customer's first message. Up to 512 characters, and can contain snippet references. - `attributes.embedIconUrl` (string): The URL of a custom image for the button that opens chat. Empty when none is set. - `attributes.embedIconColor` (string): The color of the button that opens chat, up to 64 characters. Empty when none is set. - `attributes.enabled` (boolean): Whether chat is turned on. - `attributes.updatedAt` (string): Changes on every write to the settings, including ones Kustomer makes itself. Use `modifiedAt` to see when a person or API key last edited them. - `attributes.modifiedAt` (string): When a user, or an API key acting as one, last changed the settings. `relationships.modifiedBy` is who. - `attributes.offhoursMessage` (string): The text of the off-hours screen, which `offhoursDisplay` controls. Up to 512 characters, and can contain snippet references. - `attributes.offhoursImageUrl` (string): An image for the off-hours screen. Empty when none is set. - `attributes.closableChat` (boolean): `true` lets customers end a conversation themselves. - `attributes.noHistory` (boolean): `true` hides the customer's past conversations in the widget. - `attributes.volumeControl` (object): Offers customers an alternative to waiting when your team is busy. `PATCH` merges it with the current value, so send only the sub-fields you change. - `attributes.volumeControl.enabled` (boolean): Turns volume control on or off without losing the other sub-fields. - `attributes.volumeControl.markDoneAfterTimeout` (boolean): `true` closes the conversation after `timeout` seconds. - `attributes.volumeControl.mode` (string): `delayed` (the default) makes the offer after the customer has waited `promptDelay` seconds; `upfront` makes it at the start when the wait is longer than `upfrontWaitThreshold` seconds. - `attributes.volumeControl.useDynamicWaitMessage` (boolean): `true` shows a wait message based on the estimated wait time. It applies only when `customWaitMessage` is empty. - `attributes.volumeControl.followUpChannels` (array): How your team can follow up instead: any of `email`, `sms` and `voice`. - `attributes.volumeControl.hideWaitOption` (boolean): `true` removes the choice to keep waiting in chat. - `attributes.singleSessionChat` (boolean): `true` allows only one open conversation per customer. - `attributes.showTypingIndicatorWeb` (boolean): `true` lets agents see when the customer is typing. - `attributes.showTypingIndicatorCustomerWeb` (boolean): `true` lets customers see when an agent is typing. - `attributes.showBrandingIdentifier` (boolean): Shows the "Powered by Kustomer" footer in the widget. Defaults to `true`. ### Permissions Fewest roles for a read-only integration: any valid key. For every endpoint: `org.permission.apps.update`. ## Responses ### 200 OK - `data` (object, required) - `type` (string, required) - `id` (string, required) - `attributes` (object, required) - `teamName` (string, required) - `greeting` (string, required) - `autoreply` (string, required) - `embedIconUrl` (string, required) - `embedIconColor` (string, required) - `enabled` (boolean, required) - `updatedAt` (string, required) - `modifiedAt` (string, required) - `offhoursMessage` (string, required) - `offhoursImageUrl` (string, required) - `closableChat` (boolean, required) - `noHistory` (boolean, required) - `volumeControl` (object, required) - `singleSessionChat` (boolean, required) - `showTypingIndicatorWeb` (boolean, required) - `showTypingIndicatorCustomerWeb` (boolean, required) - `showBrandingIdentifier` (boolean, required) - `relationships` (object, required) - `org` (object, required) - `modifiedBy` (object, required) ```json { "data": { "type": "chat_settings", "id": "57504f64d76808100089eb44", "attributes": { "teamName": "Jeremy", "greeting": "We're here. Let us know if we can help.", "autoreply": "Thanks for messaging us! We'll get back to you soon.", "embedIconUrl": "", "embedIconColor": "", "enabled": true, "updatedAt": "2018-04-24T16:08:17.586Z", "modifiedAt": "2017-11-17T14:38:48.581Z", "offhoursMessage": "", "offhoursImageUrl": "", "closableChat": false, "noHistory": false, "volumeControl": { "enabled": false, "markDoneAfterTimeout": false, "mode": "delayed", "useDynamicWaitMessage": false, "followUpChannels": [], "hideWaitOption": false }, "singleSessionChat": false, "showTypingIndicatorWeb": false, "showTypingIndicatorCustomerWeb": false, "showBrandingIdentifier": true }, "relationships": { "org": { "data": { "type": "org", "id": "57504f64d76808100089eb44" }, "links": { "self": "/v1/orgs/57504f64d76808100089eb44" } }, "modifiedBy": { "data": { "type": "user", "id": "57504f644c80120f00f3c378" }, "links": { "self": "/v1/users/57504f644c80120f00f3c378" } } } } } ``` ### 401 Unauthorized ### 403 Forbidden ## Example request ```bash curl --request GET \ --url 'https://api.kustomerapp.com/v1/chat/settings' \ --header "Authorization: Bearer $KUSTOMER_API_KEY" ```