Block / Unblock User

Overview

Block or unblock another chat participant from the signed-in user's perspective. Blocking stops messaging that person without deleting either chat account.

Send the target userId and a type of block or unblock. Typical chat actions: safety menu on a contact profile, or unblock from settings.

When to use this endpoint?

Use Block / Unblock when:

A chat participant taps Block on a contact or conversation.
Your report / safety flow ends in stopping messages from that peer.
They reverse a previous block (type: "unblock").
You need a reversible restriction instead of deleting a chat account.

Part of the Chat UserAPIs. Requires the chat user Bearer token for the acting participant. Pass the other person's id - you cannot block yourself.

PATCH{baseUrl}/api/{apiVersion}/user/block-unblock

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Chat user Access Token (Bearer) for the signed-in participant performing the block or unblock.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Request Payload

Both fields are required on every call:

Field	Type	Required	Description
userId	string	Required	Target user's `_id` to block or unblock.
type	string	Required	Action: `block` or `unblock`.

Block

json

1{2  "userId": "694b...a1",3  "type": "block"4}

Unblock

json

1{2  "userId": "694b...a1",3  "type": "unblock"4}

Success Response (HTTP 200 OK)

On success, the API confirms the action. data may be null; rely on message for UI feedback.

json

1{2  "success": true,3  "message": "User blocked successfully",4  "data": null,5  "error": null6}

Common Errors

Block / unblock fails when the token is missing or the target user does not exist.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "User not found",4  "data": null,5  "error": "User not found"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	Target `userId` does not exist in this tenant.
400 Bad Request	Missing `userId` / `type`, or `type` is not `block` / `unblock`.
500 Internal Server Error	An unexpected error occurred while updating the block list.

Best Practices

Optimistic UI: toggle Block in the chat profile menu immediately, then roll back if the API errors.
Hide or disable the message composer for blocked peers after a successful block.
Block is personal to the acting chat user - it is not a tenant-wide ban and not the same as Delete User.
Always send tenant headers with the chat user Bearer token over HTTPS.

Block state updated

Update conversation lists and contact menus to reflect the new state, then offer unblock from chat settings when needed.

When to use this endpoint?

Use Block / Unblock when:

A chat participant taps Block on a contact or conversation.
Your report / safety flow ends in stopping messages from that peer.
They reverse a previous block (type: "unblock").
You need a reversible restriction instead of deleting a chat account.

Part of the Chat UserAPIs. Requires the chat user Bearer token for the acting participant. Pass the other person's id - you cannot block yourself.

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Chat user Access Token (Bearer) for the signed-in participant performing the block or unblock.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.
Content-Type	application/json	JSON request body.

Field

Type

Required

Description

userId

string

Required

Target user's _id to block or unblock.

type

string

Required

Action: block or unblock.

Common Errors

Block / unblock fails when the token is missing or the target user does not exist.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 404 Not Found - User missing

json

1{2  "success": false,3  "message": "User not found",4  "data": null,5  "error": "User not found"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	Target `userId` does not exist in this tenant.
400 Bad Request	Missing `userId` / `type`, or `type` is not `block` / `unblock`.
500 Internal Server Error	An unexpected error occurred while updating the block list.

Best Practices

Optimistic UI: toggle Block in the chat profile menu immediately, then roll back if the API errors.
Hide or disable the message composer for blocked peers after a successful block.
Block is personal to the acting chat user - it is not a tenant-wide ban and not the same as Delete User.
Always send tenant headers with the chat user Bearer token over HTTPS.