[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Fmessages\u002Fforward":3,"docs-tabs-chats\u002Fmessages\u002Fforward":6},{"content":4,"lastmod":5},"## Forward messages\n\n`POST \u002Fv1\u002Fchats\u002F:dialogId\u002Fforward`\n\nForwards up to 20 messages to a chat, optionally with a comment.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|---------|\n| `dialogId` (path) | string | yes | — | ID of the dialog the messages go to: numeric user ID for personal messages, `chatXXX` for group chats. The special `me` alias refers to the current user's personal dialog. `chatXXX` is the `id` field of a [recent dialogs](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Frecent) row; a user ID comes from the [user list](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `forwardIds` | object | yes | What to forward: the key is a client UUID v4 in lower case, the value is the ID of the message to forward, from the [chat feed](\u002Fdocs\u002Fchats\u002Fmessages\u002Flist). From 1 to 20 entries; each message can appear only once |\n| `message` | string | no | A comment posted before the forwarded messages, up to 20000 Unicode code points. Must pass the blank-comment check below |\n| `templateId` | string | no | Client ID of the comment, up to 255 characters. Returned in push events. Accepted only together with `message` |\n\nAny other body field and any query parameter are rejected with `400 INVALID_PARAMS`.\n\nFor a valid non-blank comment, the complete outgoing string is counted, including markup, URLs and mentions, without truncation or trimming. For example, `😀` is one code point, while a compound emoji may occupy several. A comment longer than 20000 code points is rejected with `400 MESSAGE_TOO_LONG` before any Bitrix24 call, including resolving `me`.\n\nThe existing input checks run before the length check. When supplied, `message` must be a string and contain something besides spaces, tabs, line feeds, carriage returns, NUL characters and vertical tabs. Otherwise, the request returns `400 INVALID_PARAMS`, even when the string exceeds 20000 code points. Invalid `forwardIds`, `templateId` and disallowed fields also retain their priority. Omitting `message` still forwards without a comment.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fforward\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"forwardIds\":{\"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\":1001},\"message\":\"Please take a look\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fforward\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"forwardIds\":{\"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\":1001},\"message\":\"Please take a look\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fforward', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\"forwardIds\":{\"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\":1001},\"message\":\"Please take a look\"}),\n})\n\nconst { data } = await res.json()\nconsole.log('Forwarded:', Object.keys(data.uuidMap).length)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fforward', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\"forwardIds\":{\"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\":1001},\"message\":\"Please take a look\"}),\n})\n\nconst { data } = await res.json()\nconsole.log('Forwarded:', Object.keys(data.uuidMap).length)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.id` | number \\| null | ID of the comment. `null` when there was no comment |\n| `data.uuidMap` | object | UUID from the request → ID of the message copy in the chat. Exactly what is listed here was forwarded |\n| `data.failureMap` | object \\| array | UUID → Bitrix24 refusal code for the messages that could not be forwarded. An empty array `[]` when nothing was refused. Returned starting with `im 26.1300` |\n| `data.legacyFailureMap` | object | Message ID → refusal code for messages without a client UUID. Returned starting with `im 26.1300`, and only when non-empty |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 1100,\n    \"uuidMap\": {\n      \"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\": 1101\n    },\n    \"failureMap\": []\n  }\n}\n```\n\n## Error response example\n\n400 — a `forwardIds` key is not a lower-case UUID v4:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Every key of `forwardIds` must be a UUID v4 in lower case. `forwardIds` is required: an object mapping a client UUID v4 (lower case) to the id of a message to forward, e.g. {\\\"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f\\\": 1001}.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MESSAGE_TOO_LONG` | After the other input checks, a valid non-blank comment exceeds 20000 Unicode code points. `error.details` contains only `field: \"message\"`, `used`, `limit: 20000`, `unit: \"unicode-code-points\"`. No Bitrix24 call is made |\n| 400 | `INVALID_PARAMS` | No `forwardIds`, it is not an object, it has no entries or more than 20. A key is not a lower-case UUID v4. A value is not a positive integer. The same message is listed twice. `message` is blank or not a string. `templateId` without `message` or longer than 255 characters. Any other body field or any query parameter. Checked before any call to Bitrix24 |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported \"not found\". The portal code is in `error.b24Code` |\n| 422 | `BITRIX_ERROR` | Bitrix24 returned an error. The code is in `error.b24Code`: `MESSAGE_NOT_FOUND` — one of the messages does not exist, in which case nothing is forwarded. `CHAT_NOT_FOUND` — the target chat does not exist |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only, and forwarding posts messages — see [access rights](\u002Fdocs\u002Faccess-rights) |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | The `me` alias could not be resolved: Bitrix24 returned no ID of the current user. Nothing was sent to the chat |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`200` does not mean \"everything was forwarded\".** If the key's user cannot forward a message, that message is skipped instead of the whole call being rejected. Starting with `im 26.1300`, the skipped messages are listed with their refusal code in `data.failureMap`. On earlier versions these fields are absent and the skip is silent — compare the request with `uuidMap`.\n\n**The UUID identifies the copy on the client side.** Use it to find the copy in the response and in push events before the copy's ID is known.\n\n**Repeating with the same UUID does not create a second copy.** The UUID of a forwarded message is remembered for about a month, and a repeated request returns the ID of the existing copy in `uuidMap`. A request whose response was lost can therefore be safely repeated with the same `forwardIds`. For a new forward, generate a new UUID — for example, `crypto.randomUUID()`.\n\n## See also\n\n- [Send a message](\u002Fdocs\u002Fchats\u002Fmessages\u002Fsend)\n- [Read messages](\u002Fdocs\u002Fchats\u002Fmessages\u002Flist)\n- [Messages](\u002Fdocs\u002Fchats\u002Fmessages)\n","2026-10-17",{},1794739547314]