Forward messages

POST /v1/chats/:dialogId/forward

Forwards up to 20 messages to a chat, optionally with a comment.

Parameters

Request body fields

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

For 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.

The 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.

Examples

curl — personal key

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

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

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

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

Response example

{
  "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:

{
  "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

The 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, 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.

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.

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().

See also

• Send a message
• Read messages
• Messages