Открытые линии

Открытые линии Битрикс24 принимают обращения клиентов из мессенджеров и социальных сетей и распределяют их по операторам. Методы раздела настраивают линии, ведут диалоги от имени оператора, связывают их с карточками CRM и читают статистику контакт-центра.

Скоуп: imopenlines | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок

Разделы документации

• Конфигурации открытых линий — создание, чтение, изменение, удаление и поиск линий, а также приём и завершение диалога оператором
• Быстрые ответы открытой линии — шаблоны ответов линии: список, создание, изменение, удаление
• Сессии открытых линий — поиск сессий, их метрики, переназначения и переписка, открытие чата клиента, начало сессии, перехват диалога, вход в диалог и отправка CRM-формы клиенту
• Чаты по карточке CRM — диалоги линии, привязанные к лиду, сделке, компании или контакту
• Действия CRM-чата — добавить сотрудника в CRM-чат и удалить его, написать клиенту, создать лид из обращения
• Метаданные диалога — карточка диалога и ID линии по chatId, dialogId или sessionId
• История сессии — переписка последней сессии чата одним ответом
• Действия оператора и своя пауза — пропустить, передать, пометить клиента спамером, завершить чужой диалог, управлять своей паузой оператора
• Агрегаты по линии за период — сводные показатели линии для панели мониторинга
• Операторы в реальном времени — статус и нагрузка операторов
• Оценки (CSAT) — сессии с оценкой клиента за период

Идентификаторы

Действия над диалогом выполняются от имени сотрудника, к которому привязан ключ. Параметра «сотрудник» у них нет — подробности в разделе Действия оператора и своя пауза.

Статистика (дашборд)

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

Шесть методов только читают данные: сводные показатели линии, операторы в реальном времени, сессии с фильтрами, метрики выбранных сессий, оценки клиентов и история переназначений. Данные видны в пределах прав сотрудника, к которому привязан ключ. Если у него нет доступа ни к одной линии, метод возвращает пустой список или нулевые показатели, а не ошибку. Методам нужно право на статистику Открытых линий report_open_lines, без него запрос вернёт 403 B24_TARIFF_RESTRICTION.

Остальные методы раздела работают на любом портале. Исключение — История сессии: её платформа Вайбкод включает постепенно, и до включения вызов отвечает 403 OPENLINES_HISTORY_DISABLED. Права report_open_lines и обновления imopenlines 26.700.0 история сессии не требует.

Типичные сценарии

Рекомендации

• Сводные показатели берите из POST /v1/openlines/stats — он считает показатели на стороне Битрикс24. Сбор тех же цифр перебором страниц POST /v1/openlines/sessions/search расходует лимит запросов.
• Частота опроса сводных показателей и операторов в реальном времени указана на страницах Агрегаты по линии за период и Операторы в реальном времени.

Быстрый старт

Получите ID линии и сводные показатели этой линии за период.

1. Найдите линию

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/openline-configs"

В ответе data — массив линий портала. Поле data[].id — ID линии, data[].name — её название.

2. Запросите сводные показатели линии

curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/stats" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-09-01T00:00:00+03:00",
    "dateTo": "2026-09-30T23:59:59+03:00",
    "configId": 3
  }'

Ответ:

{
  "success": true,
  "data": {
    "totalSessions": 3,
    "closedSessions": 2,
    "spamSessions": 0,
    "avgWaitAnswer": 25,
    "avgSessionDuration": 17.3333,
    "likeCount": 0,
    "dislikeCount": 0,
    "votedSessions": 0,
    "positiveRate": 0,
    "kpiFirstAnswerOk": 0,
    "kpiFirstAnswerFail": 0,
    "sessionsBySource": [{ "source": "livechat", "count": 2 }, { "source": "telegrambot", "count": 1 }],
    "sessionsByHour": [1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0],
    "sessionsByOperator": [{ "operatorId": 42, "count": 2, "avgWaitAnswer": 25, "positiveRate": 0 }]
  }
}

Поля ответа — на странице Агрегаты по линии за период.

Полный пример

Отчёт по обращениям линии за период: сводные показатели, сессии с привязкой к CRM, их метрики и все диалоги карточки CRM первой сессии. Все вызовы только читают данные.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Линии портала: берём ID первой линии
const lines = await api('GET', '/openline-configs')
const configId = lines.data[0].id
console.log('Линия:', configId)

// 2. Сводные показатели линии за период
const period = { dateFrom: '2026-10-01T00:00:00+03:00', dateTo: '2026-10-19T23:59:59+03:00' }
const stats = await api('POST', '/openlines/stats', { ...period, configId })
console.log('Обращений:', stats.data.totalSessions, 'закрыто:', stats.data.closedSessions)

// 3. Сессии того же периода с привязкой к CRM
const found = await api('POST', '/openlines/sessions/search', {
  configId,
  dateCreateFrom: period.dateFrom,
  dateCreateTo: period.dateTo,
  hasCrm: 'Y',
  limit: 50,
})
const sessions = found.data.sessions
console.log('Сессий на странице:', sessions.length, 'есть ещё:', found.data.hasNextPage)

if (sessions.length > 0) {
  // 4. Метрики найденных сессий, до 100 за вызов
  const metrics = await api('POST', '/openlines/sessions/stats', {
    sessionId: sessions.map((s) => s.id),
  })
  for (const m of metrics.data.sessions) console.log('Сессия', m.sessionId, 'сообщений:', m.messagesCount)

  // 5. Все диалоги карточки CRM, к которой привязана первая сессия
  const { crmEntityType, crmEntityId } = sessions[0]
  const chats = await api('GET', `/openlines/crm/chats?crmEntityType=${crmEntityType}&crmEntityId=${crmEntityId}&activeOnly=false`)
  for (const c of chats.data) console.log('Чат', c.chatId, 'канал:', c.connectorTitle)
}

Как получить следующие страницы сессий — в абзаце «Пагинация» на странице Поиск сессий. Найденный на шаге 5 chatId принимают перехват диалога, вход в диалог и сообщение клиенту.

Справочник эндпоинтов

Все 39 эндпоинтов раздела:

Приём и завершение диалога оператором описаны на странице Конфигурации открытых линий. Шесть методов статистики выходят в обновлении imopenlines 26.700.0, см. Статистика (дашборд). У GET /v1/openline-configs/fields вызова Битрикс24 нет — схему полей отдаёт Вайбкод.

Коды ошибок

Ошибки Открытых линий

При отказе Битрикс24 ответ приходит как 422 BITRIX_ERROR, а код Битрикс24 дублируется в поле error.b24Code:

Коды конкретного метода — в таблице ## Ошибки на его странице.

Системные ошибки

Общие коды (SCOPE_DENIED, TOKEN_MISSING, WRITE_BLOCKED_READONLY_KEY, RATE_LIMITED и другие) — на странице Ошибки API.

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

• Бот в открытой линии
• Чаты и сообщения
• Журнал изменений API