Бронирование в Cal.com

Подключите календарь#

Откройте Агент → Действия → Cal.com. Введите API-ключ Cal.com с префиксом cal_, положительный целочисленный ID типа события и часовой пояс IANA, например Asia/Seoul. Нажмите Сохранить подключение. У каждого агента своё подключение. Ключ шифруется на сервере; панель показывает только последние четыре символа. Чтобы сохранить текущий ключ при изменении подключения, оставьте поле пустым.

Проверить подключение читает до трёх свободных интервалов на ближайшие семь дней с введёнными настройками. Проверка не сохраняет подключение и не создаёт бронирование. Пустой результат может означать отсутствие свободного времени в этот период. При ошибке проверьте ключ, тип события и расписание в Cal.com. Удаление подключения останавливает новые бронирования, но не отменяет существующие.

Платежи вне объёма функции. Google Calendar — отдельный вариант, пока недоступный для всех.

От времени к бронированию#

1. Агент вызывает find_slots для реальной будущей доступности и показывает до восьми вариантов в настроенном часовом поясе. По умолчанию период — от сегодня до семи дней спустя, максимальная разница дат — 14 дней. Единственное время показывается отдельно.
2. Клиент выбирает время и сообщает имя, email и необязательную заметку. Агент проверяет, что время было предложено этому разговору и ещё свободно. Предложенные варианты действуют 15 минут.
3. Карточка показывает дату, время, часовой пояс и данные участника. Клиент обязан нажать Подтвердить. Сообщение или выбор времени сами по себе не бронируют. Предложение истекает через 15 минут и не удерживает слот.
4. Только после подтверждения отправляется запрос в Cal.com. Результат accepted становится done, с UID бронирования в качестве номера результата. pending и awaiting_host остаются ожиданием, отказ и отмена становятся ошибкой.

В каналах бронирование предлагается только в личных чатах. Репетиция не вызывает Cal.com и не создаёт бронь. Без подключения Cal.com остаётся прежняя отправка заявки на запись; она не подтверждает резервирование в календаре. Изменение ключа, типа события или часового пояса делает цель старого предложения недействительной, поэтому начните заново после изменения подключения.

Если время занято или результат неизвестен#

Другой клиент может занять время до завершения подтверждения. Если оно больше недоступно, агент сообщит об этом; если Cal.com отклонит создание, карточка покажет ошибку. Запросите свежие варианты и подтвердите новое предложение. Новые варианты не добавляются к карточке ошибки автоматически.

Сетевой тайм-аут не доказывает ни успех, ни неудачу. Пока сервис проверяет снова, результат остаётся неизвестным. У endpoint создания Cal.com нет документированного контракта ключа идемпотентности, поэтому адаптер сохраняет run ID в metadata.maf_run и перед повторным созданием ищет бронь по всем статусам и страницам. Незавершённый поиск не разрешает новый запрос создания. Это снижает риск дубликата, но не даёт гарантии однократного выполнения со стороны провайдера. После исчерпания попыток проверьте Cal.com перед новой бронью.

Одобрение организатора Cal.com отдельно от одобрения владельца для пользовательских действий изменения. Интеграция не обновляет ожидающую бронь Cal.com автоматически: итог проверьте в Cal.com. Веб-виджет опрашивает сохранённый результат запуска, а поддерживаемые личные каналы получают отложенные результаты в пределах окна обслуживания. См. доставку результатов.

Версии API и проверки перед запуском#

Адаптер использует Bearer-аутентификацию и отдельный cal-api-version для каждого endpoint. Значения сверены с официальной документацией 2026-10-13:

Перед использованием с клиентами создайте контролируемую бронь, проверьте UID в Cal.com, попробуйте занятое время и проверьте результаты во всех нужных каналах. Успешный тест подключения подтверждает только чтение слотов, а не реальную бронь или готовность продакшена.