Для AI-агентов: markdown этой страницы — /docs-content/chats/messages/forward.md индекс документации — /llms.txt

Пересылка сообщений

POST /v1/chats/:dialogId/forward

Пересылает в чат до 20 сообщений, при необходимости с комментарием.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — ID диалога, куда пересылаются сообщения: числовой ID пользователя для личных сообщений, chatXXX для групповых. Специальный алиас me — личный диалог текущего пользователя. chatXXX — поле id строки последних диалогов, ID пользователя — из списка пользователей

Поля запроса (body)

Поле Тип Обяз. Описание
forwardIds object да Что переслать: ключ — клиентский UUID v4 в нижнем регистре, значение — ID пересылаемого сообщения из ленты чата. От 1 до 20 записей, каждое сообщение — один раз
message string нет Комментарий, который публикуется перед пересланными сообщениями. Должен содержать что-то кроме пробелов
templateId string нет Клиентский ID комментария, до 255 символов. Возвращается в push-событиях. Принимается только вместе с message

Другие поля тела и любые параметры запроса отклоняются с 400 INVALID_PARAMS.

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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":"Посмотрите, пожалуйста"}'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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":"Посмотрите, пожалуйста"}'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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":"Посмотрите, пожалуйста"}),
})

const { data } = await res.json()
console.log('Переслано:', Object.keys(data.uuidMap).length)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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":"Посмотрите, пожалуйста"}),
})

const { data } = await res.json()
console.log('Переслано:', Object.keys(data.uuidMap).length)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.id number | null ID комментария. null, если комментария не было
data.uuidMap object UUID из запроса → ID копии сообщения в чате. Переслано ровно то, что здесь перечислено
data.failureMap object | array UUID → код отказа Битрикс24 для сообщений, которые переслать не удалось. Пустой массив [], если отказов нет. Приходит начиная с im 26.1300
data.legacyFailureMap object ID сообщения → код отказа для сообщений без клиентского UUID. Приходит начиная с im 26.1300 и только непустым

Пример ответа

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

Пример ответа при ошибке

400 — ключ forwardIds не 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}."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Нет forwardIds, это не объект, в нём нет записей или больше 20. Ключ не UUID v4 в нижнем регистре. Значение не положительное целое. Одно сообщение указано дважды. message пустой или не строка. templateId без message или длиннее 255 символов. Другое поле тела или любой параметр запроса. Проверяется до обращения к Битрикс24
404 ENTITY_NOT_FOUND Битрикс24 вернул «не найдено». Код портала — в error.b24Code
422 BITRIX_ERROR Битрикс24 вернул ошибку. Код — в error.b24Code: MESSAGE_NOT_FOUND — одного из сообщений нет, и тогда не пересылается ничего. CHAT_NOT_FOUND — чата назначения нет
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения, а пересылка публикует сообщения — см. права доступа
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
502 ME_ALIAS_RESOLUTION_FAILED Алиас me не удалось разрешить: Битрикс24 не вернул ID текущего пользователя. В чат ничего не отправлено

Полный список общих ошибок API — Ошибки.

Известные особенности

200 не значит «переслано всё». Сообщение, которое пользователь ключа переслать не может, пропускается, а весь вызов не отклоняется. Начиная с im 26.1300 пропущенные сообщения с кодом отказа перечислены в data.failureMap. На более ранних версиях этих полей нет, и пропуск молчаливый — сверяйте запрос с uuidMap.

UUID — идентификатор копии на стороне клиента. По нему копия находится в ответе и в push-событиях до того, как станет известен её ID.

Повтор с тем же UUID не создаёт вторую копию. UUID пересланного сообщения запоминается примерно на месяц, и повторный запрос возвращает в uuidMap ID существующей копии. Поэтому запрос, ответ на который потерялся, можно безопасно повторить с теми же forwardIds. Для новой пересылки генерируйте новый UUID — например, crypto.randomUUID().

Смотрите также