Чат задачи

GET /v1/tasks/:taskId/chat/messages

Читает ленту чата задачи — новые сообщения первыми. У каждой задачи в Битрикс24 есть групповой чат, и эндпоинт сам определяет чат по ID задачи — знать ID чата не нужно. Типичный сценарий — выгрузка финальных сообщений по закрытой задаче.

Битрикс24 API: im.v2.Chat.Message.tail (на старых порталах — im.dialog.messages.get) Скоуп: task, im

Параметры запроса (query)

Параметр Тип Обяз. Описание
limit number Сообщений на страницу, 1..200, по умолчанию 50
lastId number Курсор: вернуть сообщения старше этого id. Для следующей страницы передайте минимальный id из текущей

Пример

Terminal 
curl "https://vibecode.bitrix24.tech/v1/tasks/53/chat/messages?limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Ответ:

JSON 
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 9123,
        "authorId": 20294,
        "text": "Релиз 24.500.0 готов",
        "createdAt": "2026-06-10T14:51:00+02:00",
        "isSystem": false
      }
    ],
    "hasNextPage": true
  }
}

Поля сообщения

Поле Описание
id ID сообщения — используйте минимальный из страницы как lastId для следующей
authorId Автор (0 у системных сообщений)
text Текст сообщения. Может содержать BB-коды Битрикс24
createdAt Дата создания, ISO 8601
isSystem Системное сообщение («задача поставлена», «срок изменён», …) — фильтруйте по этому флагу, если нужны только реплики людей

Что нужно знать перед работой

  1. Нужен скоуп im на стороне Битрикс24. Эндпоинт читает чат через im.*-методы Битрикс24 — вебхук или OAuth-грант ключа должен включать скоуп im помимо task, иначе портал вернёт insufficient_scope.
  2. Доступ — по членству в чате. Битрикс24 отдаёт сообщения, только если пользователь, от имени которого работает ключ, — участник чата задачи (постановщик, исполнитель, наблюдатель) или администратор портала.
  3. Сообщения идут от новых к старым. Первый элемент — самое свежее сообщение. Пагинация курсором lastId уходит вглубь истории.
  4. 404, если чата ещё нет. Битрикс24 создаёт чат задачи не сразу — у задачи без единого сообщения чата может не быть (TASK_CHAT_NOT_FOUND).
  5. Старые порталы. На порталах без современной im.v2-поверхности API прозрачно переключается на устаревший метод: страница там ограничена 50 сообщениями, а hasNextPage вычисляется по заполненности страницы.
  6. Комментарии и чат. GET /v1/tasks/:taskId/comments возвращает только пользовательские комментарии. Этот эндпоинт — сырую ленту чата целиком, включая системные сообщения.

Ошибки

HTTP Код Причина
400 INVALID_PARAMS Нечисловой taskId, нечисловой или неположительный limit либо lastId. Значение limit больше 200 не ошибка — оно ограничивается до 200
403 SCOPE_DENIED У ключа нет скоупа task
404 TASK_CHAT_NOT_FOUND У задачи нет чата (или задачи не существует)
422 BITRIX_ERROR Ошибка Битрикс24: insufficient_scope (нет im), ACCESS_ERROR (не участник чата)

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

  • Задачи — родительская сущность
  • Комментарии задач — отфильтрованные пользовательские комментарии + отправка
  • Scrum — эпики и скрам-размещение задач