Функциональная группа (sipkit)

Описание

Определяет группу учетных записей SIP-пользователей, звонок на которых обслуживается по алгоритму группы.

Доступны следующие функциональные типы: группа переадресации, группа отказа, группа установки опций вызова, группа параллельных вызовов, группа шеф-секретарь.

Ограничения

  • Коллекция недоступна в мастер-домене.

Поля

Структура сущности
{
  "id": uuid,
  "name": str,
  "type": str,
  "enabled": bool,
  "cascade": bool,
  "priority": int,
  "details": object,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

Описание характеристик спецификации

Table 1. Поля
Спецификация Описание

Поле: id
Режим: inout
Тип: uuid
По умолчанию: generated

Идентификатор. Может быть задан при создании, иначе генерируется системой.

Поле: name
Режим: in
Тип: str
По умолчанию: required

Название группы. Отображается при трассировке.

Поле: type
Режим: in
Тип: str
По умолчанию: required

Тип группы. Под каждый тип задаются специфические настройки в поле 'details'.
Доступны следующие типы:

  • redirect - переадресация вызова.

  • reject - отклонение вызова.

  • options - установка параметров вызова.

  • parallel - распараллеливание вызова.

  • chief - шеф-секретарь.

  • custom - используется для реализации проектной логики.

Поле: enabled
Режим: in
Тип: bool
По умолчанию: true

Выключатель группы.

Поле: cascade
Режим: in
Тип: bool
По умолчанию: false

Выключатель режима каскадирования.
Если выключено, то при применении более приоритетной группы к тому же номеру не будет применена менее приоритетная группа того же типа.
Однако если во время применения группы происходит переадресация или распараллеливание, то применение групп этого типа для других номеров не блокируется.

Поле: priority
Режим: in
Тип: int
По умолчанию: 1000

Приоритет применения группы.

Поле: details
Режим: in
Тип: object
По умолчанию: ``

Объект с типизированными настройками.
Если создавая группу типизированные настройки не задаются, то они формируются и заполняются значениями по умолчанию.

Подробнее в разделе Типы групп.

Поле: opts
Режим: in
Тип: object

Составное поле

Поле: opts.title
Режим: in
Тип: str
По умолчанию: empty

Произвольный заголовок

Поле: opts.comment
Режим: in
Тип: str
По умолчанию: empty

Произвольный комментарий

Поле: ext
Режим: inout
Тип: object

Составное поле, позволяющее расширять состав произвольными ключами и значениями

Поле: ext.ct
Режим: out
Тип: date
По умолчанию: generated

Время создания объекта

Поле: ext.lwt
Режим: out
Тип: date
По умолчанию: generated

Время последней модификации объекта

Типы групп

В зависимости от установленного типа группы задается специальный параметр 'details', и при звонке реализуется соответствующая логика.

Группа переадресации (redirect)

Группа переадресации вызова.

Фильтр 'filter_from' применяется к номеру исходного абонента-инициатора без учета переадресаций и переводов. Номер абонента, переадресовавшего вызов может быть отфильтрован полем 'filter_by'.

Table 2. Параметры
Поле: filter_from
Режим: in
Тип: str
По умолчанию: *		 Маска-фильтр номера источника.
Проверяется результат модификации правилами маршрутизации, примененными на предыдущих шагах.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: filter_by
Режим: in
Тип: str
По умолчанию: *

Маска-фильтр номера абонента, переадресовавшего звонок.
Режимы работы фильтров.

Поле: redirect_number
Режим: in
Тип: str
По умолчанию: empty

Номер для переадресации.
Пример
{
  "filter_from": "*",
  "filter_by": "*",
  "redirect_number": "122"
}

Группа отказа (reject)

Группа отказа в вызове.

Фильтр 'filter_from' применяется к номеру исходного абонента-инициатора без учета переадресаций и переводов. Номер абонента, переадресовавшего вызов может быть отфильтрован полем 'filter_by'.

Table 3. Параметры
Поле: filter_from
Режим: in
Тип: str
По умолчанию: *		 Маска-фильтр номера источника.
Проверяется результат модификации правилами маршрутизации, примененными на предыдущих шагах.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: filter_by
Режим: in
Тип: str
По умолчанию: *

Маска-фильтр номера абонента, переадресовавшего звонок.
Режимы работы фильтров.

Поле: sip_code
Режим: in
Тип: int
По умолчанию: 403

Код ответа.

Поле: sip_reason
Режим: in
Тип: str
По умолчанию: Rejected by kit

Причина отказа.
Пример
{
  "filter_from": "*",
  "filter_by": "*",
  "sip_code": 603,
  "sip_reason": "Some reason"
}

Группа установки опций вызова (options)

Группа формирует изменение опций вызова для плеча и дочерних плеч (вызовов, инициированных переадресацией и/или параллельными вызовами в рамках текущего процесса маршрутизации).
В частности, позволяет установить:

  • dialog_timeoutsec - ограничение на продолжительность разговора (от 5 до 7200).

  • fork_timeoutsec - специфическое время вызова плеча (от 3 до 180).

  • fork_fromuri - представление вызывающего абонента.

Установленное значение применяется для всех дочерних плеч, если для них в продолжении процесса маршрутизации не будет применена индивидуальная настройка из другой группы.
Значение по умолчанию - не применяет параметр группы. Значение "undefined" - сбрасывает примененный ранее параметр.

Фильтр 'filter_from' применяется к номеру исходного абонента-инициатора без учета переадресаций и переводов. Номер абонента, переадресовавшего вызов может быть отфильтрован полем 'filter_by'.

Table 4. Параметры
Поле: filter_from
Режим: in
Тип: str
По умолчанию: *		 Маска-фильтр номера источника.
Проверяется результат модификации правилами маршрутизации, примененными на предыдущих шагах.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: filter_by
Режим: in
Тип: str
По умолчанию: *

Маска-фильтр номера абонента, переадресовавшего звонок.
Режимы работы фильтров.

Поле: numbers_to
Режим: in
Тип: array<str>
По умолчанию: []

Список номеров, при поступлении вызова на которые происходит активация группы.

Поле: dialog_timeoutsec
Режим: in
Тип: int
По умолчанию: 7200

Максимальная длительность диалога, секунды.

Значение 0 или некорректное значение - не изменяет параметр.
Значение "undefined" сбрасывает значение ранее примененными группами типа 'options'.
Устанавливаемое значение ограничивается интервалом от 5 до 7200 секунд.

Поле: fork_timeoutsec
Режим: in
Тип: int
По умолчанию: 0

Таймаут вызова плеча, секунды.

Применяется для всех плеч, дочерних по отношению к текущему вызову в рамках текущего процесса маршрутизации.
Учитываются переадресованные и параллельные вызовы".
Изменить может последующее применение группы этого же типа к другим дочерним адресатам.

Значение 0 или некорректное значение - не изменяет параметр.
Значение "undefined" сбрасывает значение ранее примененными группами типа 'options'.
Устанавливаемое значение ограничивается интервалом от 3 до 180 секунд.

Поле: fork_fromuri
Режим: in
Тип: str
По умолчанию: empty

Представление вызывающего абонента.

Применяется для всех плеч, дочерних по отношению к текущему вызову в рамках текущего процесса маршрутизации.
Учитываются переадресованные и параллельные вызовы".
Изменить может последующее применение группы этого же типа к другим дочерним адресатам.

Применяются только username и displayname.
Значение "undefined" сбрасывает значение ранее примененными группами типа 'options'.
Пустая строка или некорректный формат URI - не изменяет параметр.
Пример
{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "fork_timeoutsec": 3,
  "fork_fromuri": "\"DISPLAY NAME\" <sip:username@domain>"
}

Группа параллельного вызова (parallel)

Группа распараллеливания вызова в зависимости от маски инициатора вызова и опционально инициатора перевода вызова.

Любой вызов на номер учетной записи, указанной в списке 'numbers_to', приводит к одновременному вызову заданных в поле 'numbers_parallel' параллельных номеров.
Любой - это прямой, групповой, переведенный, переадресованный, из сценария.
В случае если такой номер вызывается в качестве параллельного из другой функциональной группы, то применение установленных для него параллельных номеров зависит от свойства каскадности функциональной группы.

Является общей альтернативой настройке индивидуального параллельного вызова в учетной записи SIP-пользователей.
При этом вызов в статистике привязывается к реальному владельцу номера-назначения.

Фильтр 'filter_from' применяется к номеру исходного абонента-инициатора без учета переадресаций и переводов. Номер абонента, переадресовавшего вызов может быть отфильтрован полем 'filter_by'.

Table 5. Параметры
Поле: filter_from
Режим: in
Тип: str
По умолчанию: *		 Маска-фильтр номера источника.
Проверяется результат модификации правилами маршрутизации, примененными на предыдущих шагах.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: filter_by
Режим: in
Тип: str
По умолчанию: *

Маска-фильтр номера абонента, переадресовавшего звонок.
Режимы работы фильтров.

Поле: numbers_to
Режим: in
Тип: array<str>
По умолчанию: []

Список номеров, при поступлении вызова на которые происходит активация группы.

Поле: numbers_parallel
Режим: in
Тип: array<str>
По умолчанию: []

Список номеров применяемых для инициации параллельного вызова. В любом случае вызовы будут отправлены на каждый из целевых номеров по одному разу.
Пример
{
  "filter_from": "*",
  "filter_by": "*",
  "numbers_to": ["205","206"],
  "numbers_parallel": ["205","206","207"]
}

Группа шеф-секретарь (chief)

При поступлении вызова на шефа от номеров, отсутствующих в списке прямого доступа, производится вызов секретарей.

Решение о том, разрешен ли инициатору прямой вызов шефа, принимается на основании фильтра, примененного к номеру абонента, переведшего или переадресовавшего вызов на шефа.

Одновременно группа разрешает перехват вызова, подписку BLF между шефом и секретарями, а также размещает детализацию по входящему вызову в BLF-уведомлениях для отображения на панели устройств, чтобы абоненты группы видели инициатора вызова и могли перехватить.
Таким образом между шефом и секретарями нет необходимости настраивать отдельно разрешения правилами featurerules на следующие типы функций:
* pickup, callwaiting, blf, blf_details - во всех направлениях;
* intercom, barge - в направлении от шефа к секретарям.

Чтобы режим работал полноценно, необходимо:
* включить опцию 'blf_details_enabled' в настройках домена;
* настроить на телефонах шефа и секретарей BLF-подписки по необходимости (чтобы секретари видели состояние шефа, шеф видел состояния секретарей);
* настроить на телефонах шефа и секретарей отображение информации об инициаторе вызова при получении BLF сообщения (Yealink: account.X.dialoginfo_callpickup=1, features.pickup.blf_visual_enable=1);
* ограничить на телефонах шефа и секретарей применение визуализации BLF для определенного списка номеров (Yealink: features.pickup.blf_visual.list=101,102,103 или any);
* при необходимости аудио оповещения о звонке на номер шефа, настроить на телефонах секретарей проигрывание мелодии при получении BLF сообщения (Yealink: features.pickup.blf_audio_enable=1), настроить мелодию, и прописать ограничения применение аудио оповещения BLF для определенного списка номеров (Yealink: features.pickup.blf_audio.list=101,102,103 или any).

При вышеперечисленных настройках телефон подписчика отображает на дисплее входящие вызовы отслеживаемого абонента, предоставляя возможность перехватить выбранный.
Перехват осуществляется отправкой INVITE с заголовком Replaces (а не звонком на код абонентской функции, поскольку в этом режиме невозможно указать конкретный вызов для перехвата).

Существует альтернативная настройка с перехватом через код абонентской функции:
* создать код абонентской функции с типом "перехват по номеру" и настроить его доступность в правилах маршрутизации;
* настроить на телефонах шефа и секретарей поддержку функции перехвата - задание номера соответствующего фичакода (Yealink: account.x.direct_pickup_code);
* при настройке BLF-подписок на телефонах шефа и секретарей указать для каждой из них номер для перехвата (тот же код абонентской функции).

Чтобы работал режим с перехватом через фичакод, необходимо выключить на телефоне опцию (Yealink: account.X.dialoginfo_callpickup=0).
При использовании фичакода типа 'перехват' невозможно указать конкретный вызов для перехвата, если на отслеживаемое устройство поступает несколько вызовов.
В этой связи в целях повышения производительности целесообразно не использовать детализацию в BLF уведомлениях, отключив опцию 'blf_details_enabled' в настройках домена.

Table 6. Параметры
Поле: mode
Режим: in
Тип: str
По умолчанию: cascade		 Алгоритм работы. Возможные варианты:

* parallel - при звонке на номер шефа с любого номера, не упомянутого в группе, вызов переадресуется на обоих ассистентов параллельно.
* cascade - при звонке на номер шефа с любого номера, не упомянутого в группе, вызов переадресуется последовательно на первого ассистента, затем на второго.
* direct - при звонке на номер шефа с любого номера вызов проходит без переадресации.

Поле: chief_number
Режим: in
Тип: str
По умолчанию: empty

Номер шефа.

Поле: assistant1_number
Режим: in
Тип: str
По умолчанию: empty

Номер первого ассистента.

Поле: assistant2_number
Режим: in
Тип: str
По умолчанию: empty

Номер второго ассистента.

Поле: direct_numbers
Режим: in
Тип: array<str>
По умолчанию: []

Список номеров, напрямую проходящих на шефа. Применяется к результату преобразования from/referred-by правилами маршрутизации.

Поле: chief_mobile
Режим: in
Тип: str
По умолчанию: empty

Мобильный номер шефа. Номер применяется для автоматической публикации состояния абонента, участвующего в диалоге.
Таким образом секретари получают возможность осуществить BLF-подписку на внешний номер и получать уведомления о завершении диалога.
Разрешение на подписку на мобильный номер шефа секретарям выдается автоматически.

Пример кейса: секретарь соединяет шефа на мобильном номере последовательно с несколькими абонентами.

Расширяет список внешних номеров с отслеживаним состояний, список которых задается в настройках домена.
Пример
{
  "mode": "cascade",
  "chief_number": "101",
  "assistant1_number": "102",
  "assistant2_number": "103",
  "direct_numbers": ["115", "123"]
}

Произвольная группа (custom)

Применяется для реализации проектной логики.

Table 7. Параметры
Поле: filter_from
Режим: in
Тип: str
По умолчанию: *		 Маска-фильтр номера источника.
Проверяется результат модификации правилами маршрутизации, примененными на предыдущих шагах.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: filter_by
Режим: in
Тип: str
По умолчанию: *

Маска-фильтр номера абонента, переадресовавшего звонок.
Режимы работы фильтров.

Поле: numbers_to
Режим: in
Тип: array<str>
По умолчанию: []

Список номеров, при поступлении вызова на которые происходит активация группы.

Поле: type
Режим: in
Тип: str
По умолчанию: empty

Проектный тип группы. Определяет набор прочих параметров детализации.

Дополнительно

Режимы работы фильтра

Режим Описание

Посимвольный

Подвергаемое проверке соответствия значение посимвольно проводится через фильтр.
Могут применяться следующие спец-символы и сочетания:

  • X – любой символ;

  • * – все оставшиеся символы;

  • {F} и {f} – исходное значение From username целиком;

  • {T} и {t} – исходное значение To username целиком;

  • {E} и {e} – пустое значение.

  • ? - любой символ (если используется для фильтра по доменным именам, то любой символ кроме точки - разделителя доменных имен).

  • $ - для фильтра по доменам. Любая последовательность символов кроме точки - разделителя доменных имен.

При необходимости указать один из служебных символов как целевой, его следует заключать в квадратные скобки, например [X].

Например, XXX – любое трехсимвольное значение.

Таблица

Может применяться подстрока {tab:…​}. С помощью нее можно выделить группу символов в проверяемом значении и сопоставить их с таблицей, встроенной в правило (opts.tab).
Например, {tab:a} - выделение подстроки и сопоставление ее с полем a всех объектов/строк в таблице.
Таблица служет связке нескольких полей фильтров и модификаторов. На основании последовательной проверки фильтров в таблице остается меньшее количество строк с учетом обнаруженных совпадений.
Первая из оставшихся строк служит для применения в модификаторах. При условии что в таблице не осталось строк - правило отклоняется.
Захват символов из проверяемого значения на основе маски может происходить автоматически, либо со строгим указанием длины подстроки:

  • {tab:KEY} - Автоматический захват из проверяемого значения.

  • {tab:KEY:LENGTH} - Захват указанного количества символов из проверяемого значения.

В качестве значений полей в таблице могут применяться:

  • константы (для этого значение надо указать конкретное значение);

  • регулярные выражения (для этого необходимо задать значение в формате /reg/EXPRESSION, например /reg/^1[1-4]$);

  • сопоставления с другими полями таблицы (для этого необходимо задать значение в формате /tab/FIELD, например /tab/a). Режим используется для связывания значений различных полей. Например, чтобы разрешить звонки только на собственный ящик голосовой почты. Необходимо строго соблюдать порядок связывания: если поле таблицы, на которое производится ссылка, еще не проверялось и не было заполнено реальным значением другого поля сущности, то сопоставление не пройдет. Порядок проверки полей сущности: filter_from, filter_by;

  • любое значение, применяемого без регулярного выражения (для этого необходимо задать /any). Режим полезен исключительно при организации прямых сопоставлений со значениями других полей без дополнительных фильтров.

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

Например, {tab:a:3}XXXXX{tab:b} - позволяет выделить в номере 3-символьный код города и сопоставить с полем a в таблице, и одновременно выделить хвост начиная с 9 символа и сопоставить с полем b таблицы.

Regex

К исходному значению применяется шаблон Pattern.

Структура значения regex-шаблона:
/reg/Pattern1.

Например,- значение: "302"
- маска: "/reg/0"
- результат: true.

  • значение: "302"

  • маска: "/reg/^0$"

  • результат: false.

  • значение: "302"

  • маска: "/reg/^302$"

  • результат: true.

  • значение: "302"

  • маска: "/reg/^(301|302|305)$"

  • результат: true.

При формировании шаблонов Pattern могут применяться все стандартные правила регулярных выражений.

Диапазон

Подвергаемое проверке соответствия значение - целое числовое и входит в указанный диапазон числовых значений.

Структура значения dia-шаблона:
/dia/FromValue+N - подпадают под шаблон N+1 значений от FromValue до FromValue+N.

Например,- значение: "302"
- маска: "/dia/300+10"
- результат: true.

См. также

API

Логические роли

  • b2b проводит маршрутизацию и применение групповой логики.

  • mdc и sdc производят поиск группового номера.

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт