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

Список ссылок чата

GET /v1/chats/:chatId/links

Возвращает страницу ссылок, отправленных в сообщениях чата: тот же список, что на вкладке «Ссылки» правой панели чата. Новые ссылки идут первыми.

Параметры

Параметр Тип Обяз. По умолч. Описание
ПараметрchatId (path) Типnumber Обяз.да По умолч.— ОписаниеID чата. Получить: GET /v1/chats/recent
Параметрlimit (query) Типnumber Обяз.нет По умолч.50 ОписаниеСколько ссылок вернуть, от 1 до 200. Значение вне диапазона приводится к ближайшей границе, тогда в ответе приходят meta.requestedLimit и meta.appliedLimit
Параметрoffset (query) Типnumber Обяз.нет По умолч.0 ОписаниеСколько ссылок пропустить с начала списка, неотрицательное целое. Для следующей страницы передайте число уже полученных ссылок
ПараметрsearchQuery (query) Типstring Обяз.нет По умолч.— ОписаниеОставляет ссылки, адрес которых содержит этот текст. Непустая строка не длиннее 255 символов

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

Примеры

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/chats/1001/links?limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/chats/1001/links?limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/1001/links?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Ссылки:', data.list.map((link) => link.url.source))

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/1001/links?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Ссылки:', data.list.map((link) => link.url.source))

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.list Типarray ОписаниеСсылки страницы
Полеdata.list[].id Типnumber ОписаниеID ссылки. Нужен для удаления из списка
Полеdata.list[].messageId Типnumber ОписаниеID сообщения со ссылкой
Полеdata.list[].chatId Типnumber ОписаниеID чата
Полеdata.list[].authorId Типnumber ОписаниеID отправителя сообщения, карточка — в data.users
Полеdata.list[].dateCreate Типstring ОписаниеДата отправки (ISO 8601)
Полеdata.list[].url.source Типstring ОписаниеАдрес ссылки в том виде, в каком он записан в сообщении
Полеdata.list[].url.richData Типobject ОписаниеДанные превью ссылки: id, type, name, description, previewUrl, link. У ссылки без превью все поля null
Полеdata.users Типarray ОписаниеОтправители сообщений. Поля — как у участника в списке участников чата: id, name, firstName, lastName, active, type и другие
Полеdata.tariffRestrictions.isHistoryLimitExceeded Типboolean Описаниеtrue, когда тариф скрывает часть старой истории чата и её ссылки не попадают в выдачу
Полеmeta.requestedLimit Типnumber ОписаниеПереданный limit. Только когда он вне диапазона 1–200
Полеmeta.appliedLimit Типnumber ОписаниеПрименённый limit после приведения к границе. Только вместе с meta.requestedLimit

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

Карточка сотрудника сокращена до основных полей:

JSON
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 6,
        "active": true,
        "name": "Анна Смирнова",
        "firstName": "Анна",
        "lastName": "Смирнова",
        "workPosition": "",
        "bot": false,
        "extranet": false,
        "status": "online",
        "type": "user"
      }
    ],
    "tariffRestrictions": {
      "isHistoryLimitExceeded": false
    },
    "list": [
      {
        "id": 12,
        "messageId": 34213,
        "chatId": 1001,
        "authorId": 6,
        "dateCreate": "2026-03-03T11:44:09+03:00",
        "url": {
          "source": "https://example.com/page",
          "richData": {
            "id": null,
            "type": null,
            "name": null,
            "description": null,
            "previewUrl": null,
            "link": null
          }
        }
      },
      {
        "id": 11,
        "messageId": 34211,
        "chatId": 1001,
        "authorId": 6,
        "dateCreate": "2026-03-03T11:43:35+03:00",
        "url": {
          "source": "https://example.com/notes",
          "richData": {
            "id": null,
            "type": null,
            "name": null,
            "description": null,
            "previewUrl": null,
            "link": null
          }
        }
      }
    ]
  }
}

При limit=500 ответ дополнительно несёт "meta": { "requestedLimit": 500, "appliedLimit": 200 }.

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

400 — передан параметр, которого метод не принимает:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `lastId` is not accepted by GET /v1/chats/:chatId/links. Accepted: limit, offset, searchQuery."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_CHAT_ID ОписаниеchatId не является положительным целым числом. Проверяется до обращения к Битрикс24
HTTP400 КодINVALID_PARAMS Описаниеlimit не целое число, offset не неотрицательное целое, пустой searchQuery или длиннее 255 символов, повтор параметра или неизвестный параметр — сообщение называет его и перечисляет допустимые. Проверяется до обращения к Битрикс24
HTTP422 КодBITRIX_ERROR Описаниеerror.b24Code равен ACCESS_ERROR — у сотрудника нет доступа к чату или чата нет
HTTP404 КодENTITY_NOT_FOUND ОписаниеБитрикс24 вернул общую ошибку «не найдено», код портала — в error.b24Code
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа im
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов Битрикс24

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

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

Конец выдачи. Страница, в которой ссылок меньше limit, — последняя.

Видна только доступная история. Если сотруднику видна история чата не с начала — например, его добавили позже без доступа к старым сообщениям, — ссылки до этой границы в выдачу не попадают.

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