Update Settings

Partially update the authenticated tenant's Platform settings. Send only the keys you want to change — top-level toggles, numeric limits, or nested objects such as attachments, calls, groupPolicy, or messageTimers.

On success, the API returns the full settings document in the same shape as Get Settings (including read-only limits). Values must stay within those plan ceilings.

Use Update Settings when:

• The Platform → Settings form saves one toggle (for example disable video calls).
• An admin changes a numeric limit such as maxParticipantsPerGroup.
• Attachment rules are tightened (file size and MIME types) without resending the entire document.
• You want to persist several related fields in one PATCH after Get.

Part of the client Platform Settings module. Load current values with Get Settings first. You cannot change limits here — those are plan ceilings.

Every body field is optional. Omit keys you are not changing. Nested objects are merged shallowly — only the keys you send are updated; siblings keep their previous values.

Single-field example

Prefer one field per save when the UI has independent toggles — clearer UX and smaller payloads.

{
  "videoCallEnabled": false
}

What you can send

Use the field names returned under data.settings from Get. Grouped below — see Get Settings → Response Data for full meanings.

Each request is a partial PATCH — send only the keys you want to change. Below are three common payloads. Do not send limits, _id, or clientId.

1. Save VideoSDK token (calls)

Enable calling and store the provider token. Audio/video feature toggles only take full effect when calls.enabled is true and a valid token is saved.

{
  "calls": {
    "enabled": true,
    "videoSdkToken": "<your-videosdk-token>"
  }
}

2. Group policy defaults + message timers

Patch selected groupPolicy.defaults flags, set locked, and update only the timer keys you need (other defaults/timers stay unchanged).

{
  "groupPolicy": {
    "defaults": {
      "onlyAdminCanSendMessage": true,
      "allowMemberAdd": true
    },
    "locked": [
      "onlyAdminCanSendMessage"
    ]
  },
  "messageTimers": {
    "dmEditMinutes": 15,
    "groupDeleteMinutes": 60
  }
}

3. Feature toggle, group size limit, and attachments

Combine a boolean toggle, a numeric limit, and a nested attachments partial in one request.

{
  "videoCallEnabled": false,
  "maxParticipantsPerGroup": 100,
  "attachments": {
    "maxFileSizeMB": 10,
    "allowedMimeTypes": [
      "image/*",
      "application/pdf"
    ]
  }
}

Every successful PATCH returns the same full settings document shape as Get. The sample below shows data.settings after applying the three example payloads above (in order): calls, groupPolicy / messageTimers, then toggles / attachments. Keys you omit stay at their previous values.

{
  "success": true,
  "message": "Settings updated successfully",
  "data": {
    "_id": "6a57...739c",
    "clientId": "6a57...f0c0",
    "__v": 0,
    "createdAt": "2026-07-15T04:45:28.064Z",
    "limits": {
      "attachments": {
        "enabled": true,
        "maxFileSizeMB": 25,
        "maxAttachmentsPerMessage": 10,
        "allowedMimeTypes": ["*"]
      },
      "maxAdminsPerGroup": 5,
      "maxParticipantsPerGroup": 256,
      "maxPinnedMessagesPerConversation": 10,
      "groupCreationEnabled": true
    },
    "metadata": {},
    "settings": {
      "calls": {
        "enabled": true,
        "videoSdkToken": "<your-videosdk-token>"
      },
      "groupPolicy": {
        "defaults": {
          "onlyAdminCanSendMessage": true,
          "onlyAdminCanEditInfo": false,
          "senderCanEditMessage": true,
          "allowMemberAdd": true,
          "allowMemberRemove": false,
          "moderationEnabled": false
        },
        "locked": [
          "onlyAdminCanSendMessage"
        ]
      },
      "messageTimers": {
        "dmEditMinutes": 15,
        "dmDeleteMinutes": 10,
        "groupEditMinutes": 10,
        "groupDeleteMinutes": 60
      },
      "attachments": {
        "enabled": true,
        "maxFileSizeMB": 10,
        "maxAttachmentsPerMessage": 10,
        "allowedMimeTypes": [
          "image/*",
          "application/pdf"
        ]
      },
      "pushNotificationEnabled": true,
      "videoCallEnabled": false,
      "audioCallEnabled": true,
      "blockUsersEnabled": true,
      "maxAdminsPerGroup": 5,
      "maxParticipantsPerGroup": 100,
      "maxPinnedMessagesPerConversation": 10,
      "groupCreationEnabled": true
    },
    "updatedAt": "2026-07-19T14:10:00.000Z"
  },
  "error": null
}

Update fails when auth is invalid, the caller is not a tenant admin, or a value exceeds limits.

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

{
  "success": false,
  "message": "Some settings exceed the maximums set by the platform admin",
  "data": null,
  "error": [
    "maxParticipantsPerGroup cannot exceed 256 (the maximum set by the platform admin)",
    "attachments.maxFileSizeMB cannot exceed 25 MB (the maximum set by the platform admin)"
  ]
}

• Prefer single-field PATCHes from the Platform UI when saving one toggle or control.
• Cap inputs against data.limits from Get before submit.
• For nested objects, send only the keys that changed — omit unchanged siblings so you do not overwrite them accidentally.
• Treat videoSdkToken as a secret; never log it.
• Refresh local state from the returned data (or refetch Get) after every successful save.