Навык «Битрикс24»

Навык подключает Искру к вашему порталу Битрикс24: поиск лидов, сделок, контактов и компаний, сводка по воронке продаж, таймлайн и дела CRM, задачи Битрикс24. По умолчанию создание и изменение записей требуют подтверждения черновика; предварительное разрешение для вашего профиля задаётся в настройках подтверждения. Подключение — через входящий вебхук вашего портала, без пароля и без OAuth-приложения.

Подключение

На портале Битрикс24 (из-под администратора): Разработчикам → Другое → Входящий вебхук → выбрать права crm, user, task → создать. Битрикс покажет код вебхука один раз — сразу скопируйте его или весь URL вебхука.
В Искре: Витрина навыков → «Битрикс24» → добавить в организацию (или личный профиль) → на карточке навыка нажмите «Требует настройки» (позже те же поля открывает страница навыка → вкладка «Настройки»). Откроется окно «Настройки навыка»; если вам доступны оба варианта — личный профиль и организация, — выберите нужный в строке «Кому доступно» вверху окна: «Только мне» или «Всей организации». Ниже — группа настроек «Подключение к Битрикс24»:
- Адрес портала — например mycompany.bitrix24.ru (или адрес коробочной установки/CNAME-домена клиента, если он доступен по HTTPS из интернета);
- Входящий вебхук — можно вставить и короткий код вида 1/abc123xyz (часть URL после /rest/), и полный URL вебхука целиком; поле write-only, как и обычные ключи — посмотреть сохранённое значение нельзя, только заменить.
Для организации подключение заполняет владелец или администратор один раз — работать смогут все сотрудники. Личное подключение (если заполнено) полностью замещает организационное — при выборе личного поверх уже настроенного подключения организации Искра предупредит об этом; рядом с группой видно, какое сейчас действует. Подробнее о выборе, куда настраивать — в «Навыки» → «Группы настроек (подключения)».

На странице навыка, на вкладке «Содержимое» в группе «Знания», есть «Карта знаний» — накопленные знания о кастомных полях и стадиях воронок вашего портала. Искра пополняет её по ходу работы; построить или обновить карту можно кнопкой «Исследовать» / «Обновить карту». Подробнее — в «Навыки» → «Карта знаний подключения».

Кто вы в Битрикс24

При первом действии, которое требует авторства (создание лида, задачи и т. п.), навык спросит, кто вы. В форме одно поле выбора с поиском по всем активным сотрудникам портала: начните вводить имя, фамилию или их часть — под полем останется не больше семи подходящих сотрудников, выберите себя. У полных тёзок — в том числе различающихся только регистром букв, «ё»/«е» или знаками — к имени добавлен номер сотрудника вида #1499, по нему их можно различить. Отправить можно только сотрудника из списка, произвольный текст значением не становится.

Выбор запоминается: дальнейшие записи выполняются от вашего имени без повторного вопроса о личности. Для задач он задаёт начальные значения исполнителя и постановщика. При включённом «Спрашивать каждый раз» обе роли можно проверить и изменить в черновике; при предварительном разрешении заполненная задача может создаться сразу. Выбор личности не расширяет права вебхука. Уволенные сотрудники и пользователи экстранета в список не попадают.

Что умеет

Чтение:

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

Запись по умолчанию требует подтверждения черновика. Если в настройках этого навыка вы выключили «Спрашивать каждый раз», полностью заполненное действие может выполниться без нового подтверждения. Недостающие данные Искра всё равно предложит заполнить. Доступны действия:

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

Выгрузка сделок стадии

Например: «Выгрузи все сделки стадии „Сделка успешна“ воронки „Исполнение отделка“ и подготовь дашборд». Искра определит воронку и стадию, затем прочитает сделки страницами по 50 записей. Названия конкретных сделок для такой выгрузки не требуются. При совпадающих названиях воронок или стадий нужно уточнить выбор.

Для отчёта доступны идентификаторы и названия сделок, суммы и валюты, ответственные, даты создания, изменения и закрытия, связанные контакт и компания. Дополнительные поля отдельной сделки можно получить из её карточки. Суммы в разных валютах показываются отдельно.

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

Формы подтверждения

По умолчанию перед записью в Битрикс24 появляется черновик — название, поля, ответственный. Проверьте или поправьте значения и подтвердите действие. Если в настройках этого навыка вы выключили «Спрашивать каждый раз», полностью заполненное действие может выполниться без нового подтверждения. Недостающие данные Искра всё равно предложит заполнить. Когда форма показана, значения можно изменить перед отправкой. Поле «Ответственный» с поиском заполнено вами; если выбрать другого сотрудника, запись выполнится от его имени и этот выбор запомнится как ваша привязка.

Для задачи та же форма подтверждения содержит два независимых поля с поиском — «Исполнитель» и «Постановщик задачи». Оба заполнены заранее и меняются прямо в черновике; выбор в них не меняет запомненную привязку «Кто вы». После подтверждения или при предварительном разрешении создаётся ровно одна задача с выбранными ролями. После создания навык повторно читает задачу в Битрикс24 и сообщает, если портал сохранил другие роли или не дал их проверить. Сама задача при этом уже создана — повторять команду не нужно.

Комплектные сценарии

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

Подключить Битрикс24 — настройка входящего вебхука и проверка подключения;
Утренняя сводка по продажам — состояние воронки, суммы по стадиям, ближайшие дела и задачи;
Квалификация нового обращения — проверка дублей по телефону/email и создание лида или сделки с контактом;
Подготовка к встрече по сделке — карточка сделки, история общения, открытые дела и контакты одним брифом;
Разбор зависших сделок — сводка по воронке, комментарий и следующий шаг по сделкам без движения;
Выгрузка сделок стадии — список сделок выбранной стадии для отчёта или дашборда, включая выигранные;
Итоги звонка в CRM — комментарий в таймлайн, следующее дело и, если прозвучало продвижение, смена стадии.

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

Ограничения

REST API Битрикс24 доступен только на коммерческих тарифах портала — на бесплатном тарифе навык подключиться не сможет.
Битрикс24 ограничивает частоту запросов к REST API; при кратковременном всплеске навык сам повторяет один раз, при более строгом лимите — ответит «попробуйте позже».
Сводка по воронке охватывает до 1000 открытых сделок; если сделок больше, ответ явно помечает неполный охват.
Команда получения списка сотрудников показывает Искре не более 250 записей. Выбор человека в форме работает по всем активным сотрудникам портала — до 2000. Если активных сотрудников больше 2000, навык сообщит, что выбор в форме для такого портала не поддерживается.
Выгрузка выбранной стадии идёт страницами по 50 сделок; лимит сводки в 1000 открытых сделок к ней не относится. Частично прочитанный список при остановке или ошибке остаётся неполным.
Коробочные установки Битрикс24 без публичного DNS-имени или с адресом только во внутренней сети (приватный IP) навык подключить не может: он обращается к порталу по HTTPS через сетевую политику платформы, которая не пропускает внутренние адреса ни при каких настройках.

Типичные ошибки

Ошибка	Что означает	Что делать
`webhook_invalid`	Вебхук удалён на портале или код указан неверно	Пересоздать входящий вебхук на портале и обновить настройки навыка
`missing_scope`	У вебхука не хватает прав для вызванного метода	В настройках вебхука на портале добавить недостающее право доступа (crm, user, task)
`plan_required`	REST API недоступен на текущем тарифе портала	Перейти на коммерческий тариф Битрикс24
`not_configured`	Навык не подключён	Заполнить группу «Подключение к Битрикс24» в настройках навыка
`rate_limited`	Битрикс24 ограничил частоту запросов	Повторить действие через некоторое время

Безопасность

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