Get chat settings
/v1/chat/settingsNo specific role is required; any valid credential works.
Retrieves the display options for the chat channel.
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 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 |
| Change one or more settings | PATCH /v1/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.
Responses
OK