API Reference
Update Message
Overview
Partially update an existing message in the tenant workspace. This endpoint supports independent updates — you can change a single field or both fields in one request.
Only these request payload fields can be updated:
content— the message textmetadata— custom key/value data
Other message properties (sender, attachments, reactions, status, and similar) are not editable through this endpoint. On success the API returns the updated message and sets isEdited to true when content changes. System messages cannot be edited.
When to use this endpoint?
Use Update Message when:
- Correcting or editing the text of a user-sent message (
contentonly). - Updating custom metadata used for moderation, analytics, or filters (
metadataonly). - Saving both content and metadata from an edit or moderation panel.
- You need the updated document returned for an immediate UI refresh.
Do not call this endpoint for system messages — the API returns 400 Bad Request with System messages cannot be edited. At least one of content or metadata must be present in the body.
Editable Fields
The table below lists every field this endpoint accepts. Each field can be updated on its own (single-field update) or combined with the other.
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Optional | Updated message text. Send this alone to edit the content without changing metadata. When content changes, isEdited becomes true in the response. |
| metadata | object | Optional | Custom key/value data (for example moderation flags). Send this alone to update metadata without changing the message text. |
Both fields are optional individually, but the body must include at least one of them. Unsupported fields in the payload are ignored.
Single-Field Updates
Because this endpoint is partial, each editable value can be updated independently. Use these patterns when your UI changes one setting at a time.
Update content only
Use this when the user edits the message text. Metadata is left unchanged.
{
"content": "Corrected: the maintenance window is 02:00-03:00 UTC."
}Update metadata only
Use this for moderation or admin tools that flag a message without rewriting its content.
{
"metadata": {
"moderated": true
}
}{baseUrl}/api/{apiVersion}/client/messages/:messageIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Access Token from Login Client or Register Client. |
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
| Content-Type | application/json | Required when sending a JSON request body. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| messageId | string | Message _id (24-char Mongo ObjectId) of the message to update. |
Request Payload
Example combining both editable fields in one request. You do not need to send every field — omit anything you are not changing.
{
"content": "Corrected: the maintenance window is 02:00-03:00 UTC.",
"metadata": {
"moderated": true
}
}Success Response (HTTP 200 OK)
On success, the API returns the updated message with the new field values merged into the existing document.
{
"success": true,
"message": "Message updated successfully",
"data": {
"_id": "6a2f...caf5",
"conversationId": "6a4c...dada",
"sender": {
"_id": "6a3c...14fe",
"name": "chat3"
},
"content": "Corrected: the maintenance window is 02:00-03:00 UTC.",
"type": "text",
"isEdited": true,
"isSystemMessage": false,
"isForwarded": false,
"isDeletedForEveryone": false,
"metadata": {
"moderated": true
},
"attachments": [],
"reactions": [],
"deletedFor": [],
"readBy": ["6a3c...14fe"],
"starredBy": [],
"status": "read",
"createdAt": "2026-07-08T15:04:05.000Z",
"updatedAt": "2026-07-09T11:30:00.000Z",
"__v": 4
},
"error": null
}Error Responses
HTTP 400 Bad Request — System message
Returned when the target message is a system message (isSystemMessage: true) and cannot be edited.
{
"success": false,
"message": "System messages cannot be edited",
"data": null,
"error": "System messages cannot be edited"
}Common Errors
Update fails when the message is a system message, nothing editable is provided, the ID is invalid, or authentication is missing.
| Code | Reason |
|---|---|
| 400 Bad Request | System messages cannot be edited, or the payload is invalid / has no editable fields. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | Message not found for the given messageId. |
| 500 Internal Server Error | An unexpected error occurred while updating the message. |
Best Practices
- Prefer single-field updates when the UI changes only content or only metadata.
- Skip update for messages where
isSystemMessageistrue. - Never send an empty body — always include
contentand/ormetadata. - Keep metadata keys consistent so list filters continue to work.
- Always send Content-Type: application/json with tenant headers and a Bearer token.
- Refresh List Messages after a successful update so the UI shows the edited content.
Message updated
Refresh your list or conversation thread to show the latest content and metadata. Continue with List Messages or Delete Message if you need to remove it.