Delete User

Overview

Permanently remove a chat user by their userId - for example account deletion or cleaning up a messaging identity from the chat app.

On success, the API returns the deleted user so you can clear local chat state (threads, caches, people picker). This is not Platform panel bulk/user admin delete (Platform → Users).

When to use this endpoint?

Use Delete User when:

The chat participant deletes their messaging account.
You need to remove a test or obsolete chat identity from the tenant.
Hard delete is required - not just hiding someone from chats.

Deletion is irreversible. Prefer Block / Unblock when a participant only needs to stop messaging someone without removing either account.

DELETE{baseUrl}/api/{apiVersion}/user/:userId

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 messaging participant.
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	694b7ab37f8f05a7ac678b6b	The target user's `_id` (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

On success, the API returns the deleted user snapshot.

json

1{2  "success": true,3  "message": "User deleted successfully",4  "data": {5    "_id": "694b7ab37f8f05a7ac678b6b",6    "name": "test 2 user",7    "email": "test2@hgmail.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z",12    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY5NGI3YWIzN2Y4ZjA1YTdhYzY3OGI2YiIsImlhdCI6MTc2NjU1NDI5MSwiZXhwIjoxNzY3MTU5MDkxfQ.xArw6kNaz9cc3nW2IXh6tgj7GyIJXXa2i1A6r1Oi8Mw"13  },14  "error": null15}

Common Errors

Delete fails when the token is missing or the 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	No user exists for the given `userId`.
500 Internal Server Error	An unexpected error occurred while deleting the user.

Best Practices

Confirm with a destructive step in chat settings before calling delete.
Clear local conversations, draft messages, and people-picker cache for the deleted _id.
Prefer block when the goal is only to stop messaging a peer; use delete only when the chat account itself must be removed.
Always send tenant headers with the chat user Bearer token over HTTPS.

Chat user deleted

Sign the participant out of chat if they deleted themselves, or remove them from pickers and threads using the returned _id.

Overview

Permanently remove a chat user by their userId - for example account deletion or cleaning up a messaging identity from the chat app.

On success, the API returns the deleted user so you can clear local chat state (threads, caches, people picker). This is not Platform panel bulk/user admin delete (Platform → Users).

When to use this endpoint?

Use Delete User when:

The chat participant deletes their messaging account.
You need to remove a test or obsolete chat identity from the tenant.
Hard delete is required - not just hiding someone from chats.

Deletion is irreversible. Prefer Block / Unblock when a participant only needs to stop messaging someone without removing either account.

Header

Value

Description

Authorization

Bearer <access_token>

Chat user Access Token (Bearer) for the signed-in messaging participant.

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

694b7ab37f8f05a7ac678b6b

The target user's _id (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

On success, the API returns the deleted user snapshot.

json

1{2  "success": true,3  "message": "User deleted successfully",4  "data": {5    "_id": "694b7ab37f8f05a7ac678b6b",6    "name": "test 2 user",7    "email": "test2@hgmail.com",8    "isActive": true,9    "role": "user",10    "createdAt": "2025-12-24T05:31:31.606Z",11    "updatedAt": "2025-12-24T05:31:31.723Z",12    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY5NGI3YWIzN2Y4ZjA1YTdhYzY3OGI2YiIsImlhdCI6MTc2NjU1NDI5MSwiZXhwIjoxNzY3MTU5MDkxfQ.xArw6kNaz9cc3nW2IXh6tgj7GyIJXXa2i1A6r1Oi8Mw"13  },14  "error": null15}

Common Errors

Delete fails when the token is missing or the 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	No user exists for the given `userId`.
500 Internal Server Error	An unexpected error occurred while deleting the user.

Best Practices

Confirm with a destructive step in chat settings before calling delete.
Clear local conversations, draft messages, and people-picker cache for the deleted _id.
Prefer block when the goal is only to stop messaging a peer; use delete only when the chat account itself must be removed.
Always send tenant headers with the chat user Bearer token over HTTPS.