История изменений

Что менялось в публичном API.

Как мы меняем API

Добавления не ломают ничего и выходят без предупреждения. Новое поле в ответе, новый необязательный параметр, новый метод, новое событие вебхука — всё это может появиться в любой момент. Ваш код должен спокойно относиться к незнакомым полям в ответе.

Ломающие изменения означают новую версию — /v2/. Старая версия проживёт не меньше шести месяцев после выхода новой, и мы предупредим заранее.

Что мы считаем ломающим изменением: удаление или переименование поля, метода, кода ошибки, области доступа или события вебхука; новое обязательное поле в запросе; изменение типа поля.

v1.5.0 — 14 октября 2026

Только добавления. Всё, что раньше работало, работает так же.

• Написать клиенту первым — POST /v1/conversations: новый диалог с существующим контактом и первое сообщение в выбранном канале (по умолчанию — где клиент был активен последним). Каналы, которые не умеют начинать разговор, отказывают так же, как в кабинете. Новая область conversations:start.
• Звонки: у карточки звонка в /messages появился объект call — длительность, записи (ссылки живут 10 минут), сводка, а расшифровка — с ?include=transcript. Только для ключей с новой областью calls:read. Позвонить клиенту — POST /v1/conversations/{id}/calls, область calls:make: звонит телефон указанного сотрудника (operator_id), потом клиента. Звонить можно только на номера из карточки контакта — новый номер сначала добавьте в контакт.
• Оценка качества диалога — GET и PUT /v1/conversations/{id}/quality, области quality:read и quality:write. Оценка ключа подписана «API · <ключ>».
• Видеовстреча в диалоге — POST /v1/conversations/{id}/meetings: встреча с ведущим operator_id и ссылка клиенту. Область meetings:write.
• Дополнительные поля контакта: attributes в POST и PATCH /v1/contacts по тем же правилам, что и виджет: неизвестное поле сохраняется и видно в карточке в блоке «Другое», значение не того типа отбрасывается, длинное обрезается — и обо всём этом сообщает поле ответа attribute_warnings. Схема полей — GET /v1/contacts/attributes.
• Заметки на карточке контакта — GET (новая область notes:read) и POST /v1/contacts/{id}/notes (notes:write). Заметка ключа подписана «API · <ключ>».
• Готовые ответы — GET /v1/macros и GET /v1/macros/{id} (macros:read), POST и PATCH (macros:write). Список — страницами, новые сверху, поиск q по названию и сокращению. Только общие ответы команды; личные шаблоны сотрудников ключу не видны.
• Теги — POST /v1/tags и PATCH /v1/tags/{id}, область tags:write.
• Справка: ключ с kb:write читает черновики и архив (?status=draft|archived|all); загрузка картинок и видео для статей — POST /v1/kb/media; AI-перевод статьи — POST /v1/kb/articles/{id}/translate, отдельная область kb:translate, потому что тратит токены компании; язык, переведённый ИИ после последней правки оригинала, пропускается (up_to_date).
• `GET /v1/me`: часовой пояс, язык и рабочие часы проекта, и acts_as — от чьего имени действует ключ.
• Ключ от имени сотрудника. В «Настройки → API» у ключа есть пункт «Действует от имени»: без автора (интеграция, как раньше) или сотрудник. Ключ с автором действует его правами и видимостью, всё, что он делает, подписано «Мария Иванова · API · <ключ>», а operator_id по умолчанию — автор. Если автора отключили, ключ отвечает 403 key_author_inactive.
• Если у клиента уже открыт диалог в этом канале, а сотрудник, от чьего имени действует ключ, его не видит, POST /v1/conversations отвечает 409 и ничего не отправляет.
• Ключи, у которых уже была область kb:write, теперь также читают черновики и загружают картинки для статей. Область macros:write помечена как чувствительная.
• Заметки о компании клиента — GET и POST /v1/organizations/{id}/notes; писать может только ключ с автором (иначе 409 author_required).
• Изменённые и удалённые ответы: у сообщений в /messages и в вебхуках message.* появились поля edited_at и deleted_at. Сотрудник может исправить или удалить свой ответ у клиента; удалённый ответ остаётся в списке с deleted_at — клиент его больше не видит, body хранит отправленный текст.
• MCP: новые инструменты start_conversation (написать клиенту первым — только через подтверждение человеком, как ответ) и list_macros (готовые ответы). add_note пишет и на карточку контакта, update_contact — дополнительные поля, теги, компании клиентов, search_knowledge_base — черновики.

v1.4.2 — 27 сентября 2026

Только добавления.

• Оценки клиентов (шаг сценария «Оценка оператора»): analytics/quality.customer_ratings — sent, responded, response_rate, avg_score, distribution, by_channel; analytics/operators строки — customer_score и customer_ratings (засчитывается оператору, о котором спрашивали); analytics/overview.kpis — customer_score и customer_ratings. Отдельно от AI-оценки.
• `analytics/quality`: новые поля closed (диалоги, закрытые в периоде —

знаменатель покрытия: evaluated ÷ closed), reasons (причины низких оценок, по убыванию), detail_scored (сколько уверенных оценок несут детали); у by_operator — auto_fails и criteria (средние 1–5 по пяти критериям, null без деталей); у by_week — days (дней в неделе: 7 или меньше у короткой последней).

• `analytics/revenue`: сохранение настройки «Финансы» теперь сразу

перечитывает статус всех сохранённых сделок компании; выигранная сделка, которую CRM позже перевела в проигрыш (возврат), уходит из выручки в течение 90 дней после победы. Дата победы из Битрикс24 берётся из CLOSEDATE только когда это прошедший момент (плановая дата в будущем не считается).

• Отчёты overview / channels / teams считаются в базе данных, а не в

памяти сервера: те же цифры, быстрее на больших периодах.

v1.4.1 — 24 сентября 2026

Исправления в отчётах аналитики. Поля и методы прежние, меняются цифры — теперь верные.

• `analytics/operators`: handled — диалоги, где оператор хотя бы раз

ответил клиенту за период (раньше — диалоги, которые сейчас на нём). closed — диалоги, которые он закрыл сам. avg_resolution_seconds — время жизни закрытых им диалогов. resolved_share — доля диалогов из handled, закрытых сейчас. Фильтр operator выбирает строки операторов.

• `analytics/revenue`: одна сделка засчитывается один раз — ближайшему

диалогу (сделка создана не раньше чем за 7 дней до начала и не позже чем через 30 дней после закрытия диалога). Новое поле currency: by_channel, by_operator и per_day — только в этой валюте, другие валюты в них больше не складываются. Выручка оператора — тому, кто закрыл диалог.

• `analytics/overview`: ai_quality теперь заполнено — средняя оценка, как

в отчёте «Качество».

• `analytics/revenue`: новое поле cohort_won_count — выигранные сделки по

диалогам, закрытым в периоде (одна когорта с open_count и lost_count); won_count по-прежнему по дате признания.

• `analytics/bot`: autonomous_share теперь считается (решено самим

агентом ÷ взял агент); пока исходов нет — null с причиной no_outcomes_yet (прежняя draft_mode_only больше не возвращается).

• Явный период длиннее 366 дней обрезается до 366 (как и days).
• Спам не считается ни в одном отчёте.
• `analytics/overview`: resolved и resolved_share — из диалогов,

начатых в периоде, сколько закрыто сейчас; больше 100 % не бывает. Внутренние заметки больше не считаются первым ответом.

• Период: даты без времени (2026-09-01) читаются как полночь по поясу

компании. Даты со временем — как раньше, как есть.

• Ключ с видимостью «только мои» и фильтры по оператору и команде в отчётах

«Операторы», «Команды» и «Качество» теперь действительно ограничивают выдачу.

v1.4.0 — 13 сентября 2026

Подключение ассистента стало проще. Старые подключения продолжают работать.

• Ключ для подключения больше не нужен. Вы входите под собой, и ассистент

действует вашими правами — включая ограничение видимости диалогов, если оно у вас есть. Раньше сначала требовалось завести ключ и расставить тринадцать галочек.

• Права подключения — переключатель «Чтение» / «Чтение и запись». Меняется в

кабинете, без переподключения.

• Ключ остался для одного случая: дать ассистенту меньше, чем есть у вас.

На экране согласия это свёрнутая строка.

• Адрес один. /mcp/readonly продолжает работать у тех, кто уже его вставил,

но из кабинета убран: переключатель делает то же самое понятнее.

v1.3.0 — 13 сентября 2026

Свой MCP-сервер. Дополнение: в REST-части не изменилось ничего.

• Два адреса: /mcp — всё, что разрешает ключ, и /mcp/readonly — только

чтение, где ни одно действие недоступно даже ключу, который их разрешает.

• 19 инструментов, собранных как задачи целиком, а не как методы API. Список,

который видит программа, собирается под конкретный ключ: чего ключ не разрешает, того в списке нет.

• Вход через OAuth 2.1 с PKCE — программа сама регистрируется, человек в

кабинете выбирает ключ и подтверждает. Обычный ключ API в заголовке тоже работает, без экрана согласия.

• Ответ клиенту не отправляется сразу: инструмент возвращает ссылку, по

которой человек видит точный текст и нажимает «Отправить». Проверка на нашей стороне, обойти её нельзя.

• Текст, написанный клиентом, приходит модели помеченным как чужой.
• Подключённые программы видны в Настройках → API, отключаются одной кнопкой.

Подробности — в руководстве «Подключение ассистента (MCP)».

v1.2.0 — 13 сентября 2026

Запись в справку и встречи. Дополнение: ничего существующего не изменилось.

• Область доступа kb:write — создание и правка статей и категорий. Тело

статьи принимается в Markdown. Удаления нет и права на него у ключа нет: убрать опубликованное может только человек в кабинете.

• Новая статья создаётся черновиком. Публикация — отдельным параметром, и она

же кладёт статью в поиск ИИ-оператора.

• Область доступа conferences:read — встречи со сводками, решениями и

расшифровками. Требует и права на встречи, и права на расшифровки.

• Два события вебхука: conference.ended (разговор закончился — всегда) и

conference.transcript_ready (расшифровка и сводка готовы — только там, где была запись).

Подробности — в руководствах «Запись в справку» и «Встречи».

v1.1.0 — 13 сентября 2026

Аналитика. Дополнение: ничего существующего не изменилось и не удалено.

• Новая область доступа analytics:read. Она включает и денежные отчёты,

поэтому создать такой ключ может только сотрудник, у которого есть права и на аналитику, и на выручку, и который видит все диалоги.

• Семь отчётов: сводка, каналы, команды, сотрудники, выручка, качество диалогов

и работа ИИ-оператора. Плюс filters — допустимые значения фильтров.

• У всех отчётов одинаковые параметры: период from/to и фильтры по каналам,

командам и сотрудникам. Период — не длиннее 366 дней.

• Курсора в отчётах нет: отчёт это готовый ответ целиком, а не страница списка.

Подробности — в руководстве «Аналитика».

v1.0.0 — 12 сентября 2026

Первая версия.

• Ключи проекта с правами вида ресурс:действие.
• Чтение: диалоги, сообщения, контакты, компании клиентов, теги, сотрудники, команды, справка.
• Изменение: статус и назначение диалога, теги, ответ клиенту и внутренняя заметка, создание и правка контактов и компаний.
• Вебхуки: восемь событий, подпись HMAC-SHA256, повторы, журнал отправок за 7 дней.
• Постраничная выдача курсором, единый формат ошибок с номером запроса, Idempotency-Key, лимиты запросов с заголовками.