Настройка синхронизации календарей с Битрикс24
Синхронизация календарей с Битрикс24 подключается двумя вебхуками портала: входящий даёт UnSpot доступ к календарям, исходящий сообщает об изменениях событий. Ниже — весь порядок настройки: что создать в Битрикс24, что вставить в UnSpot и как проверить, что обмен пошёл в обе стороны. Подключение выполняют роли «Владелец» и «Администратор интеграций». Карточка Bitrix24 есть только в российском контуре UnSpot.
Что понадобится
| Требование | Подробности |
|---|---|
| Роль в UnSpot | «Владелец» или «Администратор интеграций» |
| Права в Битрикс24 | Доступ в раздел для разработчиков и право создавать вебхуки. Входящий вебхук создаётся от учётной записи с административными правами: создавая встречу, UnSpot ищет её участников среди всех пользователей портала в режиме администратора |
| Календари-локации в Битрикс24 | Переговорные в портале должны быть оформлены календарями типа «локация». Обычные и личные календари для связи с переговорными не подходят |
| Доступность портала | Портал отвечает по HTTPS и доступен из сети, где работает UnSpot. Это касается и облачного Битрикс24, и Битрикса на своём сервере |
Учтите заранее: организатором всех встреч в портале станет пользователь, от имени которого создан входящий вебхук. Выберите учётную запись, которую допустимо показывать организатором.
Шаг 1. Входящий вебхук в Битрикс24
В Битрикс24 откройте раздел «Разработчикам» и выберите карточку «Другое».
Выберите «Входящий вебхук».
В открывшейся форме заполните две вещи: метод в «Генераторе запросов» и «Настройку прав».
- Метод — calendar.event.get. Метод в генераторе запросов ни на что не влияет: доступ определяют только галочки прав, а UnSpot вызывает свой набор методов (список ниже).
- Права — «Календарь», «Пользователи», «Пользователи (минимальный)», «Пользователи (базовый)», «Мобильный календарь», «Пользовательские поля пользователей». Это набор, проверенный на практике; обязательны из него два — «Календарь» и «Пользователи», остальные выданы с запасом.
На кадре адрес вебхука и адрес запроса скрыты: это секрет, дающий доступ к данным портала.
Скопируйте адрес из поля «Вебхук для вызова rest api» — он понадобится в UnSpot — и сохраните вебхук. Адрес выглядит так: https://my-company.bitrix24.ru/rest/1/xxxxxxxxxx/ — домен портала, идентификатор пользователя и токен.
Адрес вебхука — это секрет. Он позволяет выполнять действия в портале в пределах выданных прав; не пересылайте его в открытых каналах и не публикуйте в переписке с несколькими адресатами.
Что UnSpot делает в портале этим вебхуком
Вопрос, который обычно задаёт служба безопасности при согласовании прав. Интеграция не только читает календари: она создаёт, изменяет и удаляет события в тех календарях-локациях, которые связаны с переговорными UnSpot.
| Что вызывает UnSpot | Зачем |
|---|---|
| user.current | Проверка вебхука при подключении и получение почты его владельца |
| calendar.section.get | Список календарей-локаций для привязки к переговорным |
| calendar.event.get, calendar.event.getbyid | Чтение событий: регулярная сверка и обработка вебхука |
| calendar.event.add, calendar.event.update, calendar.event.delete | Создание, изменение и удаление встреч по бронированиям UnSpot |
| user.search | Поиск участников встречи по адресу электронной почты |
Других методов интеграция не использует.
Шаг 2. Подключение портала в UnSpot
Откройте Настройка → Интеграции → Синхронизации и пролистайте страницу до блока «Синхронизация календарей».
В карточке Bitrix24 нажмите «Подключить», вставьте скопированный адрес в поле «Введите URL входящего webhook из Bitrix» и нажмите «Подключить».
Что UnSpot делает со вставленной ссылкой:
| Проверка | Подробности |
|---|---|
| Схема адреса | Если вставить адрес без https://, схема подставится автоматически. Обращения к порталу всегда идут по HTTPS |
| Путь | Обязателен вид /rest/<id>/<токен>. Завершающий слэш и лишние сегменты после токена допускаются |
| Что берётся из ссылки | Только домен портала, идентификатор пользователя и токен. Порт, параметры и якорь отбрасываются — поэтому Битрикс на своём сервере должен быть доступен на стандартном 443-м порту |
| Длина поля | До 255 символов. Формат идентификатора и токена на этом шаге не проверяется — ошибку в них покажет уже портал |
| Проверка на стороне портала | UnSpot обращается к вебхуку и убеждается, что он отвечает и что у пользователя вебхука заполнен адрес электронной почты |
Подтверждение подключения — не сообщение, а сама карточка: окно закроется, и в карточке Bitrix24 вместо кнопки «Подключить» появится домен портала, рядом — кнопка «Отключить».
Шаг 3. Исходящий вебхук в Битрикс24
Без этого шага события, созданные в портале, будут попадать в UnSpot только с регулярной сверкой, то есть с задержкой. Вернитесь в «Разработчикам» → «Другое» и выберите «Исходящий вебхук».
Заполните форму:
- «URL вашего обработчика» — адрес вида https://<адрес вашего рабочего пространства UnSpot>/api/bitrix24/webhook/incoming.
- «Токен приложения» — Битрикс24 задаёт его сам. UnSpot этот токен не использует, менять его не нужно.
- «События» — «Добавление события календаря», «Изменение события календаря», «Удаление события календаря». Нужны все три.
На кадре адрес обработчика и токен скрыты — в вашей форме там будет адрес вашего рабочего пространства.
Сохраните вебхук.
Шаг 4. Проверка
Портал подключён, но события ещё не ходят: осталось связать переговорные с календарями-локациями — это делается отдельно для каждой комнаты, порядок описан в статье «Подключение календаря Битрикс24 к переговорной».
После привязки хотя бы одной переговорной проверьте обмен в обе стороны:
- Забронируйте эту переговорную в UnSpot и убедитесь, что встреча появилась в календаре портала.
- Создайте событие в том же календаре Битрикс24 и убедитесь, что в UnSpot появилось бронирование.
Если первая проверка прошла, а вторая нет — проверьте три вещи: адрес обработчика в исходящем вебхуке, набор событий в нём и то, что событие вы создали именно в том календаре-локации, который связан с переговорной. События из других календарей UnSpot игнорирует.
Ошибки при подключении
| Сообщение | Что произошло и что делать |
|---|---|
| Введите корректный URL. Пример: https://my-company.bitrix24.ru/rest/1/xxxxxxxxxx/ | Ссылка не похожа на адрес входящего вебхука: нет части /rest/, идентификатора пользователя или токена. Скопируйте адрес из карточки вебхука целиком |
| Не удалось подключиться к Bitrix24. Проверьте URL и права доступа. | Портал не ответил, вебхук отозван, у него нет прав на раздел «Пользователи» или у пользователя вебхука не заполнена почта. При подключении UnSpot делает один вызов — user.current, — поэтому права на календарь на этом шаге не проверяются: их нехватка проявится позже, при выборе календаря для переговорной |
| Не удалось подключить Bitrix24. Подключение уже существует. | К этому рабочему пространству UnSpot уже подключён портал. Сначала отключите прежнее подключение |
Отключение
Кнопка «Отключить» в карточке Bitrix24 разрывает подключение целиком и снимает привязки календарей у всех переговорных сразу. Три следствия, о которых стоит помнить:
- События, ранее созданные UnSpot, остаются в Битрикс24 — портал при отключении не изменяется.
- Исходящий вебхук в Битрикс24 продолжает работать; отключите его в портале вручную.
- Чтобы вернуть синхронизацию, портал подключают заново и связывают календари с переговорными повторно.
- Бронирования в UnSpot остаются, в том числе созданные из событий портала, — они просто перестают синхронизироваться.
