Report Message

Overview

Submit a moderation report for a message - for the chat safety menu, long-press report action, or block-and-report flows inside the messaging client.

Creates a report record linked to the target message. The API returns the new report's _id and initial status so you can confirm submission in the UI.

When to use this endpoint?

Use Report Message when:

The user selects Report from a message context menu or long-press sheet.
Building a safety flow with predefined reasons (spam, harassment, and so on).
Recording a report before hiding or blocking the sender in your client.
Confirming submission with a toast or inline success state after POST.

Part of the Chat Messages APIs for the chat package/SDK (not Platform → Messages). Requires a chat user Access Token for the signed-in messaging participant.

Response Data

The data object contains the created report record:

Field	Description
_id	Report record id. Store if you need to reference this submission later.
status	Initial report status - typically `open` when newly created.

Request Fields

Field	Type	Required	Description
messageId	string	Required	The message `_id` being reported (24-char Mongo ObjectId).
reason	string	Required	Report reason code or label (for example `spam`, `harassment`). Use values your moderation workflow expects.

POST{baseUrl}/api/{apiVersion}/message/report

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.
Content-Type	application/json	JSON request body.

Request Payload

Example reporting a message as spam:

json

1{2  "messageId": "m1",3  "reason": "spam"4}

Success Response (HTTP 201 Created)

On success, the API returns the created report with status open.

json

1{2  "success": true,3  "message": "Message reported successfully",4  "data": {5    "_id": "r1",6    "status": "open"7  },8  "error": null9}

Common Errors

Report fails when the token is missing, the message does not exist, or the user is not allowed to report it.

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 - Message missing

json

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

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	No message exists for the given `messageId` in this tenant.
403 Forbidden	Signed-in user is not allowed to report this message (for example not a conversation participant).
500 Internal Server Error	An unexpected error occurred while creating the report.

Best Practices

Offer a fixed set of report reasons in the UI and map them to stable reason values.
Disable the submit button after a successful report to prevent duplicate submissions.
Show clear confirmation (toast or inline message) with the returned status.
Validate messageId is a 24-character ObjectId before calling the API.
Always send tenant headers, Content-Type: application/json, and the chat user Bearer token over HTTPS.

Safety menu ready

Wire this endpoint to your message long-press or overflow menu. Pair with client-side block/hide actions after the user confirms their report reason.

When to use this endpoint?

Use Report Message when:

The user selects Report from a message context menu or long-press sheet.
Building a safety flow with predefined reasons (spam, harassment, and so on).
Recording a report before hiding or blocking the sender in your client.
Confirming submission with a toast or inline success state after POST.

Part of the Chat Messages APIs for the chat package/SDK (not Platform → Messages). Requires a chat user Access Token for the signed-in messaging participant.

Field

Description

_id

Report record id. Store if you need to reference this submission later.

status

Initial report status - typically open when newly created.

Field

Type

Required

Description

messageId

string

Required

The message _id being reported (24-char Mongo ObjectId).

reason

string

Required

Report reason code or label (for example spam, harassment). Use values your moderation workflow expects.

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.
Content-Type	application/json	JSON request body.

Common Errors

Report fails when the token is missing, the message does not exist, or the user is not allowed to report it.

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 - Message missing

json

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

HTTP 403 Forbidden - Access denied

json

1{2  "success": false,3  "message": "Access denied: insufficient permissions",4  "data": null,5  "error": null6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	No message exists for the given `messageId` in this tenant.
403 Forbidden	Signed-in user is not allowed to report this message (for example not a conversation participant).
500 Internal Server Error	An unexpected error occurred while creating the report.

Best Practices

Offer a fixed set of report reasons in the UI and map them to stable reason values.
Disable the submit button after a successful report to prevent duplicate submissions.
Show clear confirmation (toast or inline message) with the returned status.
Validate messageId is a 24-character ObjectId before calling the API.
Always send tenant headers, Content-Type: application/json, and the chat user Bearer token over HTTPS.