user_timeout.md

Command: user_timeout

Set a rate limit timeout for a user. Requires manage_users permission.

Request

{
  "cmd": "user_timeout",
  "user": "<username_or_user_id>",
  "timeout": <timeout_in_seconds>
}

Fields

• user: (required) Username or user ID of the user to timeout. Can be a username (which will be resolved to user ID) or a direct user ID.
• timeout: (required) Timeout duration in seconds. Must be a positive integer (can be 0 to remove timeout).

Response

On Success

{
  "cmd": "user_timeout",
  "user": "<username>",
  "timeout": <timeout>
}

If the target user is currently connected, they will also receive:

{
  "cmd": "rate_limit",
  "reason": "User timeout set",
  "length": <timeout * 1000>
}

Error Responses

• {"cmd": "error", "val": "Authentication required"}
• {"cmd": "error", "val": "Access denied: manage_users permission required"}
• {"cmd": "error", "val": "Timeout must be provided"}
• {"cmd": "error", "val": "Timeout must be a positive integer"}

Permissions

• Requires manage_users permission.

Notes

• Users can only be timed out by users with the manage_users permission.
• The timeout is applied to the user's rate limiting system.
• A timeout of 0 removes any existing timeout (unlimits the user).
• The targeted user must be connected to receive the immediate notification.
• Setting a timeout causes the user to be immediately rate limited for the specified duration.
• The timeout affects all rate-limited actions (sending messages, etc.).
• Rate limiter must be enabled in server config for this command to work.

Usage Examples

Timeout User for 5 Minutes

{
  "cmd": "user_timeout",
  "user": "alice",
  "timeout": 300
}

Remove Timeout

{
  "cmd": "user_timeout",
  "user": "alice",
  "timeout": 0
}

Timeout by User ID

{
  "cmd": "user_timeout",
  "user": "USR:1234567890abcdef",
  "timeout": 600
}

See Also

• user_ban - Ban a user permanently
• user_unban - Unban a user
• rate_limit_status - Check rate limit status
• rate_limit_reset - Reset rate limit (owner only)

See implementation: handlers/message.py (search for case "user_timeout":).