Jump to: navigation, search

Genesys Softphone configuration options

This article lists and describes, by container and then by domain, the configuration settings in the <Genesys Softphone Installation Directory>\Softphone.config file. For an example of the configuration file, see Configuring Genesys Softphone. It also describes how to configure Genesys Softphone to work with the audio devices that you use in your environment.

When you install Genesys Softphone, either by using the Genesys Installation Wizard or silently by command line, the Softphone.config and genesys_softphone.exe files are both installed. The contents of the Softphone.config file is generated by the choices you specify in the wizard or by modifications you make to the genesys_silent.ini file.

In the Softphone.config file, the setup.exe executable sets the values of the following attributes of the Connector section: protocol, port, and certificate_search_value. The enable_sessionid and auto_restart are not set by the executable; you must set these yourself. The default values 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:

  1. Install Genesys Softphone on an administrator's machine.
  2. Edit the Softphone.config file to change the values of the attributes in the Connector section.
  3. Repackage Genesys Softphone with the custom Softphone.config file through an IT-controlled installation.
  4. Push the custom package to the agent workstations.
Tip
If you use Workspace Web Edition with Genesys Softphone, use the Workspace SIP Endpoint options to set up your environment.

Basic container

The Basic container holds the connectivity details that are required to connect to your SIP Server, optionally through a Session Border Controller (SBC). 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 or SBC is deployed, and PORT with the SIP port of the SIP Server or SBC 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 or SBC. Possible values are UDP, TCP, or TLS.

SRV resolution

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.
Important
Your environment can have up to six SIP URIs (Connectivity sections) that represent six endpoint connections with SIP Server.
Domain Section Setting Default value Description
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 protocol 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 and SIP Endpoint SDK for OSX Developer's Guide.

Genesys container

The Genesys container holds 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 describes the settings in this container and their valid values:

Domain Section Setting Values Description
policy
endpoint
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.


Default Value: 200

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.
Default value: 3

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 can 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.
Default value: status,calls,devices

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.


Default value: 0

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.


Default value: 1

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.


Default value: 1

ip_versions IPv4

IPv6
IPv4,IPv6
IPv6,IPv4
empty

  • 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.
  • A value of IPv4,IPv6 or an empty value means that the application selects an IPv4 address if one exists. If not, an available IPv6 address is selected.
  • A value of IPv6,IPv4 means that the application selects an IPv6 address if one exists. If not, an available IPv4 address is selected.


Default value: IPv4
NOTE: This parameter has no effect if the public_address option specifies an explicit IP address.

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.


Valid values:
This setting can have one of the following explicit values:

  • An IP address. For example, 192.168.16.123 for IPv4 or FE80::0202:B3FF:FE1E:8329 for IPv6.
  • A bare host name or fully qualified domain name (FQDN). For example, epsipwin2 or epsipwin2.us.example.com.

This setting can have one of the following special values:

  • $auto: The GSP selects the first valid IP address on the first network adapter that is active (status=up) and specifies the default gateway. IP family preference is specified by the policy.endpoint.ip_versions setting.
  • $ipv4 or $ipv6: Same behavior as the $auto setting but the GSP restricts the address to a particular IP family.
  • $host: The GSP retrieves the standard host name for the local computer using the gethostname system function.
  • $fqdn: The GSP retrieves the fully qualified DNS name of the local computer. The GSP uses the GetComputerNameEx function with parameter ComputerNameDnsFullyQualified.
  • $net:<subnet> Where 'subnet' is a full CIDR name, as per RFC 4632. For example, '$net:192.168.0.0/16'. The first valid IP address that belongs to the specified subnet is selected. To support a dynamic VPN connection, Genesys Softphone does not start registration attempts until the interface (configured by adapter name or subnet) is available.
  • An adapter name or part of an adapter name prefixed with $. For example, $Local Area Connection 2 or $Local. The specified name must be different from the special values $auto, $ipv4, $host, and $fqdn.

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.

rtp_inactivity_timeout Number Timeout interval in seconds for RTP inactivity.


Valid values: Integers from 5 to 150.
Default value: 150
Suggested value: 30

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.


Valid values: 1 through 32000.
Default value: 32000 (starting from release 9.0.018.06; for previous releases: 4000)
Recommended value: 32000

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 9.0.0NET—Producing_RTCP_Extended_Reports and SIP Endpoint SDK for OSX—Producing RTCP Extended Reports.
vq_report_publish See SIP Endpoint SDK for .NET 9.0.0NET—Producing_RTCP_Extended_Reports and SIP Endpoint SDK for OSX—Producing RTCP Extended Reports.
webrtc_audio_layer 0
1
2
500
501
502
1000
1001
1002
2000
2001
2002
3000
3001
3002
Valid values:
  • 0: The audio layer is defined by the GCTI_AUDIO_LAYER environment variable — Core audio is used if this environment variable is not specified.
  • 1: Wave audio layer is used.
  • 2: Core audio layer is used.
  • 500: The audio layer ensures that Microsoft Windows MultiMedia Class Scheduler Service (MMCSS) is kept alive by the system independent of the actual audio activity on input and output devices. It can be combined with the values 0, 1, or 2 (500, 501, or 502) to specify the type of audio layer.
  • 1000: Instructs the audio layer to open the microphone channel when the endpoint starts up, using the audio layer type defined by option 0, and to keep it open until the endpoint is terminated. It can be combined with the values 0, 1, or 2 (1000, 1001, or 1002) to specify the type of audio layer.
  • 2000: Opens the speaker channel for the life of the endpoint, using the audio layer type defined by option 0. Eliminates any delay in opening the audio device when an incoming or outgoing call is connected, for example in environments where audio device startup is slow due to a required restart of the Windows MMCSS service. It can be combined with the values 0, 1, or 2 (2000, 2001, or 2002) to specify the type of audio layer.
  • 3000: Opens the microphone and speaker channels for the life of the endpoint, using the audio layer type defined by option 0. It can be combined with the values 0, 1, or 2 (3000, 3001, or 3002) to specify the type of audio layer.
session
agc_mode 0

1

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.


Default value: 1
NOTE: It is not possible to apply different AGC settings for different channels in multi-channel scenarios.

rx_agc_mode 0

1

Enables and disables Receiving-side Automatic Gain Control (Rx AGC).
  • 0: Disables the feature (default).
  • 1: Enables Receiving-side AGC, resulting in automatic adjustment of the volume of the received RTP stream. This ensures that the volume of all calls is adequate for agents to hear the contact.
auto_answer Number If set to 1, all incoming calls are answered automatically.
callwait_tone_enabled 0

1

Valid Values: 0, 1
Default Value: 1
Specifies whether the call waiting tone is enabled (1) or disabled (0). This configuration is applied at startup.

callwait_tone_file String

Valid Values: Empty, or the path to the call waiting sound file. The path may be a file name in the current directory or the full path to the sound file.
Default Value: callwait.wav
Specifies the audio file that is played when the call waiting tone is enabled by the callwait_tone_enabled option.
Note: WebRTC does not support MP3 playback. The callwait file for built-in ringing should be a RIFF (little-endian) WAVE file using one of the following formats:

  • kWavFormatPcm = 1, PCM, each sample of size bytes_per_sample
  • kWavFormatALaw = 6, 8-bit ITU-T G.711 A-law
  • kWavFormatMuLaw = 7, 8-bit ITU-T G.711 mu-law

Uncompressed PCM audio must 16-bit mono or stereo, and have a frequency of 8, 16, or 32 kHz.

dtmf_feedback 0

1

Valid values: 0 or 1 (default). If set to 1, DTMF feedback (audio tones played locally when sending DTMF signals to the remote side of the conversation) is enabled. See also: dtmf_method. (Added: 9.0.018.04)
dtmf_method Rfc2833

Info
InbandRtp

Method to send DTMF when dtmf_feedback is enabled.
echo_control 0
1
Valid values: 0 or 1. If set to 1, echo control is enabled.
noise_suppression 0
1
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.


Default value: 480

vad_level Number Sets the degree of bandwidth reduction.


Valid values: 0 – 3 — from 0 (conventional VAD) to 3 (aggressive high).

ringing_enabled 0, 1, 2, 3, 4, 5, 6, or 7 Specifies whether to enable the ringtone and on which device to play the media file.


Valid values:

  • 0: None, disable ringtone.
  • 1: (default) Play ringtone through system default device only. Configure media in system.media.ringing_file.
  • 2: Play ringtone through communication device (headset) only. Configure media in policy.session.ringing_file.
  • 3: Play ringtone through both devices at the same time (the combination of values 1 and 2).
  • 4: Play ringtone through a separate ringer device, specified by policy.device.ringer_device.
  • 5: Play ringtone through system default device and lay ringtone through a separate ringer device (the combination of values 1 and 4).
  • 6: Play ringtone through the communication device (headset) once only for the full duration (policy.session.ringing_timeout is ignored, and ringing does not stop when the call is answered). Configure media in policy.session.ringing_file.
  • 7: Play ringtone once for the full duration through both system default device and communication device (headset) (policy.session.ringing_timeout is ignored, and ringing does not stop when call is answered). Configure media in system.media.ringing_file and policy.session.ringing_file.

Default value: 1

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.


Valid values: Empty, 0, or a positive number
Default value: 0

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 files for built-in ringing are RIFF (little-endian) WAVE files using one of the following formats:
kWavFormatPcm = 1, PCM, each sample of size bytes_per_sample
kWavFormatALaw = 6, 8-bit ITU-T G.711 A-law
kWavFormatMuLaw = 7, 8-bit ITU-T G.711 mu-law

Uncompressed PCM audio must be 16 bit mono or stereo and have a frequency of 8, 16, or 32 KHZ.

Sample ringing sound files are provided. Each file is adjusted to have a higher or lower level of volume than the default ringing sound file, as follows:

  • ringing.wav (default)
  • ringing_+10dB.wav
  • ringing_-10dB.wav
  • ringing_-20dB.wav

You can adjust the volume level of the default ringer sound by specifying the file that has the preferred level of volume.

Valid values: Empty or the path to the ringing sound file for the audio out device (headset). The path can be a filename in the current directory or the full path to the sound file.

Default value: ringing.wav

ringback_enabled
0, 1, 2, 3, 4, or 6 Specifies how the ringback feature is enabled.
  • 0: (default) do not play a ringback when the INVITE dialog is not yet established.
  • 1: play the incoming media stream, if provided by the media gateway in a reliable provisional response with SDP.
  • 2: play ringback from a local file only.
  • 3: always play ringback using media provided by gateway or a local file if not provided.
  • 4: same as 1, but the incoming media stream is played even if the provisional response from Media gateway is not reliable.
  • 6: the ringback is always played using either a local file or media provided by the gateway (regardless of whether the provisional response is reliable or not).
ringing_while_call_held
0, 1 Valid values: 0 or 1

Default value: 1

Specifies whether to play ringtone or not when a call is held and a new call arrives.

  • 0: call wait tone (if configured) is played instead of ringtone.
  • 1 (default): ringtone is played whenever a new call arrives and there are no other active calls; held calls are not considered active in this case.
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.
device
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
headset_name 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.

include_headset String

Valid values: A pair of device names or name parts, with microphone and speaker names separated by a colon, or a comma-separated list of name pairs. For example:

External Mic:Headphones

If the names include delimiter characters such as quotes, colons, or comma, they must be enclosed in single or double quotes.

Specifies the list of audio in / out devices to be considered as a headset for automatic device selection. This option is applicable to the case when use_headset = "1"

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.


Valid values: 0 or 1

exclude_headset String The name of a headset model or built-in audio device (example: Realtek). The specified device is excluded from being recognized or automatically selected as a valid headset.

Note that components of an excluded device, such as a microphone or speaker, can still be selected manually (or automatically, if Softphone does not find a better device). However, even if a component of an excluded device is selected, Softphone does not recognize the excluded device as an available headset.
Valid values: Any valid regular expression.
Default value: Empty

Note: This option is only available for Genesys Softphone installed on Windows.

connector
auto_restart Number Valid values: 0 or 1. If set to 1 (default) the Softphone must be restarted after every client session.
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 Workspace Web Editon (WWE) running in a browser). This option must always be set to 0 when connecting Workspace Desktop Edition (WDE) to Genesys Softphone.
partitioned_cookies Number Valid values: 0, 1, or 2. This option controls the capability of Genesys Softphone to leverage the support by Chrome and Edge (Chromium) of the cookies attribute partitioned which allows limited cookie sharing across domains. Once this cookie flag is in place, the versions of Chrome and Edge (Chromium) that implement the Phase Out of Third Party Cookie continue to accept the session cookie generated by Genesys Softphone. Valid from release 9.0.126.05.
  • 0: disabled, never add the cookie attribute
  • 1: enabled, always add the cookie attribute
  • 2 (default): auto, enable the cookie attribute conditionally for Chrome and Edge (Chromium) version greater or equal to v 118.
port Number The port that Softphone opens 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 stand-alone GUI mode.
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.
sec_protocol String Valid values:
  • strict mode: SSLv3, TLSv1, TLSv11, and TLSv12 are the strict protocol version modes. These settings can be used to enforce a specific protocol version. The connection will not be established if the remote server does not accept the enforced protocol version.
  • compatibility mode: SSLv23, the default mode, is compatible with all modes from SSLv2 up to and including TLSv12; it will connect with the highest mode offered by the other server. If SSLv2 ciphers are explicitly specified, the SSLv2 client can connect only to servers running in SSLv23 mode. Otherwise, the SSLv2 mode is deprecated; but it is highly vulnerable and is not recommended.
codecs
— See SIP Endpoint SDK for .NET 9.0.0NET—Working with Codec Priorities and SIP Endpoint SDK for OSX —Working with Codec Priorities.
proxies
proxy<n>
display_name String Proxy display name.
password String Proxy password.
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.
Important
The 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.


Valid values: 0 or 1
Default value: 0

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 stand-alone mode.
nat
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.
system
diagnostics
enable_logging Number Disable or enable logging.


Valid values: 0 or 1

log_file String Log filename, for example, SipEndpoint.log
log_level Number Valid values: 0 – 4
Log levels: 0 = "Fatal"; 1 = "Error"; 2 = "Warning"; 3 = "Info"; 4 = "Debug".
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.
log_segment false
Number
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.


Valid values:
false: No segmentation is allowed
<number> or <number> KB: Size in kilobytes
<number> MB: Size in megabytes
<number> hr: Number of hours for segment to stay open
Default value: 10 MB

log_expire false
Number
Number file
Number day
Determines whether the 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.
Valid values:
false: No expiration; all generated segments are stored.
<number> or <number> file: Sets the maximum number of log files to store. Specify a number from 1 to 1000.
<number> day: Sets the maximum number of days before log files are deleted. Specify a number from 1 to 100
Default value: 10 (store 10 log fragments and purge the rest)

log_time_convert local
utc
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).


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.
utc: The time of log record generation is expressed as Coordinated Universal Time (UTC).
Default value: local

log_time_format time
locale
ISO8601
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.


Valid values:
time: The time string is formatted according to the HH:MM:SS.sss (hours, minutes, seconds, and milliseconds) format
locale: The time string is formatted according to the system’s locale.
ISO8601: The date in the time string is formatted according to the ISO 8601 format. Fractional seconds are given in milliseconds.
Default value: time

security
certificate String For more information, see the certificate option for .NET and macOS.
use_srtp optional

allowed disabled off elective both enabled force mandatory

Indicates whether to use SRTP (Secure Real-Time Transport Protocol) [Modified: 9.0.005.06]
  • optional or allowed: Do not send secure offers, but accept them.
  • disabled or off: Do not send secure offers and reject incoming secure offers.
  • elective or both: Send both secure and non-secure offers and accept either.
  • enabled: Send secure offers, accept both secure and non-secure offers.
  • force or mandatory: Send secure offers, reject incoming non-secure offers.

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 no
host
For more information, see the tls-target-name-check option for .NET and macOS.
media
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 default audio device (speakers) when the default device ringtone is enabled with the ringing_enabled option.


Sample ringing sound files are provided. Each file is adjusted to have a higher or lower level of volume than the default ringing sound file, as follows:

  • ringing.wav (default)
  • ringing_+10dB.wav
  • ringing_-10dB.wav
  • ringing_-20dB.wav

You can adjust the volume level of the default ringer sound by specifying the file that has the preferred level of volume.

Valid values: Empty or String filename
Default value: ringing.wav

For more information about these options, see SIP Endpoint SDK for .NET Developer's Guide and SIP Endpoint SDK for OSX Developer's Guide.

Audio device settings

This section describes how to set up Genesys Softphone to work with your audio devices, such as headsets.

Genesys Softphone uses the following criteria to select its audio input and output devices:

Basic settings

Use the following parameters to configure headsets and other audio input devices:

  • headset_name
  • audio_in_device
  • audio_out_device

If none of the audio devices that are accessible to the endpoint, match the device names in the configuration file; Genesys Softphone picks up the first available devices from the WebRTC list for audio devices.

Tip

The headset_name, audio_in_device, and audio_out_device options support both device proper names and regular expressions.

Audio device selection rules

The following rules are used to select an audio device, auto-answer a call, and reject a call.

The following audio device selection procedure is applied on startup and every time any changes are made to device presence (such as when a new device is plugged in or an existing device is removed):

  1. The first device in the applicable list that is present in the system is selected when possible. This device (or devices) will either be specified by the headset_name parameter or by the audio_in_device and audio_out_device parameters, depending on whether the use_headset parameter has been enabled.
  2. If none of the configured devices are present (or if the configuration list is empty), then Genesys Softphone selects the audio devices using the priority provided by WebRTC, based on the order of the available devices in its device list.

Auto-answer

When either of the following conditions is met, Softphone blocks the auto-answer functionality (a manual answer is still possible):

  • the use_headset parameter is set to 1, and none of the devices listed in the headset_name settings are present (but session rejection is not applicable, that is, the reject_session_when_headset_na parameter has been set to 0).
  • Genesys Softphone was unable to find any usable microphone or speaker device (applicable to cases where the use_headset parameter is set to 0).

If the auto_answer parameter is set to 1 and the auto-answer functionality is not blocked (and the call was not already rejected), Genesys Softphone answers the incoming call automatically (the should answer policy returns the value true).

In addition, auto-answer will be triggered by the Alert-Info SIP header in the incoming INVITE, as described in the Deploying Genesys Softphone page.

Rejecting a call

For backward compatibility with previous releases, a call can only be rejected when both of the following conditions are met (a policy of should answer returns the value false):

  • Both the use_headset and reject_session_when_headset_na parameters are set to 1.
  • None of the devices listed in the headset_name settings is present on the workstation.

When these conditions are both met, an incoming call is rejected with the SIP response code that is configured in the sip_code_when_headset_na setting. If the setting is missing or the value is not in the valid range of 400 to 699, then the default value of 480 (Temporarily Unavailable) is used.

In addition, when these conditions are met, Genesys Softphone refuses to initiate any new calls; it rejects all outgoing call attempts.

The availability of a fallback device (selected by Step 2 in the Audio device selection section) does not affect call rejection.

Audio setting combinations

Sometimes combinations of settings that you make can have unexpected results. Before adjusting your settings, review this section. The following combinations of settings affect audio device selection, auto-answer, and call rejection in the ways described below:

use_headset=1

Headset is available

Genesys Softphone considers a headset to be available if a headset is found by name in the list of headset names stored in the headset_name parameter. (The highest priority device in the list is selected).

Outgoing calls can be initiated.

auto_answer=1 Incoming calls are answered automatically.
auto_answer=0 Incoming calls are answered manually.
Headset is not available

Genesys Softphone determines that no headset is available if a headset is not found by name in the list of headset names stored in the headset_name parameter.

An audio device is still assigned if any supported devices are present in the system, using the first available audio input and output devices from the list compiled by WebRTC.

No auto-answer is possible in this subcase, so the auto_answer setting is not used. reject_session_when_headset_na=1
  • Incoming calls are automatically rejected.
  • Outgoing calls are blocked.
reject_session_when_headset_na=0
  • Incoming calls can be answered manually. It is assumed that the agent will plug in the headset (or use an available non-headset device, if applicable) before answering the call.
  • Outgoing calls can be initiated. It is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side.

use_headset=0

Audio devices are configured using the names from the audio_in_device and audio_out_device settings. Genesys Softphone selects the highest-priority input and output devices from that list or, if no valid devices are found in that list, from the first available devices in the list compiled by WebRTC. Outgoing calls can be initiated.

Both microphone and speaker are available auto_answer=1 Incoming calls are answered automatically.
auto_answer=0 Incoming calls are answered manually.
Either microphone or speaker is not available
  • Incoming calls can be answered manually. It is assumed that the agent will plug in the headset (or use an available non-headset device, if applicable) before answering the call.
  • Outgoing calls can be initiated. It is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side.
No auto-answer is possible in this subcase, so the auto_answer setting is not used. Auto-rejection is not applicable, so the reject_session_when_headset_na setting is not used.
This page was last edited on December 6, 2023, at 07:57.
Comments or questions about this documentation? Contact us for support!