Configuration Options Reference
This article lists and describes, by container and then by domain, the configuration settings found in the '<Genesys Softphone Installation Directory>\Softphone.config' file. For an example of the configuration file, see Configuring Genesys Softphone.
The Softphone.config file is installed, along with genesys_softphone.exe, by either the Genesys Installation Wizard or silently by command line. The contents of the Softphone.config file is generated by the choices specified in the wizard or by modifications made to the genesys_silent.ini file.
In the Softphone.config file, the following attributes of the Connector section are set by setup.exe: protocol, port, and certificate_search_value, while enable_sessionid, auto_restart are not. The default value of these attributes are designed to address most business deployments. However, if you want to adjust their values, follow these steps to make a custom deployment:
- Install Genesys Softphone on an administrator's machine.
- Edit the Softphone.config file to change the values of the attributes in the Connector section.
- Repackage Genesys Softphone with the custom Softphone.config file through an IT-controlled installation.
- Push the custom package to the agent workstations.
The first container ("Basic") holds the basic connectivity details that are required to connect to your SIP Server. This container has at least one connection (Connectivity) element with the following attributes:
<Connectivity user="DN" server="SERVER:PORT" protocol="TRANSPORT"/>
If you are using a configuration that supports Disaster Recovery and Geo-Redundancy, there can be multiple connection elements present, with each element specifying a separate possible connection. Refer to the configuration settings of that feature for details.
You must make the following changes and save the updated configuration file before using Genesys Softphone:
- user="DN": Supply a valid DN for the user attribute.
- server="SERVER:PORT": Replace SERVER with the host name where your SIP Server is deployed, and PORT with the SIP port of the SIP Server host. The default SIP port value is 5060. For SRV resolution, specify the SRV record without including the port number in the server's URI. Also see SRV Resolution below.
- protocol="TRANSPORT": Set the protocol attribute to reflect the protocol being used to communicate with SIP Server. Possible values are UDP, TCP, or TLS.
When using an SRV record for the server parameter, note the following:
- Do not specify the port in the server URI.
- Genesys Softphone does not take into account the weight field of an SRV record.
- You cannot combine IPv4 and IPv6 for a single FQDN.
- The maximum number of targets (SRV records) per service is 20.
- You can only specify SRV records in the server parameter of the Connectivity element. You cannot use SRV records for the mailbox section or the vq_report_collector setting.
|Connectivity||user||The first user's DN extension as configured in the configuration database. Included in the SIP URI. For example, <sip:DN0@serverHostName0:port0>|
|server||The SIP Server or Proxy location for the first user. Included in the SIP URI. For example, <sip:DN0@serverHostName0:port0>|
|protocol||The transport procotcol for the first user. For example, UDP, TCP, or TLS.|
|For more information, see the Basic Container description in the SIP Endpoint SDK for .NET Developer's Guide.|
The "Genesys" container holds a number of configurable settings that are organized into domains and sections. You don't have to change these settings but you can customize them.
The following table presents an overview of the settings in this container and their valid values:
|defer_device_release||Integer|| Specifies a time in milliseconds before releasing audio devices after the audio stream has been stopped. Deferring device release avoids potential service interruptions if the audio will be restarted quickly and if audio device operations are too slow on the user workstation or has other problems with restart. The value 0 disables deferred device release.
|gui_call_lines||Number from 1 to 7|| This option controls the number of phone lines in the First Party Call Control tab.
|gui_tabs||Comma-separated list of tab names|| This option controls what tabs are shown in the GUI and their order.
|include_mac_address||Number|| If set to 1, the MAC address is included in the Contact header of the REGISTER message of the host's network interface in a format compatible with RFC 5626.
|include_os_version_in_user_agent_header||Number|| If set to 1, the user agent field includes the OS version the client is currently running on.
|include_sdk_version_in_user_agent_header||Number|| If set to 1, the user agent field includes the SDK version the client is currently running on.
|public_address||String|| Local IP address or Fully Qualified Domain Name (FQDN) of the machine. This setting can be an explicit setting or a special value that the GSP uses to automatically obtain the public address.
This setting can have one of the following special values:
Default value: Empty string which is fully equivalent to the $auto value.
|rtp_inactivity_timeout||Number|| Timeout interval in seconds for RTP inactivity.
|rtp_port_min||Number||The integer value representing the minimum value for an RTP port range. Must be within the valid port range of 1 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (9000) and maximum (minimum value + 999) are used. Setting the minimum to a value that is larger than the maximum is considered an error and will result in a failure to initialize the endpoint.|
|rtp_port_max||Number||The integer value representing the maximum value for an RTP port range. Must be within the valid port range of 1 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (9000) and maximum (minimum value + 999) are used. Setting the maximum to a value that is less than the minimum is considered an error and will result in a failure to initialize the endpoint.|
|tcp_port_min||Number||The integer value representing the minimum value for a TCP client-side port range. Must be within the valid port range of 1 to 65535. If set to 0 (default) or if the configured range is not valid, SIP connections over TCP and TLS use ephemeral ports, assigned by the operating system.|
|tcp_port_max||Number|| The integer value representing the maximum value for a TCP client-side port range. Must be within the valid port range of 1 to 65535.
If set to 0 (default) or if the configured range is not valid, SIP connections over TCP and TLS use ephemeral ports, assigned by the operating system.
If the value is non-zero and greater than the tcp_port_min value, this value specifies the maximum value for a TCP client-side SIP port range that will be used for all outgoing SIP connections over TCP and TLS transport.
|sip_port_min||Number||The integer value representing the minimum value for a SIP port range. Must be within the valid port range of 1 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (5060) and maximum (minimum value + 6) are used. Setting the minimum to a value that is larger than the maximum is considered an error and will result in a failure to initialize the endpoint.|
|sip_port_max||Number||The integer value representing the maximum value for a SIP port range. Must be within the valid port range of 1 to 65535. If the minimum and maximum values are not specified or are set to an invalid value, the default minimum (5060) and maximum (minimum value + 6) are used. Setting the maximum to a value that is less than the minimum is considered an error and will result in a failure to initialize the endpoint.|
|sip_transaction_timeout||Number|| SIP transaction timeout value in milliseconds.
|vq_alarm_threshold||0 (default) or number from 1.0 to 5.0||Specifies Mean Opinion Score (MOS — a measure of reported network quality ratings) threshold for generating Voice Quality Alarms. The value 0 disables the alarms. The recommended threshold value is 3.5. Using values above 4.2 are not recommended as an MOS that high might not be obtainable with some codecs, even under perfect network conditions.|
|vq_report_collector||See SIP Endpoint SDK for .NET—Producing RTCP Extended Reports|
|vq_report_publish||See SIP Endpoint SDK for .NET—Producing RTCP Extended Reports|
| Valid values:
| If set to 0, AGC (Automatic Gain Control) is disabled; if set to 1, it is enabled. Other values are reserved for future extensions. This configuration is applied at startup, after that the agc_mode setting can be changed to 1 or 0 from the main sample application.
| Enables and disables Receiving-side Automatic Gain Control (Rx AGC). [Added: 9.0.xxx.xx]
|auto_answer||Number||If set to 1, all incoming calls are answered automatically.|
|Method to send DTMF|
|Valid values: 0 or 1. If set to 1, echo control is enabled.|
|Valid values: 0 or 1. If set to 1, noise suppression is enabled.|
|dtx_mode||Number||Valid values: 0 or 1. If set to 1, DTX is activated.|
|reject_session_when_headset_na||Number||Valid values: 0 or 1. If set to 1, the GSP rejects the incoming session if a USB headset is not available.|
|sip_code_when_headset_na||Number|| If a valid SIP error code is supplied, the GSP rejects the incoming session with the specified SIP error code if a USB headset is not available.
|vad_level||Number|| Sets the degree of bandwidth reduction.
|ringing_enabled||0, 1, 2, 3, or 4|| Specifies whether to enable the ringtone and on which device to play the media file.
|ringing_timeout||Number|| Specifies the duration, in seconds, of the ringtone. If set to 0 or if the value is empty, the ringing time is unlimited.
|ringing_file||String|| Specifies the audio file that is played in the audio out device (headset) when the ringtone is enabled with the ringing_enabled option.|
Note that WebRTC does not support MP3 playback. The ringtone file for built-in ringing is a RIFF (little-endian) WAVE file using one of the following formats:
Uncompressed PCM audio must 16 bit mono or stereo and have a frequency of 8, 16, or 32 KHZ.
|ringback_enabled||0, 1, 2, 3, 4, or 6|| Specifies how the ringback feature is enabled.
|ringback_file||Empty or a valid path to a 16-bit 8-, 16-, or 32-Khz .wav sound file.||Specifies the audio file that is played when the ringback_enabled option is configured to play a local file as the ringback tone.|
|audio_in_device||String||Microphone device name: can be either the device proper name or a regular expression.|
|audio_out_device||String||Speaker device name: can be either the device proper name or a regular expression.|
|ringer_device||String||Ringer device name: can be either the device proper name or a regular expression. Used when ringing_enabled = 4|
The name of the headset model: can be either the device proper name or a regular expression. When the value of the use_headset option is set to 1, you can set the value of this option to *, the default value, to select the default headset. If the value of this option is empty, this option is not considered as a regular expression and will fail to find a headset.
|use_headset||Number|| If set to 0, the audio devices specified in audio_in_device and audio_out_device are used by the Genesys Softphone. If set to 1, the Genesys Softphone uses a headset as the preferred audio input and output device and the audio devices specified in audio_in_device and audio_out_device are ignored.
|protocol||String||Valid values: http or https. Specifies whether the HTTP requests sent from HTTP client (typically WWE running in a browser) are secured. If set to a non-empty value the option port must be populated with a valid port number. If set to https, the option certificate_search_value must be populated with a valid certificate thumbprint.|
|port||Number||The port that Softphone is opening at start-up time to listen to HTTP or HTTPS requests sent by the HTTP Client (typically WWE running in a browser). If sent to empty value (default) the connector is not activated and Softphone runs in regular standalone GUI mode.|
|certificate_search_value||String||The thumbprint of a valid certificate that is accessible from the Certificate Store of the workstation where Softphone is running.|
|enable_sessionid||Number||Valid values: 0 or 1. If set to 1 (default), a SESSION_ID attribute is generated in the header of the HTTP response returned to the HTTP Client (typically WWE running in a browser).|
|auto_restart||Number||Valid values: 0 or 1. If set to 1 (default) the Softphone must be restarted after every client session.|
codecs— See SIP Endpoint SDK for .NET 9.0.0NET—Working with Codec Priorities.
|display_name||String||Proxy display name|
|reg_interval||Number|| The period, in seconds, after which the endpoint starts a new registration cycle when a SIP proxy is down. Valid values are integers greater than or equal to 0. If the setting is empty or negative, the default value is 0, which means no new registration cycle is allowed. If the setting is greater than 0, a new registration cycle is allowed and will start after the period specified by regInterval.|
ImportantThe re-registration procedure uses a smaller timeout (half a second) for the first re-try only, ignoring the configured reg_interval setting; the reg_interval setting is applied to all further retries.
|reg_match_received_rport||Number|| DEPRECATED: This setting controls whether or not Genesys Softphone re-registers itself when receiving a mismatched IP address in the received parameter of a REGISTER response. This helps resolve the case where the Genesys Softphone has multiple network interfaces and obtains the wrong local IP address. A value of 0 (default) disables this feature and a value of 1 enables re-registration.
|reg_timeout||Number||The period, in seconds, after which registration expires. A new REGISTER request will be sent before expiration. Valid values are integers greater than or equal to 0. If the setting is 0 or empty/null, then registration is disabled, putting the endpoint in standalone mode.|
|ice_enabled||Boolean||Enable or disable ICE|
|stun_server||String||STUN server address. An empty or null value indicates this feature is not being used.|
|stun_server_port||String||STUN server port value|
|turn_password||Number||Password for TURN authentication|
|turn_relay_type||Number||Type of TURN relay|
|turn_server||String||TURN server address. An empty or null value indicates this feature is not being used.|
|turn_server_port||String||TURN server port value|
|turn_user_name||String||User ID for TURN authorization|
|enable_logging||Number|| Disable or enable logging.
|log_file||String||Log filename, for example, SipEndpoint.log|
|log_file_ctx||String||Specifies the absolute path and log filename to be created. If this option is not present or is empty, is an invalid path, or has no name, no log file is created on the client side.|
|log_level||Number|| Valid values: 0 – 4|
Log levels: 0 = "Fatal"; 1 = "Error"; 2 = "Warning"; 3 = "Info"; 4 = "Debug".
|log_options_ctx||Number|| Specifies whether the virtual driver logs are generated on the Citrix Server side or on the client host side.
|log_options_provider||String||Valid values for webrtc = (warning, state, api, debug, info, error, critical). For example: gsip=2, webrtc=(error,critical)|
|logger_type||file||If set to file, the log data will be printed to the file specified by the log_file parameter.|
Number in KB,MB, or hr
| Specifies the segmentation limit for a log file. If the current log segment exceeds the size set by this option, the file is closed and a new one is created. This option is ignored if log output is not configured to be sent to a log file.
| Determines whether log files expire. If they do, sets the measurement for
determining when they expire, along with the maximum number of files (segments) or days before the files are removed. This option is ignored if log output is not configured to be sent to a log file.
| Specifies the system in which an application calculates the log record time when generating a log file. The time is converted from the time in seconds since the Epoch (00:00:00 UTC, January 1, 1970).
| Specifies how to represent, in a log file, the time when an application generates log records. A log record’s time field in the ISO 8601 format looks like this: 2001-07-24T04:58:10.123.
|certificate||String||Thumbprint value of the Public endpoint certificate file, which is used as a client-side certificate for outgoing TLS connections and server-side certificate for incoming TLS connections. For example: 78 44 34 36 7a c2 22 48 bd 5c 76 6b 00 84 5d 66 83 f5 85 d5|
allowed disabled off elective both enabled force mandatory
| Indicates whether to use SRTP (Secure Real-Time Transport Protocol) [Modified: 9.0.005.06]
Adding either ',UNENCRYPTED_SRTCP' (long form) or ',UEC' (short form) to any value (for example, 'enabled,UEC'), adds the UNENCRYPTED_SRTCP parameter to that offer. When this parameter is negotiated, RTCP packets are not encrypted but are still authenticated.
|tls-target-name-check||Boolean|| Enables a case-insensitive comparison of the TLS host name and the certificate’s subject field during the authentication process. This option is transferred to a third-party library and describes whether it is necessary or not to check the names.
|ringing_file||String|| The Ringing sound filename in the current directory or the full local path to the ringing sound file. Specifies the audio file that is played in the defualt audio device (speakers) when the default device ringtone is enabled with the ringing_enabled option.
For more information about these options, see SIP Endpoint SDK for .NET Developer's Guide.