For AI agents: markdown of this page — /docs-content-en/chats/messages/forward.md documentation index — /llms.txt

Forward messages

POST /v1/chats/:dialogId/forward

Forwards up to 20 messages to a chat, optionally with a comment — the v2 messenger method im.v2.Chat.Message.send with the forwardIds field. The me alias as dialogId addresses the current user's personal dialog — see the Chats overview for details.

Parameters

Parameter Type Required Default Description
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 — the current user's personal dialog

Request body fields

Field Type Required Description
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 1 to 20 entries; each message can appear only once
message string no A comment posted before the forwarded messages. Must contain at least one non-whitespace character
templateId string no Client ID of the comment, up to 255 characters; returned in push events. Accepted only together with message

Any other body field and any query parameter are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/forward" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"forwardIds":{"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f":1001},"message":"Please take a look"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/forward" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forwardIds":{"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f":1001},"message":"Please take a look"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/forward', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"forwardIds":{"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f":1001},"message":"Please take a look"}),
})

const { data } = await res.json()
console.log('Forwarded:', Object.keys(data.uuidMap).length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/forward', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"forwardIds":{"3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f":1001},"message":"Please take a look"}),
})

const { data } = await res.json()
console.log('Forwarded:', Object.keys(data.uuidMap).length)

Response fields

Field Type Description
success boolean Always true on success
data.id number | null ID of the comment; null when there was no comment
data.uuidMap object UUID from the request → ID of the message copy in the chat. Exactly what is listed here was forwarded
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
data.legacyFailureMap object Message ID → refusal code for messages without a client UUID. Returned starting with im 26.1300, and only when non-empty

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1100,
    "uuidMap": {
      "3f2b8c1e-5d4a-4b6f-9e7d-1a2b3c4d5e6f": 1101
    },
    "failureMap": []
  }
}

Error response example

400 — a forwardIds key is not a lower-case UUID v4:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "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}."
  }
}

Errors

HTTP Code Description
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
404 ENTITY_NOT_FOUND Bitrix24 reported "not found"; the portal code is in error.b24Code
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
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only, and forwarding posts messages — see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
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

Full list of common API errors — Errors.

Known specifics

200 does not mean "everything was forwarded". If the key's user cannot forward a message, Bitrix24 skips it instead of rejecting the whole call. Exactly what is in data.uuidMap was forwarded. 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.

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. Upper-case UUIDs are rejected: Bitrix24 accepts a UUID v4 only in lower case.

Repeating with the same UUID does not create a second copy. Bitrix24 remembers the UUID of a forwarded message for about a month and on 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().

A blank comment is refused up front. Bitrix24 would reject a whitespace-only comment together with the whole forward, so such a message is rejected with 400. If you don't need a comment, omit the field.

See also