Как работает RegionTime

Что делает виджет

RegionTime берёт номер телефона из карточки и отвечает на один вопрос: который сейчас час у этого человека и рабочее ли у него время. Ответ появляется над номером, в отдельном блоке карточки и при постановке задачи.

Расчёт идёт в браузере. Таблицы нумерации и часовых поясов лежат внутри самого виджета, поэтому время появляется вместе с карточкой и не ждёт ответа сервера. На сервер виджет ходит только за настройками, тарифом и полями CRM.

Как номер превращается в часовой пояс

Виджет разбирает номер по кодам, а не по стране целиком.

• Россия. Реестр Россвязи: коды DEF (мобильные 9xx) и ABC (городские 3xx, 4xx, 8xx) разложены по субъектам федерации, субъекты — по часовым поясам. Поэтому 423 — это Владивосток, а не «среднее по России».
• Остальные страны. План нумерации из открытых данных Google libphonenumber плюс база часовых поясов IANA. Для стран с несколькими поясами — США, Бразилия, Австралия, Мексика, Казахстан — работает та же логика: пояс берётся от кода региона.
• Если код ничего не даёт. У мобильных номеров многих стран региона нет в принципе. Тогда виджет показывает страну и помечает ответ приблизительным — курсивом и пунктирной рамкой. Это не отказ, а честная точность.

Перевод часов

Виджет хранит имена часовых поясов — Asia/Vladivostok, Europe/Madrid — а не готовое смещение в часах. Смещение вычисляется каждый раз на нужную дату.

Разница видна там, где её обычно и упускают: задача, поставленная в октябре на ноябрь, считается по ноябрьскому времени, а не по сегодняшнему. Половина Европы и Америки в конце октября уезжает на час — виджет об этом знает.

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

Как считается рабочее и нерабочее

Состояние — это не только «попал ли час в окно». Виджет различает четыре положения и красит время соответственно.

• Рабочее время — зелёный. Час внутри окна, день не выходной и не праздник.
• День заканчивается — жёлтый. Последние 30 минут окна: звонить ещё можно, но обсуждать долгое — уже нет.
• Нерабочее время — коралловый, со значком луны.
• Выходной или праздник — тоже коралловый, но значок другой, чтобы было видно причину.

Окно по умолчанию 10:00–19:00 и меняется в настройках. Оно применяется к местному времени клиента, а не к вашему.

Праздники и выходные

Выходные

Суббота и воскресенье — не универсальное правило. В Саудовской Аравии, ОАЭ, Израиле и ряде других стран выходные приходятся на другие дни, и виджет берёт их из данных по стране, а не из своей привычки.

Праздники

Календарь собирается из правил, а не из списка дат на конкретный год: фиксированные даты, Пасха и православная Пасха с их подвижными производными, конструкции вида «третий понедельник января». Поэтому таблица не устаревает в новогоднюю ночь.

Ручная правка и почему она сильнее

Номер не всегда совпадает с местом: люди переезжают, возят SIM с собой, оформляют номер на другой регион. Для таких случаев часовой пояс правится руками.

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

Поля в карточке CRM

Виджет заводит собственную группу полей — «Регион» — и кладёт в неё только своё:

• RTZ_TIMEZONE — часовой пояс в формате IANA;
• RTZ_REGION — регион или город;
• RTZ_COUNTRY — страна;
• RTZ_WORKING — рабочее или нерабочее время у клиента (тариф PRO).

Где создавать поля — в сделке, контакте, компании — выбирается по отдельности, и можно не создавать вовсе. Ваши поля, статусы, теги и примечания виджет не трогает.

Флаг рабочего времени: как он остаётся актуальным

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

Сервер не обходит базу по расписанию. Для каждой записи он заранее вычисляет момент следующего переключения — когда у этого клиента начнётся или закончится рабочий день — и просыпается только к нему. Записи, у которых момент настал, обновляются пачками: CRM принимает до 250 сущностей за один запрос.

Отсюда арифметика, из-за которой это вообще возможно. У каждого клиента переключение случается дважды в сутки. База в 100 000 контактов — это около 33 пакетных запросов в час при лимите в 7 запросов в секунду. Обход всей базы каждый час, как это выглядит на первый взгляд, был бы невозможен.

Где виджет рисует

• Над номером телефона — время, регион и цвет состояния. Без рамки и фона: карточное поле и так обведено, а коробка внутри читалась бы как кнопка.
• Блок в правой колонке — два циферблата, сутки полосой и конвертер: циферблат клиента можно потянуть и увидеть, во сколько это будет у вас.
• В планировщике задач — время клиента для выбранного слота, до сохранения задачи.

Виджет следит за перерисовкой карточки и возвращает свои элементы на место, когда CRM обновляет разметку.

Что виджет делает с данными

• Определение пояса происходит в браузере. Номер телефона для этого никуда не отправляется.
• На сервере хранятся: идентификатор аккаунта, настройки, соответствие сущности и часового пояса, и цифры номера — они нужны, чтобы пересчитывать флаг рабочего времени без обращения к CRM.
• Токены доступа хранятся в зашифрованном виде и обновляются заранее, за час до истечения. Если доступ отозван, виджет говорит об этом в центре уведомлений, а не молчит.
• Часовые пояса сотрудников по умолчанию не собираются: часовой пояс — это приблизительные данные о местоположении человека, и включать их сбор нужно осознанно.

Тарифы и требования

Что входит в базовый тариф

Всё, что видит человек: время и регион над номером, блок с циферблатами и конвертером, подсказка в планировщике, поля с поясом, регионом и страной, перевод часов, выходные и праздники, ручная правка пояса. Бессрочно и без ограничения по числу менеджеров.

Что входит в PRO

Поле «Рабочее время у клиента», которое сервер держит актуальным, и пять видов циферблата. 1490 ₽ в месяц за аккаунт в amoCRM или $15 в Kommo, независимо от количества сотрудников.

Требование к CRM

Для того, что рисуется на экране, особый тариф CRM не нужен — работает на любом. Флаг рабочего времени обновляется по вебхукам, а они доступны не на всех тарифах amoCRM и Kommo. Если ваш их не поддерживает, остальное продолжит работать.

Установка