API Reference

Mute / Unmute User

Overview

Temporarily prevent a tenant chat user from sending messages by setting a mute duration, or clear an active mute.

Send minutes greater than zero to mute (up to 30 days). Send 0to unmute. On success, the API returns the user's updated moderation state, including mutedUntil.

When to use this endpoint?

Use Mute / Unmute User when:

A moderator mutes a report sender for a short cooldown (for example 10 minutes or a preset such as 1 hour / 24 hours / 7 days).
Replacing an existing mute with a new duration (a new mute overwrites the previous mutedUntil).
Clearing a mute early by sending minutes: 0.
Acting from Platform → Moderation after reviewing List Reports (use messageSender._id as userId).

Part of the client Platform Moderation module. A muted user can typically still read messages but cannot send until mutedUntil is in the past (or unmuted). For permanent account blocks, use Ban / Unban User.

Request Fields

Field	Required	Description
minutes	Required	Mute duration in minutes. `0` unmutes. Positive values mute for that many minutes (maximum `43200` — 30 days).

PATCH{baseUrl}/api/{apiVersion}/client/moderation/users/:userId/mute

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
Content-Type	application/json	Required when sending a JSON body.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Path Parameters

Parameter	Example	Description
userId	6a589b96cfa34ab66e35b2ab	The chat user to mute or unmute (for example `messageSender._id` from List Reports).

Request Payload

Mute for a duration

Example: mute the user for 10 minutes. mutedUntil is set to now + minutes.

json

{
  "minutes": 10
}

Unmute

Send minutes: 0 to clear the mute. Success data.mutedUntil is then null (or inactive).

json

{
  "minutes": 0
}

Success Response (HTTP 200 OK)

Returns the updated user moderation fields. In this mute example, mutedUntil is in the future and isBanned remains false.

json

{
  "success": true,
  "message": "User muted successfully",
  "data": {
    "_id": "6a589b96cfa34ab66e35b2ab",
    "name": "Bad Actor",
    "email": "badactor@example.com",
    "mutedUntil": "2026-07-16T09:03:29.501Z",
    "isBanned": false
  },
  "error": null
}

Response data fields

Field	Description
_id	User id (same as path).
name / email	User display identity.
mutedUntil	ISO timestamp while muted; treat as active only while this time is in the future. Cleared / inactive after unmute.
isBanned	Whether the user is currently banned (unchanged by mute unless you also call Ban).

Common Errors

Mute fails when auth is invalid, the user id is missing, or minutes is out of range.

HTTP 401 Unauthorized — No token

json

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

HTTP 403 Forbidden — Tenant admin required

json

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

HTTP 404 Not Found — User missing

json

{
  "success": false,
  "message": "Entity not found",
  "data": null,
  "error": "Entity not found"
}

Code	Reason
400 Bad Request	Missing `minutes`, negative value, or duration above the 30-day maximum.
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Moderation.
404 Not Found	No user exists for the given `userId`.
500 Internal Server Error	An unexpected error occurred while updating mute state.

Best Practices

Treat mute as active only while mutedUntil is in the future.
Offer presets (1h / 24h / 7d) plus custom minutes, capped at 30 days.
After mute or unmute, refetch List Reports so sender badges refresh.
Prefer mute for temporary cooldowns; use ban for lasting account removal from chat.
Confirm unmute in the UI when clearing an active mute early.

Mute state updated

Bind data.mutedUntil in the moderation UI. For permanent action, continue with Ban / Unban User, or review history in Audit Logs.

Field

Required

Description

minutes

Required

Mute duration in minutes. 0 unmutes. Positive values mute for that many minutes (maximum 43200 — 30 days).

Header

Value

Description

Authorization

Bearer <access_token>

Client Access Token with tenant admin privileges (Platform panel).

Content-Type

application/json

Required when sending a JSON body.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Parameter

Example

Description

userId

6a589b96cfa34ab66e35b2ab

The chat user to mute or unmute (for example messageSender._id from List Reports).

{ "success": true, "message": "User muted successfully", "data": { "_id": "6a589b96cfa34ab66e35b2ab", "name": "Bad Actor", "email": "badactor@example.com", "mutedUntil": "2026-07-16T09:03:29.501Z", "isBanned": false }, "error": null }

Field

Description

_id

User id (same as path).

name / email

User display identity.

mutedUntil

ISO timestamp while muted; treat as active only while this time is in the future. Cleared / inactive after unmute.

isBanned

Whether the user is currently banned (unchanged by mute unless you also call Ban).

Code

Reason

400 Bad Request

Missing minutes, negative value, or duration above the 30-day maximum.

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Tenant admin privileges required for Platform Moderation.

404 Not Found

No user exists for the given userId.

500 Internal Server Error

An unexpected error occurred while updating mute state.