API Reference
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. |
{baseUrl}/api/{apiVersion}/message/reportAuthentication
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:
{
"messageId": "m1",
"reason": "spam"
}Success Response (HTTP 201 Created)
On success, the API returns the created report with status open.
{
"success": true,
"message": "Message reported successfully",
"data": {
"_id": "r1",
"status": "open"
},
"error": null
}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
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 404 Not Found — Message missing
{
"success": false,
"message": "Message not found",
"data": null,
"error": "Message not found"
}HTTP 403 Forbidden — Access denied
{
"success": false,
"message": "Access denied: insufficient permissions",
"data": null,
"error": null
}| 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
reasonvalues. - Disable the submit button after a successful report to prevent duplicate submissions.
- Show clear confirmation (toast or inline message) with the returned
status. - Validate
messageIdis 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.