Configuration options reference
This topic 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 the 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 VoIP infrastructure. This container has at least one connection (Connectivity) element with the following attributes:
<Connectivity user="DN" server="VOIP_NETWORK_ACCESS_POINT" protocol="TRANSPORT"/>
If you are using a configuration that supports Disaster Recovery and Geo-Redundancy, there may be multiple connection elements present with each specifying a separate possible connection. Refer to the configuration settings of that feature for details. You will have to make the following changes and save the updated configuration file before using the Genesys Softphone:
- user="DN"—Supply a valid DN for the user attribute.
- server="SERVER:PORT" or "SERVER"—Replace SERVER with the host name or IP Address of the Session Border Controller (SBC), and PORT with the SIP port of the SBC, when applicable. For SRV resolution, specify SERVER with 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 the SBC: "UDP" in PureEngage Cloud.
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 can not 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 can not use SRV records for the mailbox section or the vq_report_collector setting.
You will have to make the following changes and save the updated configuration file before using the Genesys Softphone:
- user="DN"—Supply a valid DN for the user attribute.
- server="WEBRTCGATEWAY_SERVER:WEBRTCGATEWAY_PORT?sip-proxy-address="SIPPROXY_SERVER:SIPPROXY_PORT"—Replace WEBRTCGATEWAY_SERVER with the host name where the WebRTC Gateway is deployed, and PORT with the HTTPS port of the WebRTC Gateway. Also, replace SIPPROXY_SERVER and SIPPROXY_PORT (optional) with the connectivity parameters of the SIP Proxy that need to be contacted by the WebRTC Gateway to register this DN.
- protocol="TRANSPORT"—Set the protocol attribute to reflect the protocol being used to communicate with the WebRTC Gateway: HTTPS.
|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 second Container ("Genesys") holds a number of configurable settings that are organized into domains and sections. These settings do not have to be changed, but can be customized.
An overview of the settings in this container and the valid values for these settings is provided here:
|include_os_version_in_user_agent_header||SIP only||Number||If set to 1, the user agent field includes the OS version the client is currently running on. Default: 1.|
|gui_call_lines||Number from 1 to 7|| This option controls the number of phone lines in the First Party Call Control tab.|
Valid values: Integer between 1 and 7
|gui_tabs||Comma-separated list of tab names|| This option controls what tabs are shown in the GUI and their order.|
Valid values: Comma-separated list of tab names in any order. The tab names are status, calls,and devices. Names may be shortened to stat, call, and dev. The value is case-sensitive. This option ignores unrecognizable and duplicate tab names. If the setting is present but has an incorrect value, the value will fall back to the single tab status.
|include_sdk_version_in_user_agent_header||SIP only||Number||If set to 1, the user agent field includes the SDK version the client is currently running on. Default: 1.|
|ip_versions||SIP only|| IPv4
| A value of IPv4 means that the application selects an available local IPv4 address; IPv6 addresses are ignored.
A value of IPv6 means that the application selects an available local IPv6 address; IPv4 addresses are ignored.
|public_address||SIP and WebRTC||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 may have one of the following special values:
Default Value: Empty string which is fully equivalent to the $auto value.
If the value is specified as an explicit host name, FQDN, or $fqdn, the Contact header includes the host name or FQDN for the recipient of SIP messages (SIP Server or SIP proxy) to resolve on their own. For all other cases, including $host, the resolved IP address is used for Contact. The value in SDP is always the IP address.
|include_mac_address||SIP only||Number||Default Value: 0. 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.|
|rtp_inactivity_timeout||SIP and WebRTC||Number||Timeout interval for RTP inactivity. Valid values are positive integers. A value of 0 means that this feature is not activated. A value 1 or higher indicates the inactivity timeout interval in seconds. Default: 0. Suggested values: 1 through 150.|
|rtp_port_min||SIP and WebRTC||Number||The integer value representing the minimum value for an RTP port range. Must be within the valid port range of 9000 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||SIP and WebRTC||Number||The integer value representing the maximum value for an RTP port range. Must be within the valid port range of 9000 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||SIP only||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||SIP only||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||SIP only||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||SIP only||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||SIP only||Number||SIP transaction timeout value in milliseconds. Valid values are 1 through 32000, with a default value of 4000. The recommended value is 4000.|
|vq_alarm_threshold||SIP and WebRTC||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||SIP only||See SIP Endpoint SDK for .NET—Producing RTCP Extended Reports|
|vq_report_publish||SIP only||See SIP Endpoint SDK for .NET—Producing RTCP Extended Reports|
|webrtc_audio_layer||SIP and WebRTC|| 0
| Valid values:|
0—the audio layer is defined by environment variable "GCTI_AUDIO_LAYER"
|agc_mode||SIP and WebRTC|| 0
| If set to 0, AGC (Automatic Gain Control) is disabled; if set to 1, it is enabled. Default: 1. Other values are reserved for future extensions. This configuration is applied at startup, after which time the agc_mode setting can be changed to 1 or 0 from the main sample application.
NOTE: It is not possible to apply different AGC settings for different channels in multi-channel scenarios.
|auto_answer||SIP and WebRTC||Number||If set to 1, all incoming calls should be answered automatically.|
|dtmf_method||SIP and WebRTC|| Rfc2833
|Method to send DTMF|
|echo_control||SIP and WebRTC|| 0
|Valid values: 0 or 1. If set to 1, echo control is enabled.|
|noise_suppression||SIP and WebRTC|| 0
|Valid values: 0 or 1. If set to 1, noise suppresion is enabled.|
|dtx_mode||SIP and WebRTC||Number||Valid values: 0 or 1. If set to 1, DTX is activated.|
|reject_session_when_headset_na||SIP and WebRTC||Number||Valid values: 0 or 1. If set to 1, the GSP should reject the incoming session if a USB headset is not available.|
|sip_code_when_headset_na||SIP only||Number|| Defaul Value: 480|
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||SIP and WebRTC||Number||Sets the degree of bandwidth reduction. Valid values: 0 – 3 — from 0 (conventional VAD) to 3 (aggressive high).|
|ringing_enabled||SIP and WebRTC||Number|| Valid values: 0, 1, 2, 3, or 4.|
0 = None, disable ringtone
|ringing_timeout||SIP and WebRTC||Number|| Valid Values: Empty, 0, or a positive number|
Default Value: 0
|ringing_file||SIP and WebRTC||String|| Valid values: Empty or the path to the ringing sound file for the audio out device (headset). The path may be a file name in the current directory or the full path to the sound file.|
Default Value: ringing.wav
kWavFormatPcm = 1, PCM, each sample of size bytes_per_sample
|audio_in_device||SIP and WebRTC||String||Microphone device name: can be either the device proper name or a regular expression.|
|audio_out_device||SIP and WebRTC||String||Speaker device name: can be either the device proper name or a regular expression.|
|ringer_device||SIP and WebRTC||String||Ringer device name: can be either the device proper name or a regular expression. Used when ringing_enabled = 4|
|headset_name||SIP and WebRTC||String||
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||SIP and WebRTC||Number||Valid values: 0 or 1. 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||SIP and WebRTC||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||SIP and WebRTC||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||SIP and WebRTC||String||The thumbprint of a valid certificate that is accessible from the Certificate Store of the workstation where Softphone is running.|
|enable_sessionid||SIP and WebRTC||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||SIP and WebRTC||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||SIP only||String||Proxy display name|
|password||SIP only||String||Proxy password|
|reg_interval||SIP and WebRTC||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||SIP only||Number|| DEPRECATED
Valid Values: 0 or 1
|reg_timeout||SIP only||Number||The period, in seconds, after which registration should expire. 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||SIP only||Boolean||Enable or disable ICE|
|stun_server||SIP only||String||STUN server address. An empty or null value indicates this feature is not being used.|
|stun_server_port||SIP only||String||STUN server port value|
|turn_password||SIP only||Number||Password for TURN authentication|
|turn_relay_type||SIP only||Number||Type of TURN relay|
|turn_server||SIP only||String||TURN server address. An empty or null value indicates this feature is not being used.|
|turn_server_port||SIP only||String||TURN server port value|
|turn_user_name||SIP only||String||User ID for TURN authorization|
|enable_logging||SIP and WebRTC||Number||Valid values: 0 or 1. Disable or enable logging.|
|log_file||SIP and WebRTC||String||Log file name, for example, SipEndpoint.log|
|log_level||SIP and WebRTC||Number||Valid values: 0 – 4. Log levels: 0 = "Fatal"; 1 = "Error"; 2 = "Warning"; 3 = "Info"; 4 = "Debug".|
|log_options_provider||SIP and WebRTC||String||Valid values for webrtc = (warning, state, api, debug, info, error, critical). For example: gsip=2, webrtc=(error,critical)|
|logger_type||SIP and WebRTC||file||If set to file, the log data will be printed to the file specified by the log_file parameter.|
|log_segment||SIP and WebRTC|| false
Number in KB,MB, or hr
| Valid Values:|
false: No segmentation is allowed
|log_expire||SIP and WebRTC|| false
| Valid Values:|
false: No expiration; all generated segments are stored.
|log_time_convert||SIP and WebRTC|| local
| Valid Values:|
local: The time of log record generation is expressed as a local time, based
on the time zone and any seasonal adjustments. Time zone information of the application’s host computer is used.
|log_time_format||SIP and WebRTC|| time
| Valid Values:|
time: The time string is formatted according to the HH:MM:SS.sss (hours, minutes, seconds, and milliseconds) format
|cert_file||String||Thumbprint value of the Public endpoint certificate file, which is used as a client-side certificate for outgoing TLS connection 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|
|tls_enabled||Number||If set to 1, connection with TLS transport will be registered. Default: 0.|
|use_srtp||SIP only|| String
|Indicates whether to use SRTP (Secure RTP is always automatically enabled for WebRTC)|
|ringing_file||SIP and WebRTC||String|| Valid Values: Empty or String file name|
Defaul Value: ringing.mp3