Синхронизация календарей с Битрикс24: как устроена
Синхронизация с Битрикс24 связывает переговорные UnSpot с календарями-локациями портала: встреча, созданная в UnSpot, появляется в Битрикс24, а событие, созданное в портале, превращается в бронирование UnSpot. Статья описывает, как этот обмен устроен — из чего складывается подключение, в какую сторону и когда передаются события, что синхронизация не умеет и что остаётся в портале после отключения. Пошаговая настройка — в отдельных статьях, ссылки в конце.
Что синхронизируется
Обмен идёт только по календарям-локациям Битрикс24 — тем, которые портал использует для помещений и ресурсов. Один такой календарь связывается с одной переговорной UnSpot.
| Объект | Синхронизируется |
|---|---|
| Календарь-локация портала ↔ переговорная UnSpot | Да, это основа интеграции |
| Личный календарь сотрудника в Битрикс24 | Нет. Подключить его к своему профилю UnSpot нельзя — механизм подписки на изменения для Битрикс24 не реализован |
| Календарь группы или компании в Битрикс24 | Нет, в списке доступных для привязки такие календари не появляются |
| Бронирования столов, парковок, локеров | Нет, интеграция работает только с переговорными |
Из чего состоит подключение
Работающая синхронизация — это три отдельные настройки. Пропущенная третья — самая частая причина «в Битрикс24 события появляются, а обратно не приходят».
| Настройка | Где создаётся | За что отвечает |
|---|---|---|
| Входящий вебхук | Битрикс24, раздел для разработчиков | Даёт UnSpot право читать календари портала и создавать в них события. Его адрес вставляется в UnSpot |
| Подключение портала | UnSpot, «Настройка → Интеграции → Синхронизации», блок «Синхронизация календарей» | Сохраняет адрес вебхука и проверяет, что портал отвечает |
| Исходящий вебхук | Битрикс24, тот же раздел для разработчиков | Сообщает UnSpot о добавлении, изменении и удалении событий календаря. Без него обратная передача работает только на регулярной сверке, с задержкой |
Отдельным, четвёртым шагом каждая переговорная связывается со своим календарём-локацией — по одной привязке на комнату.
Токен, который Битрикс24 генерирует для исходящего вебхука, UnSpot не использует — задавать его где-либо в UnSpot не нужно.
Из UnSpot в Битрикс24
Когда сотрудник бронирует переговорную в UnSpot, система создаёт в связанном календаре-локации событие. Изменение брони обновляет это событие, удаление — удаляет.
Организатором события в портале становится пользователь, от имени которого создан входящий вебхук, а не сотрудник, забронировавший переговорную. Автор брони попадает в участники встречи — и только если его почта совпадает с почтой пользователя Битрикс24. Практический вывод: вебхук стоит создавать от учётной записи, которую не стыдно показывать организатором всех встреч.
Что ещё стоит знать про эту сторону обмена:
- Участник без совпадающей почты просто не попадёт в список. Ошибки при этом не будет: событие создастся, а часть приглашённых в портале не увидит никто.
- Приватная бронь создаётся приватным событием портала, обычная — обычным.
- Ссылка на видеовстречу и комментарий переносятся в описание события — но только при создании. При последующих изменениях брони описание в портале не обновляется: исправленный комментарий останется только в UnSpot.
- Повторяющаяся бронь передаётся правилом повторения. При изменении правится только тот экземпляр, который изменили: изменить в портале сразу всю серию из UnSpot нельзя.
- Время и таймзона. В портал уходит абсолютное время встречи плюс таймзона офиса, к которому относится переговорная (если у офиса она не задана — таймзона компании). Разница таймзон офиса и портала время встречи не сдвигает.
- Смена переговорной в брони создаёт новое событие в календаре новой комнаты, но не убирает старое: в портале остаётся встреча в прежней переговорной. Её удаляют вручную.
Из Битрикс24 в UnSpot
Событие, созданное в календаре-локации портала, приходит в UnSpot двумя путями.
- Сразу — по исходящему вебхуку. Портал сообщает UnSpot идентификатор изменённого события, UnSpot забирает его подробности и создаёт, обновляет или удаляет соответствующее бронирование.
- С задержкой — регулярной сверкой. Она подхватывает всё, что не дошло вебхуком.
Для повторяющихся событий UnSpot дополнительно запрашивает у портала родительское событие серии: в отдельном экземпляре Битрикс24 не возвращает ни список участников, ни признак приватности — эти данные берутся из родителя.
Событие из календаря, который не связан ни с одной переговорной, UnSpot игнорирует — это нормально и не требует настройки.
Что не переносится в обратную сторону. В бронировании UnSpot появляется только организатор встречи — состав участников из портала в бронь не попадает. Сам организатор определится, если автор события есть среди его участников и его адрес почты совпадает с адресом пользователя UnSpot; иначе бронь останется без организатора.
Регулярная сверка
Помимо мгновенной передачи по вебхуку UnSpot периодически сверяет связанные календари целиком: забирает события за период от вчерашнего дня до 182 дней вперёд и приводит бронирования в соответствие с порталом.
Сверка — не только страховка на случай потерянного вебхука. У неё есть последствия, о которых стоит знать: бронирование, событие которого исчезло из Битрикс24, будет удалено и в UnSpot. Не удаляются только уже завершившиеся встречи — идущая в этот момент бронь тоже исчезнет, и уведомление организатору при этом не отправляется. Завершившиеся брони остаются в истории и аналитике.
Дополнительно сверка запускается:
- сразу после того, как календарь связали с переговорной;
- по кнопке «Запустить синхронизацию» в карточке переговорной — не чаще одного раза в час для одной комнаты. Пока час не истёк, кнопка заблокирована, а рядом с ней указано время, когда она снова станет доступна. Отсчёт начинается и от момента подключения календаря, поэтому в первый час после привязки кнопки нет;
- автоматически, когда UnSpot замечает расхождение между бронью и событием.
Кто главный при конфликте
Одну и ту же переговорную можно занять с двух сторон, и правила разрешения спора несимметричны: в спорной ситуации побеждает портал. Три сценария, с которыми сталкиваются чаще всего.
1. Время уже занято в портале — бронь отменяется. Если в связанном календаре есть встреча, пересекающаяся с новой бронью, UnSpot удаляет бронирование сразу после создания и присылает организатору уведомление об отмене. Для сотрудника это выглядит так: бронь создалась и через несколько секунд исчезла. Причина — занятое время в Битрикс24, которого в UnSpot не видно, пока сверка не принесёт это событие.
2. Событие из портала вытесняет брони UnSpot. Когда встреча создана в календаре портала, UnSpot заводит по ней бронирование, а конфликтующие бронирования этой переговорной удаляет. Уведомления об этом не отправляются — организатор просто не найдёт свою бронь. Если переговорную бронируют и там и там, порядок такой: портал главнее.
3. Остановленная бронь возвращается. Кнопка «Освободить» завершает бронь в UnSpot, но событие в портале остаётся нетронутым — и ближайшая сверка создаст по нему новую бронь на исходный интервал. То есть раннее освобождение переговорной не сохраняется. Чтобы освободить помещение и в UnSpot, и в портале, бронь нужно удалить, а не останавливать.
| Симптом | Что произошло |
|---|---|
| Бронь исчезла сразу после создания, пришло уведомление об отмене | В календаре портала это время уже занято |
| Бронь пропала без уведомления | В портале появилось событие, пересекающееся с ней |
| Освободили переговорную раньше времени, а через час она снова занята | Событие в портале осталось, сверка вернула бронь |
| Встреча в портале есть, а брони в UnSpot нет | Календарь не связан с переговорной, либо событие вне окна сверки и вебхук не дошёл |
Если синхронизация перестала работать
Когда портал отказывает в доступе — вебхук отозвали, у него убрали права — UnSpot помечает подключение недействительным. Признак общий для всех переговорных, и увидеть его можно только в карточке комнаты: вместо кнопки «Запустить синхронизацию» там появляется «Переподключить». В блоке интеграций признака нет, уведомление администратору не отправляется — поэтому первым симптомом обычно становятся расходящиеся брони.
Что делать: проверить в Битрикс24, жив ли входящий вебхук и остались ли у него права на календарь и пользователей. Как только очередная сверка проходит успешно, подключение снова считается действительным — отдельного действия для этого не требуется. Если вебхук пришлось создать заново, подключение в UnSpot нужно пересоздать: Настройка синхронизации календарей с Битрикс24.
Особые случаи и ограничения
| Случай | Как ведёт себя система |
|---|---|
| Остановка брони («освободить переговорную раньше времени») | Событие в Битрикс24 не удаляется и не сокращается, а ближайшая сверка вернёт бронь на исходное время. Освобождать переговорную нужно удалением брони — подробнее в разделе «Кто главный при конфликте» |
| Один портал на рабочее пространство | Второе подключение Битрикс24 к тому же пространству UnSpot создать нельзя |
| Один портал — одно пространство UnSpot | Ограничение проверяется только внутри пространства: второе подключение к тому же пространству не создать. Технически один портал можно подключить и к другому пространству UnSpot, но тогда два пространства будут конкурировать за одни календари — так делать не нужно |
| Права пользователя вебхука | Создавая событие, UnSpot ищет его участников среди всех пользователей портала в режиме администратора, поэтому вебхук нужен от учётной записи с административными правами. При отказе в доступе подключение помечается недействительным |
| Горизонт синхронизации | Сверка берёт события в окне от вчерашнего дня до 182 дней вперёд: встреча на более далёкую дату попадёт в UnSpot позже, когда войдёт в окно. По вебхуку одиночное событие приходит сразу, независимо от даты |
| Интенсивность обращений | UnSpot сам ограничивает частоту запросов к порталу, чтобы не выйти за лимиты Битрикс24, и обрабатывает сверки одного пространства по очереди. На большом числе переговорных сверка идёт заметно дольше, а часть календарей может дождаться только следующего прогона |
Что происходит при отключении
Кнопка «Отключить» в карточке Bitrix24 разрывает подключение целиком, для всех переговорных сразу. Отключить одну комнату этой кнопкой нельзя — для этого календарь отвязывают в карточке самой переговорной.
- Привязки всех переговорных к календарям портала удаляются. Чтобы вернуть синхронизацию, портал подключают заново и связывают календари с комнатами повторно.
- Бронирования в UnSpot остаются — в том числе те, что выросли из событий портала. Они просто перестают синхронизироваться.
- События, ранее созданные UnSpot, остаются в Битрикс24 — портал при отключении не изменяется. Если они больше не нужны, их удаляют в портале вручную.
- Исходящий вебхук в Битрикс24 продолжает работать и стучаться в UnSpot впустую. Его тоже отключают в портале.
