Skip to content
Docs
Open Soosh
View as Markdown
ReferenceWorkspace

Organization Settings

Read and update organization settings and upload calling audio

DevelopersUpdated

Overview

Section titled “Overview”

These endpoints manage the current organization’s settings — general preferences, calling behaviour, and the audio files used for hold music and ringback. Settings are stored per-organization and always scoped to the caller’s org. For org CRUD and membership, see the Organizations API.

Get Settings

Section titled “Get Settings”

Return the current organization’s settings and name. Values fall back to server defaults (and the global [calling] config) when unset.

GET/api/org/settings

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "settings": {
      "mask_phone_numbers": false,
      "timezone": "UTC",
      "date_format": "YYYY-MM-DD",
      "calling_enabled": false,
      "max_call_duration": 3600,
      "transfer_timeout_secs": 60,
      "hold_music_file": "",
      "ringback_file": ""
    },
    "name": "Acme Inc"
  }
}

Settings Fields

Section titled “Settings Fields”

General

Field Type Description
mask_phone_numbers boolean Mask contact phone numbers (and phone-like names) across the app and exports.
timezone string Display timezone (default UTC).
date_format string Date display format (default YYYY-MM-DD).

Calling

Field Type Description
calling_enabled boolean Enable WebRTC voice calling for the organization.
max_call_duration integer Maximum call length in seconds.
transfer_timeout_secs integer Seconds to wait for an agent to accept a transfer.
hold_music_file string Filename of the uploaded hold-music track.
ringback_file string Filename of the uploaded ringback tone.

Update Settings

Section titled “Update Settings”

Update one or more settings. All fields are optional — only the fields present in the body are changed.

PUT/api/org/settings

Request Body

Section titled “Request Body”
{
  "name": "Acme Inc",
  "mask_phone_numbers": true,
  "timezone": "America/New_York",
  "date_format": "MM/DD/YYYY",
  "calling_enabled": true,
  "max_call_duration": 1800,
  "transfer_timeout_secs": 45,
  "hold_music_file": "org_<id>_hold_music.ogg",
  "ringback_file": "org_<id>_ringback.ogg"
}
Field Type Description
name string Organization name (ignored if empty).
mask_phone_numbers boolean Toggle phone masking.
timezone string Display timezone.
date_format string Date display format.
calling_enabled boolean Enable/disable calling.
max_call_duration integer Max call seconds (applied only when > 0).
transfer_timeout_secs integer Transfer accept timeout (applied only when > 0).
hold_music_file string Hold-music filename (usually set via the audio upload below).
ringback_file string Ringback filename (usually set via the audio upload below).

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "message": "Settings updated successfully"
  }
}

Upload Calling Audio

Section titled “Upload Calling Audio”

Upload an audio file for hold music or ringback. The file is transcoded to OGG/Opus (48 kHz mono) for WebRTC playback, stored, and the matching hold_music_file / ringback_file setting is updated automatically.

POST/api/org/audio

Requires the organizations:write permission.

Query Parameters

Section titled “Query Parameters”
Parameter Type Required Description
type string Yes hold_music or ringback.

Form Fields

Section titled “Form Fields”
Field Type Required Description
file file Yes Audio file, max 5 MB. Accepts OGG, Opus, MP3, and WAV.

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "filename": "org_<id>_hold_music.ogg",
    "type": "hold_music",
    "mime_type": "audio/mpeg",
    "size": 204800
  }
}

See Also

Section titled “See Also”