Account XML¶
SIP Accounts are specified in an XML format, where SIP credentials and various other options are specified. Below is the description of the recognized XML nodes and their possible values.
Credentials¶
title
¶
<title>Account Title</title>
- Default
empty
- Description
The title of the account. It is shown at various places in the GUI and it must have a non-empty value. It is normally populated from Cloud Softphone portal or filled-in by user in the edit account forms. In case you set the value via provisioning, make sure it’s not empty, otherwise the account validation will fail and the account won’t be saved.
cloud_username
and cloud_password
¶
<cloud_username>johndoe@company.org</cloud_username>
<cloud_password>secretPhrase2</cloud_password>
- Default
No default value
- Description
Many providers prefer to use different credentials to log in to the app than for the SIP credentials. If you return values for these, they can be used for authorizing external provisioning requests or other web service request as described here :ref: client-api-intro.
userDisplayName
¶
<userDisplayName>John Doe</userDisplayName>
- Default
empty string
- Description
SIP display user name, comes quoted in front of SIP uri.
authUsername
¶
<authUsername>johndoe</authUsername>
- Default
empty string
- Description
Username used in SIP authorization headers. If left empty, the username is used.
host
¶
<host>sip.example.com[:port]</host>
- Default
No default value.
- Description
SIP domain, used in SIP URIs as
username@host
. The SIP domain is also used as a SIP server to connect to, in case<proxy>
is not specified. If no port is specified, 5060 is the default for non-encrypted transports, 5061 for tls transports.
transport
¶
<transport>udp</transport>
- Default
udp
- Valid values
udp
,tcp
,tls
andtls+sip:
- Description
The transport protocol to use when communicating with SIP server. Transport
tls
uses sips: URIs in headers and the traffic is protected by TLS.tls+sip:
is also TLS-protected, but uses sip: URIs.
userCallerId
¶
<userCallerId>John Doe</userCallerId>
- Default
empty string
- Description
If set, this value will be sent in the
From:
field in outgoingINVITE
requests. In case it’s left empty, username will be used.
expires
¶
<expires>600</expires>
- Default
600
- Valid values
integer larger or equal to 30
- Description
value for the Expires: header in SIP REGISTER packet.
Note
Servers may reject registration with too low value in Expires: header and negotiate a higher value.
Warning
If you’re using Acrobits Cloud solution for incoming calls, the Acrobits’ Sipis servers may reject/ban instances that require
an expiration interval shorter than 300
seconds.
Ask an Acrobits representative about the option of hosting your own Sipis servers in case your deployment requires a more frequent registration refresh.
subscriptionExpires
¶
<subscriptionExpires>300</subscriptionExpires>
- Default
300
- Valid values
integer larger or equal to 30
- Description
value for the Expires: header in SUBSCRIBE packets.
allowMessage
¶
<allowMessage>1</allowMessage>
- Default
0
- Valid values
0
and1
- Description
When set,
MESSAGE
will be added to theAllow:
list inSIP REGISTER
packets. SIP/SIMPLE messaging won’t work without this set.
SIPIS¶
sipisHost
¶
<sipisHost>sipis.example.com</sipisHost>
- Default
sipis.acrobits.cz
- Valid values
domain name or IP address
- Description
Specifies the SIPIS server which the app should connect to.
sipisRegServer
¶
<sipisRegServer>sipis.example.com</sipisRegServer>
- Default
reg.acrobits.cz
- Valid values
domain name or IP address
- Description
Specifies the server which the app will use to transfer the account credentials to SIPIS. Typically it will be the same address as in
sipisHost
sipisHostPrefixLength
¶
<sipisHostPrefixLength>0</sipisHostPrefixLength>
- Default
1
- Valid values
nonnegative integer values
- Description
Used for load-balancing of SIPIS servers. In case it’s greater than zero, the actual
sipisHost
value is constructed by prefixings-X.
to address insipisHost
. The X is taken from account selector, which is SHA1(username:password:host). The value in sipisHostPrefixLength specifies how many letters from the hex-digit representation of selector to use. For example, with sipisHostPrefixLength=1, the app will use serverss-0.sipis.example.com
-s-F.sipis.example.com
. You will need to set up the DNS and deploy multiple SIPIS servers to make load balancing work.
Note
Note that the default value is 1
. If you want to use a single SIPIS server (which is OK for
up to 20,000 users on any reasonable machine), you will need to set this explicitly to 0
.
Proxies¶
proxy
¶
<proxy>proxy.example.com[:port]</proxy>
- Default
empty string
- Description
Address of SIP proxy server to connect to. If no port is specified, 5060 is used.
outboundProxy_enabled
¶
<outboundProxy_enabled>0</outboundProxy_enabled>
- Default
empty string
- Description
when set to 1, all SIP traffic is routed through
outboundProxy_host
usingoutboundProxy_transport
outboundProxy_host
¶
<outboundProxy_host>proxy.example.com[:port]</outboundProxy_host>
- Default
empty string
- Description
Address through which all SIP traffic is routed. If no port is specified, 5060 is used. outboundProxy_enabled needs to be set to
1
for this option to take effect.
outboundProxy_transport
¶
<outboundProxy_transport>udp</outboundProxy_transport>
- Default
udp
- Description
Transport to use for outboud proxy. All values described in
transport
field may be used. outboundProxy_enabled needs to be set to1
for this option to take effect.
Note
The final address of the SIP server is determined as follows:
if outbound proxy is enabled and its host is filled it, all traffic is routed through it
if
<proxy>
is empty,address = <host>
, otherwiseaddress = <proxy>
if address is not numeric (a.b.c.d) and port is not specified in address, do a SRV DNS resolution for
_sip._udp.address
(or_sip._tcp.address
, depending on the transport used)if SRV record exists,
address = DNSResultAddress:DNSResultPort
else use address
Voicemail¶
voiceMailNumber
¶
<voiceMailNumber>*69</voiceMailNumber>
- Default
empty string
- Description
The number which is dialed when the “voice mail” button is pressed.
subscribeForVoicemail
¶
<subscribeForVoicemail>1</subscribeForVoicemail>
- Default
0
- Valid values
1
or0
- Description
Set to send
SUBSCRIBE
for voice mail
pushVoicemail
¶
<pushVoicemail>1</pushVoicemail>
- Default
0
- Valid values
1
or0
- Description
Set to 1 if you want new voicemails reported to SIPIS to trigger a push notification to the device.
Audio Codecs¶
codecOrder
¶
<codecOrder>103,9,0,8,18,102,3</codecOrder>
- Default
103,9,0,8,18,102,3
- Valid values
comma separated list of codec numbers.
- Description
The order of codecs, as it will be offered in SDP for calls made over Wifi network.
Supported codecs are:
0 : G711 μ-law 3 : GSM 8 : G711 a-law 9 : G722 wideband codec 102 : iLBC 18 : G729 103 : Opus
codecOrder3G
¶
<codecOrder3G>18,103,102,3,9,0,8</codecOrder3G>
- Default
18,103,102,3,9,0,8
- Valid values
comma separated list of codec numbers.
- Description
The order of codecs, as it will be offered in SDP for calls made over cellular network. See the codecOrder field above for the list of valid codec payloads.
honorTheirCodecListWiFi
¶
<honorTheirCodecListWiFi>0</honorTheirCodecListWiFi>
- Default
1
- Valid values
0
or1
- Description
Forces the application to use the first codec offered by the remote side for calls over Wifi
honorTheirCodecList3G
¶
<honorTheirCodecList3G>0</honorTheirCodecList3G>
- Default
0
- Valid values
0
or1
- Description
Forces the application to use the first codec offered by the remote side for calls over 3G
Warning
It’s not recommended to change honorTheirCodecList3G and honorTheirCodecListWiFi defaults.
Note
Consider an incoming INVITE with codecs “0,18” in SDP. SIP account is configured with codecOrder set to “0,18” and codecOrder3G “18,0”.
If we’re on cellular network, it makes sense to ignore the remote’s preference of codec “0” (μ-law), because
we know our bandwidth is limited. This is why honorTheirCodecList3G if 0
by default - with this
setting, we pick the first codec on our list, which is also supported by the remote side (“18”-G.729)
On the other hand, when on wifi connection, we assume that we have enough bandwidth to honor the remote’s
preference, therefore the default value is 1
.
ptime
¶
<ptime>20</ptime>
- Default
20
- Description
packet time in milliseconds, to be used with WiFi codec set.
ptime3G
¶
<ptime3G>30</ptime3G>
- Default
30
- Description
packet time in milliseconds, to be used with 3G codec set.
forcePtime
¶
<forcePtime>0</forcePtime>
- Default
0
- Valid values
0
or1
- Description
If set to
1
, the ptime parameter will be used even if the remote side requests a different value.
forcePtime3G
¶
<forcePtime3G>0</forcePtime3G>
- Default
0
- Valid values
0
or1
- Description
If set to
1
, the ptime3G parameter will be used even if the remote side requests a different value.
Opus codec options¶
Opus codec parameters may be fine-tuned via several keys. The keys start either with opusOptions. or opusOptions3G. for WiFi or cellular calling respectively.
You can either just set the opusOptions.class which can be nb
for narrowband, wb
for wideband, or fb
for fullband.
Alternatively you can finetune all the opus parameters. In this case the opusOptions.class parameter need to be set to the empty string. Then you can set opusOptions.bandwidth, opusOptions.complexity, opusOptions.bitrate, opusOptions.fec, opusOptions.vbr, opusOptions.dtx, and opusOptions.expectedPacketLoss.
Example:
<opusOptions3G.class>nb</opusOptions3G.class>
or
<opusOptions.class></opusOptions.class>
<opusOptions.bandwidth>fb</opusOptions.bandwidth>
<opusOptions.complexity>5</opusOptions.complexity>
<opusOptions.bitrate>300000</opusOptions.bitrate>
<opusOptions.fec>1</opusOptions.fec>
<opusOptions.dtx>0</opusOptions.dtx>
<opusOptions.vbr>0</opusOptions.vbr>
opusOptions.class
¶
<opusOptions.class>wb</opusOptions.class>
<opusOptions3G.class>nb</opusOptions3G.class>
- Default
wb
- Valid values
nb
,wb
,fb
or empty string- Description
If set to
nb
, it’s equivalent to setting:opusOptions.bandwidth to
nb
opusOptions.complexity to empty string
opusOptions.bitrate to
15500
opusOptions.fec to
1
opusOptions.dtx to
1
opusOptions.vbr to
1
If set to
wb
, it’s equivalent to setting:opusOptions.bandwidth to
wb
opusOptions.complexity to empty string
opusOptions.bitrate to
24000
opusOptions.fec to
1
opusOptions.dtx to
1
opusOptions.vbr to
1
If set to
fb
, it’s equivalent to setting:opusOptions.bandwidth to
fb
opusOptions.complexity to empty string
opusOptions.bitrate to
64000
opusOptions.fec to
1
opusOptions.dtx to
1
opusOptions.vbr to
1
If set to empty string, you need to set other options yourself
opusOptions.bandwidth
¶
<opusOptions.bandwidth>wb</opusOptions.bandwidth>
<opusOptions3G.bandwidth>nb</opusOptions3G.bandwidth>
- Default
wb
- Valid values
nb
,wb
,fb
- Description
Limits the band width of the codec.
nb
for narrowband i.e. 8kHzwb
for wideband i.e. 16kHzfb
for fullband i.e. 48kHzany other value is treated as
wb
The hertz value will be signalled in SDP as
maxplaybackrate
. Encoder will be set to the minimum of this setting and the value received in the SDP.
opusOptions.complexity
¶
<opusOptions.complexity></opusOptions.complexity>
<opusOptions3G.complexity>5</opusOptions3G.complexity>
- Default
empty string
- Valid values
0 to 10 or empty string
- Description
Configures the encoder’s computational complexity. The supported range is 0-10 inclusive with 10 representing the highest complexity. When not specified, use Opus default.
opusOptions.bitrate
¶
<opusOptions.bitrate>20500</opusOptions.bitrate>
<opusOptions3G.bitrate>15500</opusOptions3G.bitrate>
- Default
empty string
- Valid values
integers between
6000
and510000
, empty string value,-1000
, or-1
- Description
Desired encoder bitrate in bits per second.
Values between
6000
and510000
are meaningful. Empty string or-1000
means automatic bitrate. Value-1
means maximum bitrate. This value will be signalled in SDP. If received in SDP asmaxaveragebitrate
, the value from SDP will be used for encoder.
opusOptions.fec
¶
<opusOptions.fec>1</opusOptions.fec>
<opusOptions3G.fec>1</opusOptions3G.fec>
- Default
0
- Valid values
1
or0
- Description
Forward error correction. When enabled, encoder transmits redundant information which makes it possible to reconstruct lost packets on the received side. If enabled
useinbandfec=1
is signalled in SDP. The FEC for the encoder is enabled only ifuseinbandfec=1
is received in SDP. Otherwise it is disabled.
opusOptions.dtx
¶
<opusOptions.dtx>1</opusOptions.dtx>
<opusOptions3G.dtx>1</opusOptions3G.dtx>
- Default
0
- Valid values
1
or0
- Description
Enables discontinuous transmission (DTX). If enabled
usedtx=1
is signalled in SDP. The DTX for the encoder is enabled only ifusedtx=1
is received in SDP. Otherwise it is disabled.
opusOptions.vbr
¶
<opusOptions.vbr>1</opusOptions.vbr>
<opusOptions3G.vbr>1</opusOptions3G.vbr>
- Default
1
- Valid values
1
or0
- Description
Enables variable bit rate. Note it’s not recommended to use VBR for secure calls. If disabled
cbr=1
is signalled in SDP. The VBR for the encoder is disabled ifcbr=1
is received in SDP. Otherwise it is enabled.
opusOptions.expectedPacketLoss
¶
<opusOptions.expectedPacketLoss>5</opusOptions.expectedPacketLoss>
<opusOptions3G.expectedPacketLoss>5</opusOptions3G.expectedPacketLoss>
- Default
0
- Valid values
0 - 100
- Description
Specifies the expected percentage of packet loss. Higher values will allocate more of the bit rate for redundant data to be used to reconstruct lost packets, which may degrade quality in the loss-less case (but will provide better quality in situations with lost packets)
Video Codecs¶
allowVideo
¶
<allowVideo>1</allowVideo>
- Default
1
- Valid values
1
or0
- Description
Value
1
enables video calls in the application,0
disables video calls.
videoCodecOrder
¶
<videoCodecOrder>108,99</videoCodecOrder>
- Default
108,99
- Valid values
comma separated list of codec numbers
- Description
The order of video codecs, as it will be offered in SDP for calls made with Wifi codec set.
Supported codecs are:
108 : VP8 99 : H264
videoCodecOrder3G
¶
<videoCodecOrder3G>108,99</videoCodecOrder3G>
- Default
108,99
- Valid values
comma separated list of codec numbers
- Description
The order of video codecs, as it will be offered in SDP for calls made with 3G codec set.
videoMinKbpsWifi
and videoMaxKbpsWifi
¶
<videoMinKbpsWifi>64</videoMinKbpsWifi>
<videoMaxKbpsWifi>384</videoMaxKbpsWifi>
- Default
64 - 384
- Description
The values are in kilobits per second. Bandwidth range for video in case it’s being sent over wifi. The encoder is initially configured to produce bitrate in the middle of the given range and adjusts the bitrate adaptively towards either end of the range depending on the network conditions.
videoMinKbps3G
and videoMaxKbps3G
¶
<videoMinKbps3G>64</videoMinKbps3G>
<videoMaxKbps3G>384</videoMaxKbps3G>
- Default
64 - 192
- Description
The values are in kilobits per second. Bandwidth range for video in case it’s being sent over cellular network. See videoMinKbpsWifi and videoMaxKbpsWifi for more details.
videoDimsWifi
¶
<videoDimsWifi>qcif</videoDimsWifi>
- Default
qcif
- Description
Specifies video resolution to be sent over wifi
- Valid values
one of the resolution names, specified in table below:
resolution name
frame dimensions
qcif
176 × 144
cif
352 × 288
vga
640 x 480
cif4
704 × 576
cif16
1408 × 1152
720p
1280 × 720
1080p
1920 x 1080
Note
H264 and VP8 support all resolutions and in case the device changes orientation from landscape to portrait or vice-versa, the resolution is automatically transposed.
videoDims3G
¶
<videoDims3G>qcif</videoDims3G>
- Default
qcif
- Description
Specifies video resolution to be sent over cellular networks
- Valid values
same as for videoDimsWifi
videoFPSWifi
¶
<videoFPSWifi>15</videoFPSWifi>
- Default
empty string
- Description
Frame rate in frames-per-second which the video encoder should use to encode video streams transferred over Wifi.
Note
When left empty, the library chooses the pre-defined value for the current device. Choosing high frame rate means more CPU power is needed to encode the video and less bits can be allocated to a single frame within the bandwidth constraints. When a bit rate is too high, some frames may be dropped if the CPU can’t keep up with encoding.
iOS camera has maximum fram rate of 30 fps. The pre-defined fps ranges from 10 for 3GS device to 20 for iPhone 4S.
videoFPS3G
¶
<videoFPS3G>15</videoFPS3G>
- Default
empty string
- Description
Frame rate in frames-per-second which the video encoder should use to encode video streams transferred over cellular networks.
autoSendVideoWifi
¶
<autoSendVideoWifi>1</autoSendVideoWifi>
- Default
empty string
- Valid values
0
,1
or empty string- Description
when set to empty string, the outgoing video stream is added to the call based on global app settings. Specifying
0
or1
will override these settings for this particular account. When set to1
, video stream will be added into SDP when making general call (dialAction: “autoCall”) over wifi network or when answering incoming call without explicitly specifying media type (for example, by clicking on notification about incoming call)
Note
You can always explicitly request a video call by using “videoCall” dialAction, or voice-only call by “voiceCall” dialAction. Also note that even if the call is started without video, it can be added later.
autoSendVideo3G
¶
<autoSendVideo3G>1</autoSendVideo3G>
- Default
empty string
- Valid values
0
,1
or empty string- Description
Automatically add outgoing video stream into SDP when making call over cellular network. See autoSendVideoWifi for more details.
autoReceiveVideoWifi
¶
<autoReceiveVideoWifi>1</autoReceiveVideoWifi>
- Default
empty string
- Valid values
0
,1
or empty string- Description
Automatically allow incoming video stream when for calls over wifi. See autoSendVideoWifi for more details.
autoReceiveVideo3G
¶
<autoReceiveVideo3G>1</autoReceiveVideo3G>
- Default
empty string
- Valid values
0
,1
or empty string- Description
Automatically allow incoming video stream when for calls over cellular networks. See autoSendVideoWifi for more details.
DTMF¶
dtmfOrder
¶
<dtmfOrder>rfc2833,info,audio</dtmfOrder>
- Default
rfc2833,info,audio
- Valid values
comma separated list of: rfc2833, info and audio.
- Description
The methods to use when generating DTMF events. The methods are tried in the order specified here. RFC 2833 method is only used when the remote side supports telephone-event RTP payload.
Note
To disable a method, simply don’t put it on the list. The list may have only a single item.
dtmfAll
¶
<dtmfAll>0</dtmfAll>
- Default
0
- Valid values
0
and1
- Description
When set, all supported DTMF modes will be sent together. Not recommended.
rfc2833NegotiateOnly8kHzClockRate
¶
<rfc2833NegotiateOnly8kHzClockRate>1</rfc2833NegotiateOnly8kHzClockRate>
- Default
1
- Valid values
0
and1
- Description
In theory, the RFC 2833 DTMF RTP packets should use the same clock rate as the selected audio codec:
“DTMF digits and named telephone events are carried as part of the audio stream, and MUST use the same sequence number and time-stamp base as the regular audio channel to simplify the generation of audio waveforms at a gateway.”
—RFC 2833
This means that if an application offers audio codecs with distinct clock rates (e.g. PCMU/8000 and opus/48000/2), it should also offer multiple telephone-event payload types, each with a corresponding distinct clock rate (e.g. telephone-event/8000 and telephone-event/48000). And depending on the final outcome of the audio codec negotiation, the application should then use proper payload number, corresponding to either telephone-event/8000 or telephone-event/48000 when generating RFC 2833 DTMF RTP packets.
In practice, however, many systems cannot deal with anything else than “telephone-event/8000” regardless of the selected audio codec and its clock rate.
This option therefore allows switching between RFC 2833 conforming mode (value
0
), in which the application offers multiple telephone-event payload types, and legacy mode (value1
) in which only “telephone-event/8000” is offered and recognized.
rfc2833EnforceDurationIn8KHzTimestampUnits
¶
<rfc2833EnforceDurationIn8KHzTimestampUnits>0</rfc2833EnforceDurationIn8KHzTimestampUnits>
- Default
0
- Valid values
0
and1
- Description
In case the rfc2833NegotiateOnly8kHzClockRate option is enabled and the clock rate of the negotiated audio codec differs from 8 kHz, the app can populate the duration field of RFC 2833 DTMF RTP packets with either unmodified timestamp units corresponding to the audio codec clock rate (value
0
), or it can adjust the timestamp units to correspond to 8 kHz clock rate (value1
).
NAT Traversal¶
STUN
¶
<STUN>stun.example.com:[port]</STUN>
- Default
empty string
- Description
STUN server to use. When empty, libsoftphone will make a DNS SRV query for
_stun._udp.sipserver
and uses the returned address. If no port is specified, 3478 is used.
STUNUsername
¶
<STUNUsername>user</STUNUsername>
- Default
empty string
- Description
Username for STUN/TURN server. If filled in, we’ll consider the STUN server TURN-capable.
STUNPassword
¶
<STUNPassword>password</STUNPassword>
- Default
empty
- Description
Password for STUN/TURN server.
natTraversal
¶
<natTraversal>auto</natTraversal>
- Default
auto
- Valid values
off, auto, stunOnly, turnAlways, ice
- Description
Specifies the NAT traversal mode to use. This setting controls which addresses will be put into SDP. The options are described in detail below:
- off
will always send local/private IP address detected from local network interface. No public address resolution is done.
- auto
will do a STUN query for a public address. If symmetric NAT is not detected, the global address is used. In case of symmetric NAT, TURN server is used if STUNUsername is filled in, otherwise private/local address is used.
- stun
will do a STUN query and always use the obtained public address (unless symmetric NAT is detected or if ignoreSymmetricNat is set to 1)
- turnAlways
will always use TURN server
- ice
will use the ICE process to choose the best address
ignoreSymmetricNat
¶
<ignoreSymmetricNat>1</ignoreSymmetricNat>
- Default
0
- Valid values
0
and1
- Description
if set, it will not check for symmetric NAT and will use the public IP if instructed so even when on symmetric NAT. Setting it to 1 is not recommended, since the IP:port detected will most likely not be accessible from outside, but sometimes it may be necessary to send the public IP even though the port is wrong.
iceDefaultCandidateOrder
¶
<iceDefaultCandidateOrder>relay,srflx,host</iceDefaultCandidateOrder>
- Default
relay,srflx,host
- Valid values
comma-separated list of “relay”,”srflx”,”host”
- Description
You can prioritise one default ICE candidate over others.
For example to prefer server reflexive address over relay address, set it to srflx,host,relay. To prefer host address, set it to host,srflx,relay.
contactIP
¶
<contactIP>internal</contactIP>
- Default
internal
- Valid values
internal, external, static
- Description
Specifies which address to use in Contact and Via SIP headers:
- internal
will use the local/private in the Contact and Via SIP header.
- external
will try to determine the public address using STUN ping, OPTIONS packet or STUN server and use it in Contact and Via header.
- static
will use a static address in Contact and Via header, the address is specified in forcedContact node.
forcedContact
¶
<forcedContact>192.168.100.100:7777</forcedContact>
- Default
empty string
- Description
This IP address will be used in Contact and Via headers in case contactIP is set to “static”.
sendAudioBack
¶
<sendAudioBack>0</sendAudioBack>
- Defalut
1
- Valid values
0
and1
- Description
If set to
1
, we will always send the audio back to the address from which we receive the audio from the other side.
keepAlive
¶
<keepAlive>1</keepAlive>
- Default value
0
- Valid values
0
and1
- Description
When set, libSoftphone periodically sends keep-alive packet to SIP server, to keep the connection active and NAT port mappings open.
keepAlivePeriod
¶
<keepAlivePeriod>30</keepAlivePeriod>
- Default value
30
- Valid values
integer number. The value is in seconds, the minimum allowed value is 5
- Description
Specifies the amount of seconds between two keep-alive packets
rtpPortRangeStart
and rtpPortRangeEnd
¶
<rtpPortRangeStart>10000<rtpPortRangeStart>
<rtpPortRangeEnd>65530<rtpPortRangeEnd>
- Default
10000 and 65535.
- Valid values
integer numbers between 1025 and 65535 (inclusive). There should be at least 4 ports between these values
- Description
The port range to use for RTP sockets.
listeningPort
¶
<listeningPort>5060</listeningPort>
- Default
empty string
- Description
The local port which the SIP stack will bind to:
- Valid values
integer numbers between 1025 and 65535 (inclusive)
If left empty, the SIP stack will choose a random port number and will bind to it. This number will remain the same for at least one day. If the client is restarted and re-registers repeatedly, it will remember its rinstance, callId and CSeq numbers, port will remain the same and therefore it should always occupy the same registration slot on the server.
If set to 0, a random port will be chosen every time the client registers.
If set to a specific numeric value, the SIP stack will always bind to that port.
Warning
On iOS, setting listeningPort for TCP and TLS SIP transports has no effect. Specifying a port to bind to for TCP is not supported by iOS platform.
maxTimeToWaitForWorkingNetworkInMilliseconds
¶
<maxTimeToWaitForWorkingNetworkInMilliseconds>15000</maxTimeToWaitForWorkingNetworkInMilliseconds>
- Default
15000
- Description
the time in milliseconds for which the client keeps calls in established state after the network is lost. When this time expires and there is still no network, the call is hung up.
Custom SIP Headers¶
<headers>
<header method="INVITE" name="X-CustomHeader" value="value"/>
<header method="*" name="X-OtherHeader" value="12345"/>
…
</headers>
Specify custom headers to be added into SIP packets. The headers should be stored in their own node named “headers” as sub-nodes with name “header”. The attributes are:
- method
SIP request method. The custom header will be added only to SIP packets of the specified method. Use
method="*"
to add the header to all SIP packets.- name
header name
- value
header value
Do Not Disturb¶
Do Not Disturb (DND), also called Zen Mode in Android Developers Documentation, mutes all events when the user does not want to be disturbed. DND rules can be provisioned using the XML format described below. Here is an example:
<doNotDisturb gmtOffsetInMinutes="60">
<dndEntry>
<from>08:00</from>
<to>10:00</to>
<weekdays>31</weekdays>
<contacts>
<contactInfo
name="+1 (222) 333-4455"
phone="+12223334455"
identifier=""
source=""/>
</contacts>
</dndEntry>
<dndEntry>
<from>00:00</from>
<to>23:59</to>
<weekdays>96</weekdays>
<contacts/>
<enabled>1</enabled>
<comment>Do not disturb on weekends</comment>
</dndEntry>
</doNotDisturb>
The DND XML is wrapped in an <doNotDisturb>
node. The optional attribute gmtOffsetInMinutes
defines the timezone for
the time values in DND entries. Inside this XML node, there is a list of <dndEntry>
child nodes.
<from>
and <to>
elements define the start and end time when the DND rule applies. The format is HH:MM
and the
hours are in 24h format. Both are required, if you want all-day rule, it should be <from>00:00</from>
and
<to>23:59</to>
.
<weekdays>
is a bit mask which defines for which days in the week the rule applies. The values are as follows:
bit
value
day
0
1
Monday
1
2
Tuesday
2
4
Wednesday
3
8
Thursday
4
16
Friday
5
32
Saturday
6
64
Sunday
If you are not familiar with bitwise arithmetics, all you need to do is to sum the values for days when you want the rule to apply. For example, weekends are Saturday and Sunday, i.e. 32+64 = 96. Workdays would be 1+2+4+8+16 = 31. Note that if you set this to 0, the rule will never be applied; to match any day, you need to set it to 127.
<contacts>
is a list of <contactInfo>
child nodes. In case there are no <contactInfo>
child nodes, the
rule will match for any incoming number. In case the list is not empty, the rule applies only if the incoming party
matches some of the <contactInfo>
child nodes.
In case the <contactInfo>
element has non-empty fields <identifier>
and <source>
, the rule will apply in
case the incoming phone number matches address book contact from the given source and with the given identifier. For
provisioning, you will typically not know these identifiers, so these will be usually left empty (you can also omit
them). In such case, the app uses the value in field <phone>
to match against the incoming call and the rule
applies only when these two are equivalent; it should be in E.164 format. The field <name>
is only
a display name shown in DND rule editor GUI.
<enabled>
is an optional tag. If not present or if its value is <enabled>1</enabled>
, the rule is enabled,
otherwise it is disabled.
Optional tag <comment>
can be used to add a comment to the rule. This is displayed in the GUI.
In the example above, this DND setup will reject all calls coming from number +1 (222) 333-4455 between 8AM and 10AM (GMT+1) on workdays, and it will reject all calls from anyone on weekends.
Number Rewriting¶
<rewriting>
<rule>
<conditions>
<condition type="doesntStartWith" param="+"/>
<condition type="longerThan" param="8"/>
</conditions>
<actions>
<action type="prepend" param="+420"/>
</actions>
</rule>
<rule>
… another rule …
</rule>
…
</rewriting>
- Default
none.
Rules are examined in sequence until all conditions of a rule match the dialed number. Then all the actions are applied to the number. If neither of the actions is continue the transformation ends. However, if one of the actions of the rule is continue, another rule is examined and the conditions are now matched against the transformed number (not the originally dialed number).
The example above means: Add +420 to numbers not starting with + that are longer than 8 digits.
Condition nodes have two attributes: type
(see below) and param
- the parameter of the condition
startsWith
matches numbers that start with the parameter
doesntStartWith
matches numbers that doesn’t start with the parameter
equals
dialed number is exactly the same as the parameter
lengthEquals
the length of the dialed number equals the parameter
shorterThan
the length of the dialed number is shorter then the parameter
longerThan
the length of the dialed number is longer then the parameter
networkType
parameter is one of
wifi
,cellular
,any
,none
. Matches if the current network is the one specified by parameter
ssid
matches if the current Wi-Fi SSID is the one specified in parameter
Action nodes have two attributes:
type
(see below) and optionalparam
- the parameter of the action.
replace
applicable only to conditions
startWith
andequals
. Replaces the matched part with parameter
prepend
prepends the parameter to the dialed number
append
appends the parameter to the dialed number
continue
no parameter, try following rules as well
recordCall
turns on call recording for this call
dialOut
overrides dial-out account. In multi-account clients, this action makes it possible to route certain numbers through a specific account (for example, emergency numbers via cellular account)
confirm
unused
drop
unused
callThrough
forces a call-through dial action for the matching number
overrideDialAction
changes the dialAction to the one specified in param. This can be used to dial certain numbers using callThrough or using native gsm call, or show a list of options of what to do with the number. See Dial Actions for more details.
setHeader
sets SIP header for outgoing SIP call. The
param
contains the header to be set, for example:<action type="setHeader" param="X-Condition-Matched: true"/>
.
rejectCall
used in Incoming Call Rewriter. Rejects the call (486 Busy Here).
forwardCall
used in Incoming Call Rewriter. Forwards the call to the number specified in
param
attribute.
answerImmediately
used in Incoming Call Rewriter. Answers the incoming call immediately, without any user interaction.
Incoming Calls *¶
icm_auto
¶
Deprecated since version C4AEB: builds after Dec 2016.
See icm instead.
<icm_auto>1</icm_auto>
Valid values: 0,1
Determines whether or not to use the global setting for incoming calls.
Default value is 1 which means the global setting for incoming calls will be used.
incomingDisabled
¶
Deprecated since version C4AEB: builds after Dec 2016.
See icm instead.
<incomingDisabled>1</incomingDisabled>
Valid Values: 0,1
Default Value: N/A
pushMethod
¶
Deprecated since version C4AEB: (builds after Dec 2016).
See icm instead.
<pushMethod>tunnel</pushMethod>
Valid Values: off, tunnel
Enables Push Notifications for incoming calls.
Default: N/A
bgrEnabled
¶
Deprecated since version C4AEB: builds after Dec 2016.
See icm instead.
<bgrEnabled>1</bgrEnabled>
Valid Values: 0,1
Enables backgrounding for incoming calls (1 is enabled).
Default Value: N/A
Note: The transport protocol must be TCP or TLS for backgrounding to work.
forceRegistration
¶
Deprecated since version C4AEB: builds after Dec 2016.
See icm instead.
<forceRegistration>1</forceRegistration>
Valid Values: 0,1
Forces registration when incoming calls are off. Use 1 to force registration, only necessary if using incoming calls off with registration.
Default Value: N/A
Note
Only required properties are necessary. E.g., to set incoming calls to Push Notifications you would add:
<icm_auto>0</icm_auto>
<pushMethod>tunnel</pushMethod>
It is not necessary to add the other properties.
- *
Not needed for external provisioning in the Cloud Softphone. Cloud Softphone providers should contact us through the Cloud Softphone web portal if they have any questions on how to set incoming calls.
icm
¶
New in version C4AEB: builds after Dec 2016.
<icm>auto</icm>
From Dec 2016, the incoming call mode configuration has been greatly simplified. The properties above have been deprecated (if you set them, the apps will still migrate them to the icm property though.
Valid Values: auto, push, keepAwake, off
Specifies the incoming call mode to be used for this account. If “auto” is set, the mode is taken from global app settings.
Default Value: auto
requiresRegistrationForOutgoingCalls
¶
New in version C4AEB: builds after Dec 2016.
<requiresRegistrationForOutgoingCalls>1</requiresRegistrationForOutgoingCalls>
Valid Values: 0,1
When
icm
is set tooff
, the app will not register for incoming calls. When it makes an outgoing call, some SIP backends will reject it because they only accept call attempts from registered endpoints.In case this parameter is set to 1, we will register the account when the outgoing call is made and keep it registered for the duration of the call.
Default Value: 1
pushBlockReg
¶
<pushBlockReg>1</pushBlockReg>
Default value: 0
Setting to 1 blocks registration on the device until any Pushed incoming call has ended.
remoteContact
¶
<remoteContact>pai,from,rpid,ppi</remoteContact>
Default value: as above
Specifies where in the incoming INVITE packet should we look for calling party identification. The value is a coma- separated list of identifiers described below. When incoming INVITE packet is received, we look for the remote party identification at places defined by the order here and use the first found value:
identifier
SIP header
pai
P-Asserted-Identity header
from
From header
rpid
Remote-Party-ID header
ppi
P-Preferred-Identity header
Secure Calls¶
Properties:
sdesIncoming sdesOutgoing zrtpIncoming zrtpOutgoing dtlsIncoming dtlsOutgoingValid values: enabled, required, <empty>
Defalut: N/A
Example:
<sdesIncoming>enabled</sdesIncoming>
When set to
enabled
, the app will use best-effort to establish the secure call using the selected technology if the other side supports it as well, but will fall back to unprotected call if it fails.In case of
required
, the call will be dropped if security can’t be established.If not set (left empty), secure calls using the corresponding technology won’t be enabled even if the other side supports them - our side will behave as if the security protocol is not supported.
External Provisioning¶
extProvUrl
¶
<extProvUrl>https://my.server.com/prov.php?u=%account[username]%&p=%account[password]%</extProvUrl>
Default value: empty.
Reprovisioning URL, the app will ask this URL for complete account details. The service is expected to return
<account>
with all the required properties.
extProvInterval
¶
<extProvInterval>3600</extProvInterval>
Default value: 0
How often (in seconds) will the app ask the reprovisioning service for account updates. If the value is 0, the periodic reprovisioning is disabled and reprovisioning URL is contacted only when saving the account on Edit Account screen.
Balance Checking¶
See Balance Checker for detailed description.
Properties:
genericBalanceCheckUrl genericBalanceCheckPostData genericBalanceCheckContentType balanceCheckIntervalInSeconds balanceCheckDelayInSeconds
Web Callback¶
See Web Callback for detailed description.
wcb_enabled
¶
<wcb_enabled>1</wcb_enabled>
Default value: 0
This node is used to enable/disable web callback web service.
Other properties:
wcb_url
wcb_method
wcb_contentType
wcb_postData
wcb_customHeaders
Call Through¶
cth_enabled
¶
<cth_enabled>1</cth_enabled>
Default value: 0
This node is used to enable/disable callthrough service.
cth_dialString
¶
<cth_dialString>+1555123456,%targetNumber%</cth_dialString>
Default value: 0
This dial string to dial via GSM for callthrough service. The dial string may use placeholder replacement described in Global parameters and Account parameters scopes.
cth_ws_enabled
¶
<cth_ws_enabled>1</cth_ws_enabled>
Default value: 0
This node is used to enable/disable callthrough service via a web service. The web service and its parameters are described in detail in Web Call-Through page.
Properties:
cth_ws_url cth_ws_method cth_ws_contentType cth_ws_postData cth_ws_customHeaders
Call Forwarding¶
forwardingEnabled
¶
<forwardingEnabled>1</forwardingEnabled>
Default value: 0
When set to 1, any incoming call will be automatically forwarded to the number defined in forwardingNumber field.
forwardingNumber
¶
<forwardingNumber>500</forwardingNumber>
Default value: empty.
All incoming calls are redirected to the number you specify.
Miscellaneous¶
vpnStartupUrl
¶
<vpnStartupUrl>https://my.server.com/dummy</vpnStartupUrl>
Default value: empty
If non empty, the web service is called before every registration attempt. Sometimes it’s required to bring VPN up.
customActionUrl
¶
<customActionUrl>https://example.com/action?uri=%uri%&user=%account[username]%</customActionUrl>
Default value: empty
Defines the URL which is opened in external browser in case the
openUrl
Dial Action is invoked on a number or SIP uri. The placeholder%uri%
is replaced by the actual dialed number. See Dial Actions for more details and also Introduction about web service parameter placeholders.
Call Tones¶
These are tones played locally to indicate call progress or status. The tones may be composed from elementary tones using periodic and compound operations. Durations are always in milliseconds, amplitudes can be either positive numbers, in which case they are used directly as amplitude of 16bit samples, or as negative values, interpreted as decibels (ITU-T recommendation is to use -24dBm0. Frequencies are in Hertz. Characters after digits are ignored, so it’s a good idea to write the units after the number for clarity (see examples below).
Elementary Tones¶
sine( duration, amplitude, freqs… )
Creates a sine wave of given duration and amplitude. In case more than one frequency is specified, the tone will play the sine waves of given frequencies simultaneously.
silence( duration )
Plays a silence of given duration.
wav( "filenameWithExtension" )
Plays a WAV or CAF file. The files should be PCM or ADPCM (ima4) encoded, 8 or 16KHz. Stereo files are converted to mono.
On iOS, it should specify filename with extension, the library will first search in
NSApplicationSupportDirectory
, if not found, then in bundleresourcePath
.On Android, the parameter should be asset filename.
Tone Operators¶
periodic( tones… )
Plays the given tone segments in a loop. Tones may be any elementary tones, or compound tone.
compound( tones… )
Plays the given tones simultaneously. For simultaneous sine waves, a shortcut syntax of
sine(…)
with multiple frequencies is easier to write.tryingTone
<tryingTone>periodic(sine(50ms,500,440Hz),silence(40ms))</tryingTone>
Played when outgoing call is being establishes, before we get Ringing notification from the remote side.
ringingTone
<ringingTone>periodic(sine(2000ms,2500,440Hz),silence(4000ms))</ringingTone>
Played when outgoing call is ringing at the remote side.
For examples of common ringback tones refer to table below:
Country
Tone definition
Canada
periodic(sine(2000ms,2500,440Hz,480Hz),silence(4000ms))
Italy
periodic(sine(1000ms,2500,425Hz),silence(4000ms))
Japan
periodic(sine(1000ms,2500,400Hz,416Hz),silence(2000ms))
UK
periodic(sine(400ms,2500,400Hz,450Hz),silence(200ms),sine(400ms,2500,400Hz,450Hz),silence(2000ms))
US
periodic(sine(2000ms,2500,440Hz,480Hz),silence(4000ms))
endCallTone
<endCallTone>periodic(sine(300ms,1000,400Hz),silence(400ms),sine(300ms,1000,400Hz),silence(400ms),sine(300ms,1000,400Hz),silence(700000ms))</endCallTone>
Played to notify local user that the remote party hung up the call.
busyTone
<busyTone>periodic(sine(500ms,2000,400Hz),silence(500ms))</busyTone>
Played when we receive “Busy” answer on outgoing call.
For examples of common busy tones refer to table below:
Country
Tone definition
UK
periodic(sine(375ms,2500,400Hz,450Hz),silence(375ms))
US
periodic(sine(500ms,2500,480Hz,620Hz),silence(500ms))
callWaitingTone
<callWaitingTone>periodic(silence(1000ms),sine(300ms,7500,440Hz),silence(9000ms))</callWaitingTone>
Played in case there is an established call and another incoming call is waiting to be answered.
zrtpHandshakeTone
<zrtpHandshakeTone>periodic(sine(50ms,500,400Hz,450Hz),silence(80ms))</zrtpHandshakeTone>
Played during ZRTP handshake.
Auto Answer¶
Note
If callkit is enabled on iOS we are unable to auto-answer the calls on lock screen or in background.
appInitiatedAutoAnswerEnabled
¶
<appInitiatedAutoAnswerEnabled>1</appInitiatedAutoAnswerEnabled>
- Default
0
- Description
Determines if the incoming call should be answered automatically. The application waits the amount of seconds configured via autoAnswerTimeoutInSeconds before answering the call automatically.
autoAnswerTimeoutInSeconds
¶
<autoAnswerTimeoutInSeconds>5</autoAnswerTimeoutInSeconds>
- Default
0
- Description
If appInitiatedAutoAnswerEnabled is
1
, the amount of time to wait before answering the call automatically. A value of0
means the call is immediately answered.
sipInitiatedAutoAnswerEnabled
¶
<sipInitiatedAutoAnswerEnabled>1</sipInitiatedAutoAnswerEnabled>
- Default
0
- Description
If enabled (value
1
), the call is honoring the incoming SIP call headerCall-Info:
withanswer-after=xx
, the timeout will be taken from this SIP header.
Busy Lamp Field¶
Busy Lamp Field allows to observe status of some phone extension on your device. For example, you can create a quick dial (favorite) entry and check that you are interested in Busy Lamp Field status. The app then shows an indicator whether this extension is on-hook or off-hook.
On SIP level, the app has to SUBSCRIBE to on-hook and off-hook events from this extension (dialog-info
event
package). The app therefore only receives info about subscribed extensions. The extensions to subscribe to are stored
in account XML, in a format described below.
blf
¶
<blf>
<uri>1001</uri>
<uri>1002</uri>
<uri>5000</uri>
</blf>
- Default
<empty>
- Description
blf
node contains list of uris/extensions. The app will subscribe to the listed uris for dialog-info events.
Note
For External Provisioning, if the incoming XML contains the <blf> node with some <uri> entries, the list from incoming XML replaces the existing list, discarding any previous values (if the priorities allow that, see Mergeable XML. It is also possible to provision using “union” operation, as in: <blf priority=”40” operation=”subnode-union”>….</blf> in which case the lists are merged together.
CardDav¶
cardDavTitle
¶
<cardDavTitle>My CardDav</cardDavTitle>
- Default
No default value
- Description
Title shown in the app for CardDav contacts, in Contacts tab.
cardDavPrincipalUrl
¶
<cardDavPrincipalUrl>somecarddavurl.com</cardDavPrincipalUrl>
- Default
No default value
- Description
CardDAV principal URL. You can use placeholders like %account[username]% in the URL for any fields from Account XML.
cardDavRefresh
¶
<cardDavRefresh>180</cardDavRefresh>
- Default
180
- Description
CardDAV refresh period in seconds. The app will check for any changes on the server periodically.
cardDavUsername
¶
<cardDavUsername>johndoe</cardDavUsername>
- Default
No default value
- Description
Username for CardDav. If not sent, will default to use SIP username.
cardDavPassword
¶
<cardDavPassword>secrete</cardDavPassword>
- Default
No default value
- Description
Password for CardDav. If not sent, will default to use SIP password.
Desktop Options¶
genericSmsFetchInterval
¶
<genericSmsFetchInterval>8000</genericSmsFetchInterval>
- Default
8000
- Description
The time in milliseconds for polling interval of fetching web messages.
genericSmsFetchInBackgroundInterval
¶
<genericSmsFetchInBackgroundInterval>20000</genericSmsFetchInBackgroundInterval>
- Default
30000
- Description
The time in milliseconds for polling interval of fetching web messages when the Desktop app is in the background.
Video Conferencing¶
conferencingEnabled
¶
<conferencingEnabled>0</conferencingEnabled>
- Default
1
- Description
When the value in the account.xml is set to “0” then Video Conferencing is explicitly disabled for the device. In case of more account.xmls at least one of these account.xmls must have value set to “0” to disable Video Conferencing for the device.
Account Example¶
<account>
<username>xxx</username>
<password>secret</password>
<host>1.2.3.4</host>
<codecOrder>9,0,8,102,3</codecOrder>
<codecOrder3G>102,3,9,0,8</codecOrder3G>
</account>