Set chat settings

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.

curl --request PATCH \ --url 'https://api.kustomerapp.com/v1/chat/settings' \ --header "Authorization: Bearer $KUSTOMER_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "teamName": "Help Team Name", "greeting": "We'\''re here to help. Let us know if we can help.", "autoreply": "Thanks for messaging us! We'\''ll get back to you soon.", "teamIconUrl": null, "embedIconUrl": null }'

{ "data": { "type": "chat_settings", "id": "57f29863a1dbf61100e6aa92", "attributes": { "teamName": "Help Team Name", "teamIconUrl": null, "greeting": "We're here to help. Let us know if we can help.", "autoreply": "Thanks for messaging us! We'll get back to you soon.", "embedIconUrl": null, "updatedAt": "2016-11-13T03:38:56.344Z", "modifiedAt": "2016-11-13T03:38:56.344Z" }, "relationships": { "org": { "data": { "type": "org", "id": "57f29863a1dbf61100e6aa92" }, "links": { "self": "/v1/orgs/57f29863a1dbf61100e6aa92" } }, "modifiedBy": { "data": { "type": "user", "id": "57f29863a1dbf61100e6aa93" }, "links": { "self": "/v1/users/57f29863a1dbf61100e6aa93" } } } } }

Chat settings

Key fields

Volume control

Which endpoint to use

Request body

Responses