Settings

Tags: business-hours, configuration, settings, workspace

Workspace configuration and settings management

In the product: Workspace Settings

Resources

Request and response models used by the endpoints on this page.

BusinessHoursStatusResponse

Field	Type	Required	Description
isBusinessHours	Boolean	✓

Example:

{
  "isBusinessHours": false
}

FirstRunState

Field	Type	Required	Description
collapsed	Boolean
mode	String		Default: unset
statuses	dict[str, str]

Example:

{
  "mode": "unset"
}

UpdateWorkspaceDefaultsRequest

Field	Type	Required	Description
allowDevices	Boolean		Default: False
defaultAgentId	Integer
defaultPhoneNumberId	Integer
defaultReplyToInboxId	Integer
emailFooter	String
enableAudioRecording	Boolean
enableVoicemailDetection	Boolean
escalationBusinessHours	String
escalationNotifiedMessageTemplate	String
escalationOfflineMessageTemplate	String
escalationOnlineMessageTemplate	String
escalationPausedMessageTemplate	String
pauseOnEscalate	Boolean
shortenUrls	Boolean
transcriptionModel	String

Example:

{
  "allowDevices": false
}

UpdateWorkspaceFeaturesRequest

Field	Type	Required	Description
features	dict[str, bool]	✓

Example:

{
  "features": {}
}

WorkspaceFeatureState

Field	Type	Required	Description
category	String	✓
description	String	✓
editable	Boolean	✓
enabled	Boolean	✓
icon	String
name	String	✓
slug	String	✓

Example:

{
  "slug": "string",
  "name": "string",
  "description": "string",
  "category": "string",
  "enabled": false,
  "editable": false
}

WorkspaceFeaturesResponse

Field	Type	Required	Description
features	Array<WorkspaceFeatureState>	✓

Example:

{
  "features": []
}

WorkspaceSettingsResponse

Field	Type	Required	Description
allowDevices	Boolean	✓
defaultAgentId	Integer	✓
defaultChatModel	String	✓
defaultInferenceModel	String	✓
defaultPhoneNumberId	Integer	✓
defaultRealtimeModel	String	✓
defaultReplyToInboxId	Integer	✓
defaultVoiceModel	String	✓
emailFooter	String	✓
enableAudioRecording	Boolean	✓
enableVoicemailDetection	Boolean	✓
escalationBusinessHours	String	✓
escalationNotifiedMessageTemplate	String	✓
escalationOfflineMessageTemplate	String	✓
escalationOnlineMessageTemplate	String	✓
escalationPausedMessageTemplate	String	✓
firstRunMode	String
id	Integer	✓
pauseOnEscalate	Boolean	✓
sesDomain	String	✓
shortenUrls	Boolean	✓
shortenUrlsAvailable	Boolean	✓
shortenUrlsExampleUrl	String	✓
slug	String	✓
transcriptionModel	String
workspaceFolderId	Integer

Example:

{
  "id": 0,
  "slug": "string",
  "defaultPhoneNumberId": 0,
  "defaultAgentId": 0,
  "escalationBusinessHours": "string",
  "escalationOnlineMessageTemplate": "string",
  "escalationOfflineMessageTemplate": "string",
  "escalationNotifiedMessageTemplate": "string",
  "escalationPausedMessageTemplate": "string",
  "emailFooter": "string",
  "defaultReplyToInboxId": 0,
  "pauseOnEscalate": false,
  "sesDomain": "string",
  "enableAudioRecording": false,
  "enableVoicemailDetection": false,
  "allowDevices": false,
  "shortenUrls": false,
  "shortenUrlsExampleUrl": "string",
  "shortenUrlsAvailable": false,
  "defaultChatModel": "string",
  "defaultRealtimeModel": "string",
  "defaultInferenceModel": "string",
  "defaultVoiceModel": "string"
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/business-hours-status - Business Hours Status
• GET /api/v2/w/{workspace_uuid}/defaults - Defaults
• PUT /api/v2/w/{workspace_uuid}/defaults - Update Defaults
• GET /api/v2/w/{workspace_uuid}/features - Features
• PUT /api/v2/w/{workspace_uuid}/features - Update Features
• GET /api/v2/w/{workspace_uuid}/first-run-state - First Run State
• PUT /api/v2/w/{workspace_uuid}/first-run-state - Update First Run State

Business Hours Status

GET /api/v2/w/{workspace_uuid}/business-hours-status

Description:

Get current business hours status

Get the current business hours status for the workspace.

Authorization: Requires workspace:read scope

Response: See BusinessHoursStatusResponse

---

Defaults

GET /api/v2/w/{workspace_uuid}/defaults

Description:

Get workspace default settings

Get the default settings for a workspace.

If no settings row exists yet, returns workspace defaults. The row is created on the first update.

Authorization: Requires workspace:read scope

Response: See WorkspaceSettingsResponse

---

Update Defaults

PUT /api/v2/w/{workspace_uuid}/defaults

Description:

Update workspace default settings

Update default settings for a workspace.

Authorization: Requires workspace:write scope

Parameters:

• request - See UpdateWorkspaceDefaultsRequest

Response: See WorkspaceSettingsResponse

---

Features

GET /api/v2/w/{workspace_uuid}/features

Description:

Features this workspace's plan allows, and whether each one is on.

Each entry carries editable: false means an administrator has locked the feature and a change to it will be refused.

Gated on WORKSPACE_WRITE rather than a read scope on purpose: this is the settings surface, and everything it lists is something the caller is about to be offered a toggle for. A member who cannot change any of it has no use for the list.

Authorization: Requires workspace:write scope

Response: See WorkspaceFeaturesResponse

---

Update Features

PUT /api/v2/w/{workspace_uuid}/features

Description:

Turn plan-allowed features on or off for this workspace.

A feature the org plan does not include is a 400. A feature an administrator has locked is a 403; the response says which and why.

Authorization: Requires workspace:write scope

Parameters:

• request - See UpdateWorkspaceFeaturesRequest

Response: See WorkspaceFeaturesResponse

---

First Run State

GET /api/v2/w/{workspace_uuid}/first-run-state

Authorization: Requires workspace:read scope

Response: See FirstRunState

---

Update First Run State

PUT /api/v2/w/{workspace_uuid}/first-run-state

Authorization: Requires workspace:write scope

Parameters:

• request (FirstRunState)

Response: See FirstRunState

---