1.11 Voipbox (windows only)

VoipBox is one of the core VoipSwitch components, responsible for processing multimedia files and streams. In every case, when multimedia content flows from server, VoipBox acts as a streamer or transcoder, besides exceptions when media over web interface (such as VUP or VUC), can be processed as they are (without transcoding).

Files structure:

The engine, configuration and media files are located in its installation directory - usually: C:\Program Files (x86)\VoipBox*, unless other location was selected during installation. VoipBox installation path needs to be included in configuration files of other VoipSwitch modules, as they communicate, write and read files directly to VoipBox environment. In case of deployment distributed to several servers its recommended to install VoipBox on the machine that handles web services due to the need of mentioned direct communication, otherwise required access to VoipBox directories must be supplied over network resources.

Folders:

\application-data\language - Language media files evoked by IVR scenarios ie |You have|five|dollars|. Stored in WAVE format.
\application-data\scenario - Files containing IVR scenario instructions, stored in XML format. In most cases factory set of scenarios is sufficient for carriers to support their desired IVR services, but its possible to customize existing or write new scenario in case of needs that can not be covered by factory set.
\call_recordings - Customers calls recorded by Call Recording service. Default format AMR, configurable in voipbox_config.xml/<listener type="call-recorder">
\faxes - Fax files received by FaxBox service and sent over web (VUP, VUC) interface or Email2Fax service. Files are being written and stored by VoipBox in .FAX format and converted with help of ImageMagick to other common graphic formats required by web modules.
\grammar - Grammar libraries of languages supported by VoipBox .
\greetings - Enduser media files used as custom recordings for Voicemail, Music On Hold, Call Waiting services. Managed usually from My Profile level of user portal. Stored by default in Mp3 format.
\pbx_waves - PBX enduser media files used in PBX scenarios. Stored by deault in Mp3 format.
\logs - VoipBox logs folder.
\temp - temp directory used for media conversions.

Setup:

VSM: Settings : System : VoipBox

Files storage - path to the folder where relevant VoipBox files are stored. Such folder should contain following sub-folders: scenarios, languages, messages, greetings, call_recordings, faxes, pbx_waves (required by a PBX module)
Maximum number length - maximum length of a number processed by the VoipBox scenario, either a PIN or a dialed number ("0" means unlimited
Non activity timeout - the time after which either the announcement will be repeated, passed number will be processed (if not followed by the finish key) or a call to VoipBox scenario will be disconnected. Should be set to non-zero value
Finish key - a key with which a person calling to the VoipBox scenario should confirm the typed number (by default set as a pound key "#"), eg. after registering with a PIN or dialing a number via the scenario, if the Finish key is set to "#", dialed number should look like "12345#"
Redial string - a string of characters indicating the last dialed number should be redialed again - if the calling person is connected to the VoipBox scenario (by default set as "*#")
End call string - a string of characters using which a call made via the VoipBox scenario can be disconnected without disconnecting the calling party from the scenario so the next number can be dialed (by default set as "##")
Non activity retries - a number determining how many times the announcement should be repeated if there is no action from the calling party end
Wrong pin retries - number of retries available if the incorrect PIN has been passed
Time multiplier - changes the time announced to the customer that can be utilized for a call (dependent on the account state and voice rate for the called number) by multiplying the original value Time multiplier allows defining different time multipliers for different client LOTs.
Time addition - similar to the Time multiplier but adds a number of seconds to the announced time (it can't be assigned to different LOTs like a previous feature)
Round time to minutes - rounds the announced time to minutes (doesn't announce seconds)
Silence duration - time in seconds after which the calling person will hear the announcement
Use client's account to recharge - enables the feature of recharging customer's account using other customer account, like IVR or Retail, using one of VoipBox Recharge scenarios. In such case IVR/Retail client account that is a source of the recharge is treated as a recharge PIN
Ani storing exceptions- disables customers from adding ANI numbers specified in the field. Subsequent number should be separated by "|" sign, for example: anonymous|none|442081369011;

Remaining configuration settings are contained in voipbox_config.xml file, stored in main VoipBox directory. The file defines listeners configuration, audio codecs parameters and database connection details. As VoipBox reads configuration only during startup, any configuration change should be followed by restart of the module. Its important to copy final state of voipbox_config.xml to voipbox_routes stored in main VoipSwitch installation directory and remember to reflect any further change to this location.

Listeners:

voipbox - Port where VoipSwitch sends requests to evoke scenarios, used also by web modules to trigger media conversions.
audio-rtp - Port used for media streaming VoipBox<->VoipSwitch while executing scenarios.
fax-t38 - Port handling FAX transmission
audio-mergerOFF - Port handling “audio events”
audiotranscoderOFF - Port handling transcoding for certain audio codec. One port is dedicated only for one type of codec. For several codecs the port must be defined multiple times on following ports (as on example below). Transcoding service consumes significant volume of CPU resources, therefore in case of need to transcode many concurrent calls, its recommended to run several VoipBox instances on separate / dedicated servers where each instance is dedicated only for selected codec. In such case it's important to reflect the change of listening ports configuration in voipbox_routes/voipbox_config.xml stored in main VoipSwitch installation directory.

Example where one VoipSwitch instance used two VoipBox instances for transcoding:

Server-Box1:
    <listener type="audio-transcoderOFF">
        <param name="ipaddr" value="10.0.0.3" />
        <param name="port" value="2060" />
        <param name="transport" value="udp" />
        <param name="output-codec" value="g711u" />
    </listener>
     Serwer-Box2:
    <listener type="audio-transcoderOFF">
        <param name="ipaddr" value="10.0.0.4" />
        <param name="port" value="2062" />
        <param name="transport" value="udp" />
        <param name="output-codec" value="g711a" />
    </listener>
/voipswitch*/voipbox_routes - this single file contains listeners configuration from files on both voipbox servers
    <listener type="audio-transcoderOFF">
        <param name="ipaddr" value="10.0.0.3" />
        <param name="port" value="2060" />
        <param name="transport" value="udp" />
        <param name="output-codec" value="g711u" />
    </listener>
    <listener type="audio-transcoderOFF">
        <param name="ipaddr" value="10.0.0.4" />
        <param name="port" value="2062" />
        <param name="transport" value="udp" />
        <param name="output-codec" value="g711a" />
    </listener>

codecs - defines payload definition for codecs supported by VoipBox.
database - contains database connection details.

Scenarios

The main VoipBox purpose is to handle IVR services defined by scenarios. Each scenario is a script containing instruction which can be described as conditional or unconditional sequence of events. Most of scenarios required intended configuration, starting from dedicated DID number in routing plan. Other, system scenarios are triggered automatically under certain conditions. In many cases, for a particular type of IVR service you can choose between several scenarios, where the main common thread bears various options as described below.

IVR services and dedicated scenario groups

/wiki/spaces/doc/pages/306872592 Callback.

Scenarios containing element "PIN" as a part of their name are dedicated for calling cards services requiring customers authorization by providing their PIN number.

Scenarios containing element "Ask for number" without element "PIN" as a part of their name are dedicated for callback services in case when customers are recognized by their CLI number

Other scenarios containing above, common elements as a part of their names allow to enable additional options for certain service

Scenario names consisted of different elements are joined by + character. Usually their names are self described.

Possible options:

PIN - basing scenario with authorization. Customer is requested for authorization by PIN number and then for destination number.
Additional options for PIN scenario:
Account - provides account state
Time - provider maximal time of connection for destination number basing on user account state and tariff rate.
Register - saves customer CLI to the system, on further calls customer will be recognized by CLI without a need to provide PIN number.
Only once - by default, after call is disconnected by remote party, customer is requested to provide destination number for next call. With option "only once" disconnection by remote party will finish IVR scenario and disconnect originating side.
Select language - provides ability to select language for IVR prompts.
PIN ANI_only - optional scenario that authorizes customers only by CLI number. Despite "PIN" element as a part if its name, PIN authorization is not allowed.
no ANI - omits authorization by CLI number, always requires PIN number
Recharge - provides ability to recharge account
One stage - specific scenario for services provided in cooperation with source carrier. In case of "one stage" based services, destination number is being indicated directly by source carrier, therefore "ask for number" element is ommited in its basic sequence.

Sip clients scenarios:

Account state - provides account state
Recharge - provides ability to recharge by PIN code.
Recharge + account state provides ability to recharge by PIN code and informs about account state
Voicemail Management - Provides ability to check voicemail messages and to manage voicemail greeting (after greeting record, there is need to set recorded welcome message in Find Me rule for use it)
Voicemail welcome greeting - provides ability to record voicemail greeting (there is need to set recorded welcome message in Find Me rule for use it)
Fax receive - system scenario dedicated for FaxBox service
Fax send - scenario dedicated for web2fax and email2fax service
Say verification code - dedicated for RCS account activation service
Time + call - provides maximal possible time of connection for destination number basing on account state and tariff rate
PBX is scenario handling DID numbers for PBX customers. It's part of extended structure, controlled by VUC, therefore it shouldn't be configured manually. Basically number is being assigned to the scenario by system when it's purchased by customer over VUC. From technical point of view, after purchase, system inserts the number to tables: 'portal_clientdids' and 'dialingplan' and then destination point of the number is added to table 'pbx_dialingplan'. In case of any problem related to inbound routing on PBX numbers, these are three basic tables that should be checked for diagnostic purposes.

Simple IVR scenarios configuration

Basic sip clients scenario configuration such as Voicemail Management, Recharge or Account state, requires 2 simple steps
-add local (short) number to routing plan
-include same number in customers tariff (usually with free rate

Detailed configuration for scenarios belonging to IVR services has been described on dedicated pages.

Voipswitch

1.11 Voipbox (windows only)

Related content