4. Minimal Configuration

The recommended first step in configuring Promptar HTTPBX Connector focuses on the essentials and allows one to validate its basic operation. It consists of setting up:

With this configuration the following critical aspects are validated:

4.1. Sample Configuration Files

The installation procedure for each Promptar software component, creates one or more sample configuration files in the platform dependent configuration file directory. These files have a .conf.sample extension and contain, within themselves, multiple comments and examples. Please take your time having a look at those.

Copy each .conf.sample file to the respective .conf file. When completed, you should have the following files:

name purpose

prptHTTPBX.conf

Connector configuration.

4.2. Editing Configuration Files

Configuration files are .INI like files and should be edited with a regular text editor. Since we’re starting off with the sample configuration file and it includes several pre-defined, commented out settings, the majority of the initial work will be going through it uncommenting the appropriate ones for the given environment.

 

prptHTTPBX.conf

Open the prptHTTPBX.conf file and scroll down to the [log] section. You should find the following:

[log]

; Recommended configuration
; -------------------------
; type = file
; file = /var/log/promptar/prptHTTPBX.log
; file = C:/Program Files/Promptar HTTPBX Connector/Log/prptHTTPBX.log
; file = C:/Program Files (x86)/Promptar HTTPBX Connector/Log/prptHTTPBX.log
; file.rotate.when  = 1 midnight
; file.rotate.count = 7
; level             = warning

Uncomment the lines starting with type, file and level depending on whether you’re on a Linux or Windows host; pay particular attention the the line starting with file, pointing to the path of the log file. The recommended configuration ensures daily log file rotation while keeping 7 days worth of history. If you want to change these settings, please check the comments preceding these lines in the sample configuration file.

Continue scrolling down to the [http] section, skipping the commented out [network] section. The sample configuration includes two examples for different HTTP(S) servers. To start off, activate the server0 instance by uncommenting, at least, the first server0.protocol line [1].

[http]

; server0.protocol  = http
; server0.interface = 0.0.0.0
; server0.port      = 8080
; server0.auth      = digest
; server0.username  = promptar
; server0.password  = qwepoi123098
; server0.fallback  = yes

; server1.protocol  = https
; server1.interface = 0.0.0.0
; server1.port      = 8443
; server1.key       = <path-to-pem-encoded-private-key-file>
; server1.cert      = <path-to-pem-encoded-certificate-file>
; server1.trust     = <path-to-pem-encoded-certificate-bundle-file>
; server1.auth      = basic
; server1.username  = promptar
; server1.password  = qwepoi123098
; server1.fallback  = yes

 

Before setting up a driver and associated extensions, scroll to the bottom of the where the [data] section is located. It shows the recommended settings for where the connector should store its state accross restarts, depending on the platform. Uncomment the location line appropriate to the host system:

[data]

; Recommended configuration
; -------------------------
; location = /var/lib/promptar/prptHTTPBX
; location = C:/Program Files/Promptar HTTPBX/data
; location = C:/Program Files (x86)/Promptar HTTPBX/data

 

The next sections describe the minimal configuration for each of the existing drivers and associated extensions, by continuing the configuration file editing process. Please refer to the one appropriate to your environment and, if multiple drivers are required, start with a single one, test it, and keep adding and testing others one at a time.

4.3. Broadworks

Broadworks System Configuration

None required once the XSI URL is accessible.

Connector Configuration

Scroll to the [drivers] section and uncomment the lines:

[drivers]

; broadworks.server.id      = server0
; broadworks.client.url     = https://<broadworks-xsi-url>/
; broadworks.client.version = 21.0

Then:

  • Set broadworks.client.url to the Broadworks XSI URL of the Broadworks system in use.
  • If the HTTP server is not used by any other driver, given that the broadworks driver does not need the HTTP server to be exposed, set server0.interface to 127.0.0.1 in the [http] section.

Once complete, scroll to the [extensions] section and add a set of lines like the following ones, per each extension to be configured. For initial testing, add no more than two or three [2].

<extension>.identity = broadworks/<bw-user-and-domain>
<extension>.auth     = <bw-password>

Where:

  • <extension> will typically be a sequence of digits representing the user extension.
  • <bw-user-and-domain> identifies the Broadworks user associated to the extension.
  • <bw-password> is the user’s Broadworks password.

The minimal Broadworks driver/extension setup is now complete. The connector operation should now be verified with test calls, along with the Promptar Server, Client and other components in the environment.

Once successful, other drivers/extensions can be added [3]; then, proceed to the Finalizing the Installation chapter.

4.4. Switchvox

Switchvox System Configuration

Switchvox systems need to be configured in order to notify the connector of call related events. To do that, login to the Switchvox administration web interface at https://<switchvox-system>/admin and, under PBX Features > Event Triggers, set the System Default URL to:

<base-url>/?event_type=%EVENT_TYPE%&
            clid_num=%CALLER_ID_NUMBER%&
            dialled_num=%DIALED_NUMBER%&
            extension=%EXTENSION%&
            ext_type=%EXTENSION_TYPE%&
            in_did=%INCOMING_DID%&
            jobid=%JOB_ID%

Where:

  • <base-url> is the URL that Switchvox should use to issue HTTP requests reaching this connector. Depending on the [http] section settings:

    • Use http or https protocol.
    • Optionally include <username>:<password> to handle authentication.
    • By default, the path for the Switchvox driver will be /switchvox.
    • A typical case is https://<username>:<password>@<promptar-host>:<port>/switchvox.
  • The URL above is displayed for readability purposes. It should be entered in a single line with no spaces between each of the above shown multiple lines.

 

Network Connectivity

 

Keep in mind general network connectivity aspects like routing, firewalls, address translation and name resolution that may need to be configured when using a public Switchvox server reaching into a private network hosted system running Promptar.

Connector Configuration

After configuring the Switchvox system go back to the connector configuration file, scrolling to the [drivers] section, and uncomment the sample lines starting with switchvox, there:

[drivers]

; switchvox.server.id       = server1
; switchvox.server.path     = /switchvox
; switchvox.client.url      = https://<switchvox-system>/xml/
; switchvox.client.username = username
; switchvox.client.password = password

Then:

  • Adjust switchvox.server.id to match the settings in the [http] section.
  • Set switchvox.client.url to include the correct protocol, hostname and optional port for the Switchvox XML API.
  • Lastly, change username and password to reflect the credentials of a Switchvox administrator user.

Once complete, scroll to the [extensions] section and add a set of lines like the following ones, per each extension to be configured. For initial testing, add no more than two or three [4].

<extension>.identity = switchvox/<sv-extension>
<extension>.auth     = <sv-password>
<extension>.account  = <sv-account>

Where:

  • <extension> will typically be a sequence of digits representing the user extension.
  • <sv-extension> is the Switchvox extension and should probably match <extension>.
  • <sv-password> is the Switchvox extension password.
  • <sv-account> is the Switchvox extension account number.

The minimal Switchvox driver/extension setup is now complete. The connector operation should now be verified with test calls, along with the Promptar Server, Client and other components in the environment.

Once successful, other drivers/extensions can be added [5]; then, proceed to the Finalizing the Installation chapter.

4.5. Polycom Phones

Phone Configuration

Polycom phones need to be configured in order to notify the connector of call related events. Additionally, the push requests need to be enabled so as to support Promptar based call control. To do that, login to the phone’s web based administration interface and, under Settings > Applications:

  • In the Telephony Event Notification section:

    • Enter the appropriate URL under Configured Telephony Notification URL, based on the [http] section settings. A typical case is https://<username>:<password>@<promptar-host>:<port>/polycom/.
    • Enable all event checkboxes: Line Registration, Incoming Call, Outgoing Call, Onhook, Offhook, User Login and Logout and Call State Change.
  • In the Push section:

    • Set Allow Push Messages to All.
    • Enter values for User Name and Password.

When done, save the phone configuration by clicking the Save button.

 

Automated Configuration

When preparing a large set of phones, it is valuable to configure them in a centralized manner. Even though that is out of the scope of this document, the snippet below includes XML settings that can be used:

<polycomConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="polycomConfig.xsd">
  <apps apps.1.label="" apps.1.url="" apps.2.label="" apps.2.url="">
    <apps.push apps.push.alertSound="0" apps.push.messageType="5"
               apps.push.password="{PUSH_PASSWORD}" apps.push.secureTunnelEnabled="1"
               apps.push.secureTunnelPort="443" apps.push.secureTunnelRequired="0"
               apps.push.serverRootURL="" apps.push.username="{PUSH_USERNAME}">
    </apps.push>
    <apps.telNotification apps.telNotification.appInitializationEvent="0"
                          apps.telNotification.callStateChangeEvent="1"
                          apps.telNotification.incomingEvent="1"
                          apps.telNotification.lineRegistrationEvent="1"
                          apps.telNotification.networkUpEvent="0"
                          apps.telNotification.offhookEvent="1"
                          apps.telNotification.onhookEvent="1"
                          apps.telNotification.outgoingEvent="1"
                          apps.telNotification.taInitializationEvent="1"
                          apps.telNotification.uiInitializationEvent="0"
                          apps.telNotification.URL="{CONNECTOR_URL}"
                          apps.telNotification.userLogInOutEvent="1">
    </apps.telNotification>
  </apps>
  <voIpProt>
    <voIpProt.SIP.alertInfo voIpProt.SIP.alertInfo.1.class="ringAutoAnswer"
                            voIpProt.SIP.alertInfo.1.value="Ring Answer">
    </voIpProt.SIP.alertInfo>
  </voIpProt>
</polycomConfig>

 

Where {PUSH_USERNAME}, {PUSH_PASSWORD} and {CONNECTOR_URL} should be replaced with appropriate values for the environment. Note, also, the inclusion of the voIpProt.SIP.alertInfo setting that forces the phone to auto-answer Promptar initiated outgoing calls.

Connector Configuration

After configuring the phones, go back to the connector configuration file, scrolling to the [drivers] section, and uncomment the sample lines starting with polycom, there:

[drivers]

; polycom.server.id         = server1
; polycom.server.path       = /polycom
; polycom.handle.control    = strict
; polycom.client.protocol   = https

Then:

  • Adjust polycom.server.id to match the settings in the [http] section.
  • Set polycom.client.protocol according to the phones' HTTP server settings.

Once complete, scroll to the [extensions] section and add a set of lines like the following ones, per each extension to be configured. For initial testing, add no more than two or three [6].

<extension>.identity = polycom/<line-sip-uri>/<phone-mac-address>:<line-number>
<extension>.auth     = <phone-http-auth>:<phone-push-username>:<phone-push-password>

Where:

  • <extension> will typically be a sequence of digits representing the user extension.
  • <line-sip-url> is a line URI formatted like sip:user@domain.
  • <phone-mac-address> is the phone mac address, in lower-case hex, and no per-byte separators.
  • <line-number> is the configured line number for the given <line-sip-uri>.
  • <phone-http-auth> is one of basic or digest, depending on the phone’s HTTP server authentication settings.
  • <phone-push-username> and <phone-push-password> should match the values configured on the phone.

The minimal Polycom phone driver/extension setup is now complete. The connector operation should now be verified with test calls, along with the Promptar Server, Client and other components in the environment.

Once successful, other drivers/extensions can be added [7]; then, proceed to the Finalizing the Installation chapter.

4.6. Snom Phones

Phone Configuration

Snom phones need to be configured in order to notify the connector of call related events. To do that, login to the phone’s web based administration interface and, under Setup > Action URL Settings, enter the settings in the table:

setting value

Incoming call

<base-url>/incoming?local=$local&remote=$remote&callid=$call-id

Outgoing call

<base-url>/outgoing?local=$local&remote=$remote&callid=$call-id

On Connected

<base-url>/connected?local=$local&remote=$remote&callid=$call-id

On Disconnected

<base-url>/disconnected?local=$local&remote=$remote&callid=$call-id

Hold call

<base-url>/hold?local=$local&remote=$remote&callid=$call-id

Unhold call

<base-url>/resume?local=$local&remote=$remote&callid=$call-id

Transfer call

<base-url>/xfer?local=$local&remote=$remote&callid=$call-id

Blind transfer

<base-url>/b-xfer?local=$local&remote=$remote&callid=$call-id

Attended transfer

<base-url>/at-xfer?local=$local&remote=$remote&callid=$call-id

Where <base-url> is the URL that the phones should use to issue HTTP requests reaching this connector, depending on the [http] section settings. A typical case is https://<username>:<password>@<promptar-host>:<port>/snom/.

 

Automated Configuration

When preparing a large set of phones, it is valuable to configure them in a centralized manner. Even though that is out of the scope of this document, the snippet below includes XML settings that can be used:

<?xml version="1.0" encoding="utf-8" ?>
<settings>
<phone-settings>
  <action_incoming_url perm="R">
    {CONNECTOR_URL}/incoming?local=$local&remote=$remote&callid=$call-id
  </action_incoming_url>
  <action_outgoing_url perm="R">
    {CONNECTOR_URL}/outgoing?local=$local&remote=$remote&callid=$call-id
  </action_outgoing_url>
  <action_connected_url perm="R">
    {CONNECTOR_URL}/connected?local=$local&remote=$remote&callid=$call-id
  </action_connected_url>
  <action_disconnected_url perm="R">
    {CONNECTOR_URL}/disconnected?local=$local&remote=$remote&callid=$call-id
  </action_disconnected_url>
  <action_hold perm="R">
    {CONNECTOR_URL}/hold?local=$local&remote=$remote&callid=$call-id
  </action_hold>
  <action_unhold perm="R">
    {CONNECTOR_URL}/resume?local=$local&remote=$remote&callid=$call-id
  </action_unhold>
  <action_transfer perm="R">
    {CONNECTOR_URL}/xfer?local=$local&remote=$remote&callid=$call-id
  </action_transfer>
  <action_blind_transfer perm="R">
    {CONNECTOR_URL}/b-xfer?local=$local&remote=$remote&callid=$call-id
  </action_blind_transfer>
  <action_attended_transfer perm="R">
    {CONNECTOR_URL}/at-xfer?local=$local&remote=$remote&callid=$call-id
  </action_attended_transfer>
</phone-settings>
</settings>

Where {CONNECTOR_URL} should be replaced with appropriate value for the environment.

Connector Configuration

After configuring the phones, go back to the connector configuration file, scrolling to the [drivers] section, and uncomment the sample lines starting with snom, there:

[drivers]

; snom.server.id            = server1
; snom.server.path          = /snom
; snom.handle.control       = strict
; snom.client.protocol      = https

Then:

  • Adjust snom.server.id to match the settings in the [http] section.
  • Set snom.client.protocol according to the phones' HTTP server settings.

Once complete, scroll to the [extensions] section and add a set of lines like the following ones, per each extension to be configured. For initial testing, add no more than two or three [8].

<extension>.identity = snom/<sip-line-identity>
<extension>.auth     = <phone-http-auth>:<phone-username>:<phone-password>

Where:

  • <extension> will typically be a sequence of digits representing the user extension.
  • <sip-line-identity> is formatted like user@domain as seen in the phone web interface under Status > System Information.
  • <phone-http-auth> is one of basic or digest, depending on the phone’s HTTP server authentication settings, and <phone-username> and <phone-password> should match the phone credentials to support Promptar based call control.

The minimal Snom phone driver/extension setup is now complete. The connector operation should now be verified with test calls, along with the Promptar Server, Client and other components in the environment.

Once successful, other drivers/extensions can be added [9]; then, proceed to the Finalizing the Installation chapter.

4.7. Yealink Phones

Phone Configuration

Yealink phones need to be configured in order to notify the connector of call related events. Additionally, settings need to be enabled so as to support Promptar based call control. To do that, login to the phone’s web based administration interface and, under Features > Action URL, enter the settings in the table:

setting value

Incoming Call

<base-url>/incoming-call?local=$local&remote=$remote&callid=$call_id

Outgoing Call

<base-url>/outgoing-call?local=$local&remote=$remote&callid=$call_id

Established

<base-url>/call-established?local=$local&remote=$remote&callid=$call_id

Terminated

<base-url>/call-terminated?local=$local&remote=$remote&callid=$call_id

Transfer Call

<base-url>/transfer-call?local=$local&remote=$remote&callid=$call_id

Blind Transfer

<base-url>/blind-transfer-call?local=$local&remote=$remote&callid=$call_id

Attended Transfer

<base-url>/attended-transfer-call?local=$local&remote=$remote&callid=$call_id

Hold

<base-url>/hold?local=$local&remote=$remote&callid=$call_id

UnHold

<base-url>/unhold?local=$local&remote=$remote&callid=$call_id

Mute

<base-url>/mute?local=$local&remote=$remote&callid=$call_id

UnMute

<base-url>/unmute?local=$local&remote=$remote&callid=$call_id

Missed Call

<base-url>/missed-call?local=$local&remote=$remote&callid=$call_id

Reject Incoming Call

<base-url>/reject-incoming-call?local=$local&remote=$remote&callid=$call_id

Answer New Incoming Call

<base-url>/answer-new-incoming-call?local=$local&remote=$remote&callid=$call_id

Transfer Failed

<base-url>/transfer-failed?local=$local&remote=$remote&callid=$call_id

Transfer Finished

<base-url>/transfer-finished?local=$local&remote=$remote&callid=$call_id

Cancel Call Out

<base-url>/cancel-callout?local=$local&remote=$remote&callid=$call_id

Remote Busy

<base-url>/remote-busy?local=$local&remote=$remote&callid=$call_id

Call Remote Canceled

<base-url>/call-remote-canceled?local=$local&remote=$remote&callid=$call_id

Where <base-url> is the URL that the phones should use to issue HTTP requests reaching this connector, depending on the [http] section settings. A typical case is https://<username>:<password>@<promptar-host>:<port>/yealink/.

Next, under Features > Remote Control, add the IPv4 address of the system running the connector, so as to allow Promptar based call control.

Automated Configuration

When preparing a large set of phones, it is valuable to configure them in a centralized manner. Even though that is out of the scope of this document, the snippet below includes settings that can be used:

#!version:1.0.0.1

action_url.incoming_call            = {CONNECTOR_URL}/incoming-call?local=$local&remote=$remote&callid=$call_id
action_url.missed_call              = {CONNECTOR_URL}/missed-call?local=$local&remote=$remote&callid=$call_id
action_url.reject_incoming_call     = {CONNECTOR_URL}/reject-incoming-call?local=$local&remote=$remote&callid=$call_id
action_url.outgoing_call            = {CONNECTOR_URL}/outgoing-call?local=$local&remote=$remote&callid=$call_id
action_url.remote_busy              = {CONNECTOR_URL}/remote-busy?local=$local&remote=$remote&callid=$call_id
action_url.call_remote_canceled     = {CONNECTOR_URL}/call-remote-canceled?local=$local&remote=$remote&callid=$call_id
action_url.cancel_callout           = {CONNECTOR_URL}/cancel-callout?local=$local&remote=$remote&callid=$call_id
action_url.answer_new_incoming_call = {CONNECTOR_URL}/answer-new-incoming-call?local=$local&remote=$remote&callid=$call_id
action_url.call_established         = {CONNECTOR_URL}/call-established?local=$local&remote=$remote&callid=$call_id
action_url.call_terminated          = {CONNECTOR_URL}/call-terminated?local=$local&remote=$remote&callid=$call_id
action_url.transfer_call            = {CONNECTOR_URL}/transfer-call?local=$local&remote=$remote&callid=$call_id
action_url.blind_transfer_call      = {CONNECTOR_URL}/blind-transfer-call?local=$local&remote=$remote&callid=$call_id
action_url.attended_transfer_call   = {CONNECTOR_URL}/attended-transfer-call?local=$local&remote=$remote&callid=$call_id
action_url.transfer_finished        = {CONNECTOR_URL}/transfer-finished?local=$local&remote=$remote&callid=$call_id
action_url.transfer_failed          = {CONNECTOR_URL}/transfer-failed?local=$local&remote=$remote&callid=$call_id
action_url.hold                     = {CONNECTOR_URL}/hold?local=$local&remote=$remote&callid=$call_id
action_url.unhold                   = {CONNECTOR_URL}/unhold?local=$local&remote=$remote&callid=$call_id
action_url.held                     = {CONNECTOR_URL}/held?local=$local&remote=$remote&callid=$call_id
action_url.unheld                   = {CONNECTOR_URL}/unheld?local=$local&remote=$remote&callid=$call_id
action_url.mute                     = {CONNECTOR_URL}/mute?local=$local&remote=$remote&callid=$call_id
action_url.unmute                   = {CONNECTOR_URL}/unmute?local=$local&remote=$remote&callid=$call_id

features.action_uri.enable          = 1
features.show_action_uri_option     = 0
features.action_uri_limit_ip        = {CONNECTOR_HOST_IPv4}

Where {CONNECTOR_URL} and {CONNECTOR_HOST_IPv4} should be replaced with appropriate value for the environment. Note, also, the inclusion of the features.show_action_uri_option that forces phones to accept Promptar based call control commands without first prompting the user.

Connector Configuration

After configuring the phones, go back to the connector configuration file, scrolling to the [drivers] section, and uncomment the sample lines starting with yealink, there:

[drivers]

; yealink.server.id         = server1
; yealink.server.path       = /yealink
; yealink.handle.control    = strict
; yealink.client.protocol   = https

Then:

  • Adjust yealink.server.id to match the settings in the [http] section.
  • Set yealink.client.protocol according to the phones' HTTP server settings.

Once complete, scroll to the [extensions] section and add a set of lines like the following ones, per each extension to be configured. For initial testing, add no more than two or three [10].

<extension>.identity = yealink/<line-sip-url>
<extension>.auth     = <phone-http-auth>:<phone-username>:<phone-password>

Where:

  • <extension> will typically be a sequence of digits representing the user extension.
  • <line-sip-url> is a line URI formatted like sip:user@domain.
  • <phone-http-auth> is one of basic or digest, depending on the phone’s HTTP server authentication settings, and <phone-username> and <phone-password> should match the phone credentials to support Promptar based call control.

The minimal Yealink phone driver/extension setup is now complete. The connector operation should now be verified with test calls, along with the Promptar Server, Client and other components in the environment.

Once successful, other drivers/extensions can be added [11]; then, proceed to the Finalizing the Installation chapter.



[1] Uncomment and adjust the remaining server0 settings at will.

[2] Refer to the comment block preceeding this section in the file, for a concrete example.

[3] Refer to the appropriate sections in this chapter, for that.

[4] Refer to the comment block preceeding this section in the file, for a concrete example.

[5] Refer to the appropriate sections in this chapter, for that.

[6] Refer to the comment block preceeding this section in the file, for a concrete example.

[7] Refer to the appropriate sections in this chapter, for that.

[8] Refer to the comment block preceeding this section in the file, for a concrete example.

[9] Refer to the appropriate sections in this chapter, for that.

[10] Refer to the comment block preceeding this section in the file, for a concrete example.

[11] Refer to the appropriate sections in this chapter, for that.