API Reference
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.
{baseUrl}/api/{apiVersion}/user/block-unblockAuthentication
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
{
"userId": "694b...a1",
"type": "block"
}Unblock
{
"userId": "694b...a1",
"type": "unblock"
}Success Response (HTTP 200 OK)
On success, the API confirms the action. data may be null; rely on message for UI feedback.
{
"success": true,
"message": "User blocked successfully",
"data": null,
"error": null
}Common Errors
Block / unblock fails when the token is missing or the target user does not exist.
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 404 Not Found — User missing
{
"success": false,
"message": "User not found",
"data": null,
"error": "User not found"
}| 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.