Шаблон VoIP провайдера для 3CX

Данная инструкция описывает создание шаблона VoIP провайдера и предназначена для сотрудников компаний, желающих создать готовые настройки своего VoIP сервиса для работы с 3CX Phone System. Шаблон VoIP провайдера для 3CX включает оптимальные предустановленные настройки для конкретного VoIP провайдера, что значительно облегчает процедуру подключения VoIP провайдера для пользователя — неспециалиста.

Введение

Большинство провайдеров в настоящее время придерживаются единых стандартов в предоставлении VoIP подключений. Практически любой VoIP провайдер может быть успешно подключен с использованием шаблона провайдера Generic. Шаблон Generic является основой для создания кастомизированного шаблона для конкретного провайдера. 3CX Phone System различает два типа подключения провайдеров:

  • Подключения с авторизацией по логину и паролю (VoIP Provider). Большинство провайдеров, рекомендованных 3CX, поддерживают подключение со стороны 3CX Phone System по логину и паролю
  • Подключение с авторизацией по IP адресу (VoIP trunk). VoIP транки не требуют регистрации 3CX на сервере провайдера. Вместо этого IP адрес сервера 3CX регистрируется у провайдера, и на этот адрес / с этого адреса провайдер маршрутизирует SIP вызовы. Подробнее о взаимодействии 3CX Phone System с VoIP операторами.

Расположение шаблонов VoIP провайдеров

Шаблоны VoIP провайдеров, включая шаблон Generic, доступны после инсталляции 3CX Phone System в папке C:\ProgramData\3CX\Data\Http\Templates\provider

  • GenericVoIPProvider.pv.xml – для провайдеров с авторизацией по логину и паролю
  • GenericSIPTrunk.pv.xml – для провайдеров с авторизацией по IP адресу

В зависимости от того, как ваш провайдер авторизует подключение, следует отредактировать соответствующий шаблон. Отредактированный шаблон следует сохранить под другим именем в этой же папке, чтобы 3CX “увидела” нового провайдера.

Создание шаблона нового VoIP провайдера

Для начала работы создайте копию файла провайдера Generic.

Внимание! Не рекомендуется изменять никакие значения в этом файле, кроме указанных ниже. И даже указанные значения (кроме названия, логотипа и сетевого адреса провайдера) рекомендуется изменять только в том случае, если параметры в шаблоне Generic работают в вашем случае некорректно.

Раздел Header

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

im1

Version

Значение определяется вендором (VoIP провайдером). Допустимы только цифровые значения. Номер версии начинается с 1 и должен быть увеличен при каждом обновлении данного шаблона.

<version>1</version>

URL

Ссылка на веб сайт провайдера

<url>http://www.vendorwebsite.com</url>

Логотип

Логотип должен представлять собой PNG файл размеров 16×16 пикселей. Имя файла логотипа должно совпадать с именем файла шаблона данного провайдера. Например, если имя файла шаблона myprovider.pv.xml, имя файла логотипа должно быть myprovider.png.

<image>myprovider.png</image>

Раздел Hostnames and Port Numbers

В разделе Hostnames and Port Numbers указываются FQDN имена / IP адреса и порты SIP провайдера, для которого создается данный шаблон.

im2

RegistrarHost

Указывается IP адрес или FQDN сервера провайдера. Если не будут указаны параметры ProxyHost/Port (см. ниже), 3CX Phone System попытается разрешить указанное FQDN имя SIP сервера через DNS SRV запись (_sip._udp.myprovider.com). В случае успешного ответа, 3CX получит набор DNS A записей SIP серверов провайдера и будет использовать SIP сервер с наименьшей метрикой. Если 3CX не сможет разрешить SRV запись, она просто использует FQDN имя как A запись SIP сервера.

<field name=”RegistrarHost”>myprovider.com</field>

RegistrarPort

Порт SIP сервера провайдера. По умолчанию имеет значение 5060. В редких случаях провайдер требует изменить это значение.

<field name=”RegistrarPort”>5060</field>

ProxyHost (опционально)

Если поле ProxyHost заполнено, 3CX использует DNS A запись, указанную в этом поле. Разрешение хоста по SRV записи не производится. Данные регистрации провайдера (RegistrarHost) 3CX передает через указанный ProxyServer. Значения ProxyServer и RegistrarHost могут совпадать (и обычно совпадают).

<field name=”ProxyHost”>proxy.myprovider.com</field>

ProxyPort (опционально)

Порт SIP прокси сервера провайдера. По умолчанию имеет значение 5060. В редких случаях провайдер требует изменить это значение.

<field name=”ProxyPort”>5060</field>

Раздел Registration Settings

В этом разделе определяются дополнительные настройки провайдера и параметры авторизации.

im3

RegistrationExpiry

Данный параметр определяет время в секундах, в течении которого 3CX подтверждает регистрацию (перерегистрируется) на VoIP провайдере. По умолчанию это 600 секунд. Минимальное допустимое значение – 60 секунд. Этот параметр не используется, если провайдер является транком (авторизация по IP адресу), но все равно должен быть установлен.

<field name=”RegistrationExpiry”>600</field>

RequiredAuthFor

Данный параметр определяет, используется ли авторизация по логину и паролю. Если провайдер является транком (авторизация по IP адресу), значение параметра равно 1.

<field name=”RequireAuthFor”>1</field>

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

<field name=”RequireAuthFor”>4</field>

Другие возможные значения параметра
2 = Авторизация только для входящих вызовов
3 = Авторизация только для исходящих вызовов

Только для подключений типа Trunk (авторизация по IP)

Если провайдер предусматривает авторизацию по IP, этот параметр запрещает указание логина и пароля пользователя.

<field name=”LineAuthenticationPassword” status=”readonly”></field> и <field name=”3wayauthenticationid” status=”readonly”></field>

Раздел Provider Capabilities

Параметры в этом разделе описывают дополнительные возможности провайдера. Они актуальны для провайдера любого типа, поскольку 3CX Phone System является промежуточным узлом коммутации между внутренними (добавочными) телефонами и провайдером.

im4

IsBindToMS

Этот параметр указывает, что все медиапотоки (голос) должны проходить через 3CX, а не направляться непосредственно на конечное SIP устройство. Доступные значения Yes=1 и No=0. Как правило, значение должно быть выставлено в 1.

<field name=”IsBindToMS”>1</field>

IsSupportReinvite

Этот параметр указывает на поддержку SIP Re-invites. Переключение этого параметра необходимо, если у вас нестабильно работает удержание, возобновление или перевод вызова. Доступные значения Yes=1 и No=0. Как правило, значение должно быть выставлено в 0.

<field name=”IsSupportReinvite”>0</field>

IsSupportReplaces

Этот параметр указывает на поддержку SIP Replaces. Переключение этого параметра необходимо, если у вас нестабильно работает перевод вызова. Доступные значения Yes=1 и No=0. Как правило, значение должно быть выставлено в 0.

<field name=”IsSupportReplaces”>0</field>

Disable Video

Этот параметр позволяет отключить описание видеопотока в исходящем SDP поле. Доступные значения Yes=1 и No=0. Если провайдер поддерживает передачу видео, значение параметра можно установить в 0 (т.е. включить видео).

<field name=”DisableVideo”>1</field>

Раздел Codecs

В разделе Codecs указываются доступные для данного провайдера кодеки, список которых передается в полях SDP. Приоритет кодеков определяется сверху вниз. Можно указать только поддерживаемые провайдером кодеки (т.е. меньше трех).

im5

Доступные опции: pcmu, pcma, gsm, g729, g722.

Раздел Source Identification

При получении запроса SIP INVITE, 3CX Phone System проводит идентификацию источника запроса (Source Identification) — сравнивает источник с имеющимся (созданным) аккаунтом SIP провайдера. Идентификация источника производится различными способами (по различным SIP полям).

im6

Лучше всего не изменять значения, установленные по умолчанию. При этом значения, передаваемые провайдером, будут без изменений приходить на сервер 3CX. Сообщение SIP INVITE, как правило, содержит уникальное значение, определяющее конкретный транк (линию) от SIP оператора. Для провайдеров, поддерживающих регистрацию по логину и паролю, это значение Authentication ID, передаваемое в любом из стандартных SIP полей.

Тем не менее, вы можете раскомментировать строку Match Strategy и установить в ней значение 1. Далее укажите в каком SIP поле (например, Contact User Part) передается AuthID в запросе SIP INVITE.

<field name=”MatchStrategy”>1</field>
<field name=”Source” parameter=”ContactUser” custom=””>$AuthID</field>

Если AuthID не передается в запросе INVITE (например, если подключение с авторизацией по IP), нужно определить уникальный параметр, по которому 3CX сможет провести идентификацию источника. Рекомендуется указывать FQDN или IP адрес SIP сервера провайдера (RegistrarHost). Именно с этого адреса приходит запрос INVITE. В этом случае система 3CX может использовать только единственный (многоканальный) транк от провайдера, т.к. нет другого уникального параметра, по которому можно идентифицировать подключение. Пример настройки:

field name=”MatchStrategy”>1</field>
<field name=”Source” parameter=”FromHostPart” custom=””>$GWHostPort</field>

В поле GWHostPort подставляется имя (или IP) хоста и порт в том виде, в каком они передаются провайдером.

Раздел Inbound/Outbound Parameters

В этом разделе определяются правила составления исходящих INVITE сообщений и правила парсинга (разбора) входящих INVITE сообщений. Они должны соответствовать требованиям провайдера. В свою очередь, входящие запросы от провайдера должны соответствовать требованиям 3CX.

im7

Parameter

Здесь определяется SIP поле запроса INVITE, в соответствии с SIP RFC, в котором ожидается (или должно быть помещено) соответствующее значение. Все возможные поля уже перечислены в этом разделе. Не добавляйте никакие дополнительные X или P заголовки – 3CX Phone System их игнорирует.

Правильно составленный SIP запрос INVITE показан ниже.

Invite: RequestLineURIUser@RequestLineURIHost
ContactUser@ContactHost
ToDisplayName: ToUserPart@ToHostPart
FromDisplayName: FromUserPart@FromHostPart
RemotePartyIDCalledPartyDisplayName: RemotePartyIDCalledPartyUserPart@RemotePartyIDCalledPartyHostPart
RemotePartyIDCallingPartyDisplayName: RemotePartyIDCallingPartyUserPart@RemotePartyIDCallingPartyHostPart
P-AssertedIdentityDisplayName: P-AssertedIdentityUserPart@P-AssertedIdentityHostPart
ProxyAuthID@ProxyAuthRealm

Обращаем внимание, что только необходимые SIP поля должны присутствовать в исходящем запросе INVITE. Не нужно включать в запрос все имеющиеся поля. Как правило, полей выставленных по умолчанию достаточно. Для входящих запросов INVITE необходимый минимум – это номер с которого и на которых идет вызов (Calling Party number, Called Party number), а также идентификатор транка (Device host, device port).

<field name=”ParameterIn” custom=”” parameter=”ToUserPart”>$CalledNum</field>

<field name=”ParameterIn” custom=”” parameter=”FromUserPart”>$CallerNum</field>

<field name=”ParameterIn” custom=”” parameter=”RequestLineURIHost”>$DevHostPort</field>

XML переменные

Переменные, которые помещаются между тэгами “> <” заменяются значениями, когда 3CXPhone System формирует SIP запрос. При обработке входящих запросов важно, чтобы одна переменная встречалась в только в одном SIP поле, т.е. не дублировалась в другом месте. При формировании исходящих запросов, одна переменная может помещаться в различные SIP поля, в зависимости от требований провайдера.

Если провайдер поддерживает функцию Clip No Screening, которая позволяет стороннему номеру (Caller ID) передаваться по транку вместо собственного номера транка, используйте значение Originator Caller ID вместо Outbound Caller ID в исходящих параметрах. Это позволит, например, перевести вызов на мобильный телефон и показать на экране мобильного исходный номер звонящего (Caller ID), а не добавочный номер 3CX (Extension).

Переменные и их описание

Обратите внимание, что определенные переменные могут соответствовать только определенным SIP полям, в соответствии с правилами RFC. Возможные значения SIP полей можно проверить в консоли управления 3CX Phone System.

ПеременнаяОписание
GWHostPortХост и порт SIP сервера провайдера, указываемый при создании провайдера.
OutHostPortХост и порт прокси сервера провайдера, указываемый при создании провайдера.
DevHostPortАдрес и порт источника сообщения от провайдера.
ContactURIСодержимое поля Contact.
CalledNameИмя абонента, которого вызывают (стандартно: To → display name).
CalledNumНомер абонента, которого вызывают (стандартно: To → User).
CallerNumНомер вызывающего абонента (стандарт: From → User).
LineNumberВнешний номер линии.
LineIDВнутренний (виртуальный) номер линии.
AuthIDID аутентификации.
OrginatorCallerIDОригинальный Caller ID вызывающего абонента.
OutboundLineIdИсходящий номер линии, который указывается в поле Внешний номер транка в консоли 3CX.
OutboundCallerIDИсходящий номер добавочного номера (Extension), который указывается в поле Исходящий номер в свойствах Extension в консоли 3CX.
CallerDispNameИмя пользователя (Display Name) добавочного номера. Формируется из имени и фамилии пользователя в консоли 3CX.
CustomFieldКастомная переменная.
Кастомные переменные

Если имеющегося набора переменных недостаточно для нормальной работы с провайдером, вы можете добавить кастомную переменную во входящий или исходящий набор SIP полей. В примере ниже, значение mysource.com вставлено в параметр To:HostPart  как кастомное поле, необходимое для корректной работы транка.

<field name=”Source” parameter=”ToHostPart” custom=”mysource.com”>$CustomField</field>