Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/chats/1001/links?limit=50" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
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 — личный ключ
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-приложение
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 |
Пример ответа
Карточка сотрудника сокращена до основных полей:
{
"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 — передан параметр, которого метод не принимает:
{
"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, — последняя.
Видна только доступная история. Если сотруднику видна история чата не с начала — например, его добавили позже без доступа к старым сообщениям, — ссылки до этой границы в выдачу не попадают.