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

Поиск сессий

Метод выходит в обновлении imopenlines 26.700.0 и доступен пока не на всех порталах Битрикс24. Если обновление на ваш портал ещё не пришло, API вернёт 422 METHOD_NOT_YET_AVAILABLE — это признак того, что метод на портале ещё не выпущен, а не ошибка интеграции.

POST /v1/openlines/sessions/search

Список сессий Открытых линий с фильтрами и пагинацией — основной метод для детализированных отчётов и выгрузки во внешние системы аналитики. Пустое тело {} вернёт первую страницу всех видимых сессий.

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

Поле Тип Обяз. Описание
ПолеconfigId Типnumber Обяз.нет ОписаниеИдентификатор линии. Источник: GET /v1/openline-configs
ПолеconfigIdList Типnumber[] Обяз.нет ОписаниеСписок идентификаторов линий. Источник: GET /v1/openline-configs
ПолеoperatorId Типnumber Обяз.нет ОписаниеИдентификатор оператора. Источник: GET /v1/users
ПолеoperatorIdList Типnumber[] Обяз.нет ОписаниеСписок идентификаторов операторов. Источник: GET /v1/users
Полеsource Типstring Обяз.нет ОписаниеКод коннектора, например livechat. Значения — поле sessions[].source в ответе этого метода или sessionsBySource[].source в ответе POST /v1/openlines/stats
ПолеsourceList Типstring[] Обяз.нет ОписаниеСписок кодов коннекторов
Полеstatus Типstring Обяз.нет ОписаниеСтатус сессии: new / answered / closed / spam / paused
ПолеcloseReason Типstring Обяз.нет ОписаниеПричина закрытия: operator / auto / spam / client / replyLimit
ПолеdateCreateFrom Типstring Обяз.нет ОписаниеНачало периода создания, ISO 8601. Период dateCreateFrom..dateCreateTo — не больше 1 года
ПолеdateCreateTo Типstring Обяз.нет ОписаниеКонец периода создания, ISO 8601
ПолеdateCloseFrom Типstring Обяз.нет ОписаниеНачало периода закрытия, ISO 8601
ПолеdateCloseTo Типstring Обяз.нет ОписаниеКонец периода закрытия, ISO 8601
Полеvote Типstring Обяз.нет ОписаниеКлиентская оценка: like / dislike / none / any
ПолеhasVoteHead Типstring Обяз.нет ОписаниеЕсть ли оценка руководителя: Y / N
ПолеkpiFirstAnswer Типstring Обяз.нет ОписаниеУложились ли в норматив времени первого ответа (SLA): Y / N. Требует ограниченного периода (dateCreateFrom+dateCreateTo либо dateCloseFrom+dateCloseTo)
ПолеhasCrm Типstring Обяз.нет ОписаниеЕсть ли привязка к CRM: Y / N
ПолеwaitAnswerFrom Типnumber Обяз.нет ОписаниеМин. время до первого ответа, секунды
ПолеwaitAnswerTo Типnumber Обяз.нет ОписаниеМакс. время до первого ответа, секунды
ПолеwaitCloseFrom Типnumber Обяз.нет ОписаниеМин. время до закрытия, секунды
ПолеwaitCloseTo Типnumber Обяз.нет ОписаниеМакс. время до закрытия, секунды
Полеorder Типstring Обяз.нет ОписаниеПоле сортировки: dateCreate / dateClose / waitAnswer / waitClose (по умолчанию dateCreate)
ПолеorderDirection Типstring Обяз.нет ОписаниеНаправление: asc / desc (по умолчанию desc)
Полеlimit Типnumber Обяз.нет ОписаниеРазмер страницы, 1..200 (по умолчанию 50). Значение вне диапазона не даёт ошибки — возвращается страница из 50 записей
Полеoffset Типnumber Обяз.нет ОписаниеСмещение для пагинации (по умолчанию 0)

Фильтры status и closeReason взаимоисключающи: closeReason уже подразумевает закрытую сессию. Фильтр hasVoteHead применяется только к линиям, где у пользователя есть право на оценку руководителя.

Фильтра по типу CRM-сущности нет — по CRM доступен только флаг hasCrm (есть привязка или нет). Если нужен отбор по конкретному типу, фильтруйте на своей стороне по полям crmEntityType / crmEntityId из ответа.

Пагинация. Следующая страница — тот же запрос с offset, увеличенным на limit, пока data.hasNextPage равно true. При постраничной выгрузке фиксируйте верхнюю границу периода — dateCreateTo равным моменту начала выгрузки. Без фиксированной границы новые сессии, пришедшие во время выгрузки, сдвигают страницы, и записи на стыках могут повториться или пропасть.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+03:00",
    "dateCreateTo": "2024-05-31T23:59:59+03:00",
    "limit": 2
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+03:00",
    "dateCreateTo": "2024-05-31T23:59:59+03:00",
    "limit": 2
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+03:00',
    dateCreateTo: '2024-05-31T23:59:59+03:00',
    limit: 2,
  }),
})
const { data } = await res.json()

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+03:00',
    dateCreateTo: '2024-05-31T23:59:59+03:00',
    limit: 2,
  }),
})
const { data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном ответе
Полеdata.sessions Типarray ОписаниеСессии текущей страницы. Пустой массив, если под фильтры ничего не попало
Полеdata.sessions[].id Типnumber ОписаниеИдентификатор сессии
Полеdata.sessions[].configId Типnumber ОписаниеИдентификатор линии. Описание линии — GET /v1/openline-configs/:id
Полеdata.sessions[].source Типstring ОписаниеКод коннектора
Полеdata.sessions[].operatorId Типnumber | null ОписаниеИдентификатор оператора, завершившего сессию. Сотрудник — GET /v1/users
Полеdata.sessions[].userId Типnumber ОписаниеВнутренний идентификатор клиента
Полеdata.sessions[].userCode Типstring ОписаниеВнешний код клиента в коннекторе
Полеdata.sessions[].chatId Типnumber ОписаниеИдентификатор чата Открытой линии. Один чат проходит через несколько сессий
Полеdata.sessions[].dateCreate Типstring ОписаниеДата создания сессии, ISO 8601
Полеdata.sessions[].dateClose Типstring | null ОписаниеДата закрытия сессии, ISO 8601
Полеdata.sessions[].dateFirstAnswer Типstring | null ОписаниеДата первого ответа, ISO 8601
Полеdata.sessions[].dateOperatorAnswer Типstring | null ОписаниеДата, когда оператор начал работу с сессией, ISO 8601. Это другой момент, чем dateFirstAnswer
Полеdata.sessions[].status Типstring ОписаниеСтатус: new / answered / closed / spam / paused
Полеdata.sessions[].closeReason Типstring | null ОписаниеПричина закрытия: operator / auto / spam / client / replyLimit
Полеdata.sessions[].vote Типstring ОписаниеКлиентская оценка: like / dislike / none
Полеdata.sessions[].voteHead Типnumber | null ОписаниеОценка руководителя. null, если оценки нет или у пользователя нет права на оценку руководителя
Полеdata.sessions[].commentHead Типstring | null ОписаниеКомментарий руководителя. null в тех же случаях, что voteHead
Полеdata.sessions[].crmEntityType Типstring | null ОписаниеТип привязанной CRM-сущности, например lead или deal. null, если привязки нет или нет права чтения связанной сущности
Полеdata.sessions[].crmEntityId Типnumber | null ОписаниеИдентификатор привязанной CRM-сущности. Карточка — по типу из crmEntityType: лид GET /v1/leads/:id, сделка GET /v1/deals/:id, контакт GET /v1/contacts/:id, компания GET /v1/companies/:id
Полеdata.sessions[].queueTransfers Типnumber ОписаниеЧисло переназначений в очереди. Сами переназначения — История переназначений
Полеdata.sessions[].waitAnswer Типnumber | null ОписаниеВремя до первого ответа, секунды. Хранимая метрика — не вычисляйте её из дат выше, значения могут не совпасть
Полеdata.sessions[].waitClose Типnumber | null ОписаниеВремя до закрытия, секунды. Хранимая метрика, как waitAnswer
Полеdata.sessions[].kpiFirstAnswer Типboolean | null ОписаниеУложились ли в норматив времени первого ответа
Полеdata.sessions[].messageCount Типnumber ОписаниеЧисло сообщений в сессии
Полеdata.hasNextPage Типboolean ОписаниеЕсть ли следующая страница

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

JSON 
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 781,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1211,
        "userCode": "livechat|1|2073|1211",
        "chatId": 2075,
        "dateCreate": "2024-05-13T15:08:33+03:00",
        "dateClose": "2024-06-13T15:46:31+03:00",
        "dateFirstAnswer": "2024-05-13T15:12:05+03:00",
        "dateOperatorAnswer": "2024-05-13T15:09:14+03:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "like",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "contact",
        "crmEntityId": 2399,
        "queueTransfers": 0,
        "waitAnswer": 212,
        "waitClose": 116,
        "kpiFirstAnswer": false,
        "messageCount": 5
      },
      {
        "id": 779,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1209,
        "userCode": "livechat|1|2069|1209",
        "chatId": 2071,
        "dateCreate": "2024-05-13T15:05:52+03:00",
        "dateClose": "2024-05-13T16:11:52+03:00",
        "dateFirstAnswer": "2024-05-13T15:06:50+03:00",
        "dateOperatorAnswer": "2024-05-13T15:06:41+03:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "none",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "deal",
        "crmEntityId": 5317,
        "queueTransfers": 0,
        "waitAnswer": 58,
        "waitClose": 144,
        "kpiFirstAnswer": true,
        "messageCount": 2
      }
    ],
    "hasNextPage": false
  }
}

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

422 — период превышает 1 год:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "Запрошенный период превышает максимум в 1 год", "b24Code": "PERIOD_TOO_LARGE" }
}

Текст error.message локализован. Для обработки ошибки сверяйте error.b24Code.

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_JSON_BODY ОписаниеТело запроса не разобралось как JSON. JSON разбирается до проверки полей, поэтому про отсутствующие параметры ответ ничего не говорит
HTTP400 КодINVALID_PARAMS ОписаниеТело запроса не объект
HTTP422 КодBITRIX_ERROR (error.b24Code: PERIOD_TOO_LARGE) ОписаниеПериод создания или закрытия превышает 1 год
HTTP422 КодBITRIX_ERROR (error.b24Code: OFFSET_TOO_LARGE) Описаниеoffset превышает максимум — сузьте период или фильтры
HTTP422 КодBITRIX_ERROR (error.b24Code: INVALID_FILTER) ОписаниеНедопустимое значение фильтра, одновременно переданы status и closeReason, либо kpiFirstAnswer без ограниченного периода
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеОбновление imopenlines 26.700.0 ещё не пришло на портал. Ответ содержит поле error.release со значением imopenlines 26.700.0
HTTP403 КодB24_TARIFF_RESTRICTION ОписаниеТариф не включает статистику Открытых линий (report_open_lines)
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа imopenlines
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет настроенных токенов

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

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