API
SIP.UA Configuration Parameters
- uri
- wsServers
- allowLegacyNotifications
- authenticationFactory
- authorizationUser
- autostart
- connectionRecoveryMaxInterval
- connectionRecoveryMinInterval
- displayName
- hackCleanJitsiSdpImageattr
- hackStripTcp
- hackIpInContact
- hackViaTcp
- hackWssInTransport
- iceCheckingTimeout
- instanceId
- log
- mediaHandlerFactory
- noAnswerTimeout
- password
- register
- registerExpires
- registrarServer
- rel100
- replaces
- rtcpMuxPolicy
- stunServers
- traceSip
- turnServers
- usePreloadedRoute
- userAgentString
- wsServerMaxReconnection
- wsServerReconnectionTimeout
Parameters
uri
String
- SIP URI associated to the User Agent. This is a SIP address given to you by your provider. By default, URI is set to anonymous.X@anonymous.invalid
, where X is a random token generated for each UA.
wsServers
Set of WebSocket URIs to connect to. By default, the WebSocket URI is set to wss://edge.sip.onsip.com
. If not specified, port 80 will be used for WS URIs and port 443 will be used for WSS URIs. This parameter can be expressed in multiple ways:
-
String
to define a single WebSocket URI. -
Array
ofStrings
to define multiple WebSocket URIs. -
Array
ofObject
to define multiple WebSocket URIs with weight. URIs with higher weights are attempted before those with lower weights.
wsServers: "ws://sip-ws.example.com"
wsServers: "ws://sip-ws.example.com:8443/sip?KEY=1234"
wsServers: [
"ws://sip-ws-1.example.com",
"ws://sip-ws-2.example.com"
]
wsServers: [
{ // First connection attempt
ws_uri: "ws://sip-ws-1.example.com",
weight: 10
},
{
ws_uri: "ws://sip-ws-2.example.com",
weight: 1
}
]
allowLegacyNotifications
If set to true, the user agent will allow NOTIFYs received without subscriptions to be emitted to a notify
event listener on the UA. Default value is false.
allowLegacyNotifications: true
authenticationFactory
Similar to mediaHandlerFactory
, this parameter allows the application to use a custom authentication model with SIP.js.
The factory is passed the UA and should return credentials. Modifying this is very advanced; please refer to the source code for examples.
By default, Digest Authentication is used.
authorizationUser
Username (String
) to use when generating authentication credentials. If not defined the value in uri parameter is used.
authorizationUser: "alice123"
autostart
If set to true, the user agent calls the .start()
method upon being created. Default value is true.
autostart: true
connectionRecoveryMaxInterval
Maximum interval (Number
) in seconds between WebSocket reconnection attempts. Default value is 30.
connectionRecoveryMaxInterval: 60
connectionRecoveryMinInterval
Minimum interval (Number
) in seconds between WebSocket reconnection attempts. Default value is 2.
connectionRecoveryMinInterval: 4
displayName
Descriptive name (String
) to be shown to the called party when calling or sending IM messages. It must NOT be enclosed between double quotes even if the given name contains multi-byte symbols (SIPjs will always enclose the display_name
value between double quotes).
displayName: "Alice ¶€ĸøĸø"
hackCleanJitsiSdpImageattr
Remove a=imageattr lines from the SDP produced by Jitsi calling a WebRTC endpoint with certain codecs. Valid values are true
and false
(Boolean
). Default value is false
.
Version: 0.7.6+
hackCleanJitsiSdpImageattr:true
hackStripTcp
Remove TCP candidates generated from the browser gathering ICE candidates. Valid values are true
and false
(Boolean
). Default value is false
.
Version 0.7.6+
hackStripTcp:true
hackIpInContact
Set a random IP address as the host value in the Contact header field and Via sent-by parameter. Useful for SIP registrars not allowing domain names in the Contact URI. Valid values are true
and false
(Boolean
). Default value is false
.
hackIpInContact: true
hackViaTcp
Set Via transport parameter in outgoing SIP requests to “TCP”. Useful when traversing SIP nodes that are not ready to parse Via headers with “WS” or “WSS” value in a Via header. Valid values are true
and false
(Boolean
). Default value is false
.
hackViaTcp: true
hackWssInTransport
Set the transport parameter to wss
when used in SIP URIs. This replaces ws
, which is the default and required by RFC 7118, but some SIP servers do not like that.
hackWssInTransport: true
iceCheckingTimeout
When setting up a session, how long (in milliseconds) to allow the browser to collect ICE candidates before proceeding. Lowering this timeout will speed up signaling but potentially fail to set up connections in some network topologies. Default value is 5 seconds, and this can be set as low as 0.5 seconds.
iceCheckingTimeout: 5000
instanceId
String
indicating the UUID URI to be used as instance ID to identify the UA instance when using GRUU.
instanceId: "uuid:8f1fa16a-1165-4a96-8341-785b1ef24f12"
instanceId: "8f1fa16a-1165-4a96-8341-785b1ef24f12"
log
Object
providing the desired log behavior.
- builtinEnabled
Boolean
indicating whether SIPjs should write log messages in the browser console. Default value is true
.
- level
Number
or String
indicating the verbose level of the SIPjs log. Valid values are 3
, 2
, 1
, 0
or "debug"
, "log"
, "warn"
, "error"
respectively. Default value is 2
(or log
).
- connector
User defined Function
which will be called everytime a log is generated, according to the enabled
and level
options.
The function is called with the following semantics:
/*
level: String representing the level of the log message
('debug', 'log', 'warn', 'error')
category: String representing the SIPjs instance class firing
the log. ie: 'sipjs.ua'
label: String indicating the 'identifier' of the class instance
when the log level is '3' (debug). ie: transaction.id
content: String representing the log message
*/
connector(level, category, label, content);
mediaHandlerFactory
A function(session, options) that returns an object that acts like a SIP.MediaHandler. See SIP.WebRTC.MediaHandler.defaultFactory for an example.
noAnswerTimeout
Time (in seconds) (Number
) after which an incoming call is rejected if not answered. Default value is 60
.
noAnswerTimeout: 120
password
SIP Authentication password (String
). Default value is null
.
password: "1234"
register
Indicate if a SIP User Agent should register automatically when starting. Valid values are true
and false
(Boolean
). Default value is true
.
register: false
registerExpires
Registration expiry time (in seconds) (Number
). Default value is 600
.
registerExpires: 300
registrarServer
Set the SIP registrar URI. Valid value is a SIP URI without username. Default value is null
which means that the registrar URI is taken from the uri parameter (by removing the username).
registrarServer: 'sip:registrar.mydomain.com'
rel100
Constant
representing whether the UA should do 100rel. Accepts SIP.C.supported.REQUIRED
, SIP.C.supported.SUPPORTED
, and SIP.C.supported.UNSUPPORTED
. Default value is SIP.C.supported.UNSUPPORTED
.
rel100: SIP.C.supported.REQUIRED
replaces
Constant
representing whether the UA should support the SIP Replaces header.
If you enable support for Replaces, please be sure to listen for the replaced
event event on each Session.
Accepts SIP.C.supported.SUPPORTED
, and SIP.C.supported.UNSUPPORTED
. Default value is SIP.C.supported.UNSUPPORTED
.
replaces: SIP.C.supported.SUPPORTED
rtcpMuxPolicy
String
that overrides the default Multiplexing RTP (rtp-mux
) mode used for the peer connection. Setting this to “negotiate” may allow endpoints that do not support rtp-mux
to work with SIP.js. If not specified, the browser’s default policy is used.
Version: 0.7.7+
rtcpMuxPolicy: "negotiate"
stunServers
String
or Array
of Strings
indicating the STUN server(s) to use for IP address discovery. Values must include “stun:” or “stuns:” schema. Default value is ["stun:stun.l.google.com:19302"
].
stunServers: "stun:example.org"
stunServers: ["stun:example.org", "stuns:example.org"]
stunServers: ["stun:example.org:8000"]
traceSip
Indicate whether incoming and outgoing SIP request/responses must be logged in the browser console (Boolean
). Default value is false
.
traceSip: true
turnServers
Object
or Array
of Objects
indicating the TURN server(s) and corresponding username and password to be used for media relay. ‘url’ values can include “turn:” or “turns” schema. No TURN server is set by default.
turnServers: {
urls:"turn:exam.org",
username:"alice",
password:"racecar"
}
turnServers: {
urls:["turn:exam.org",
"turn:exam.org"],
username:"Al",
password:"yo"
}
turnServers: [{
urls:"turn:exam.org",
username:"alice",
password:"racecar"
}]
turnServers: [
{
urls:"turn:exam.org",
username:"alice",
password:"racecar"
},
{
urls:"turn:exam.org?transport=udp",
username:"bob",
password:"dog"
}
]
usePreloadedRoute
If set to true every SIP initial request sent by SIP.js includes a Route header with the SIP URI associated to the WebSocket server as value. Some SIP Outbound Proxies require such a header. Valid values are true
and false
(Boolean
). Default value is false
.
wsServers: "ws://example.org/sip-ws"
usePreloadedRoute: true
The Route header will look like Route: <sip:example.org;lr;transport=ws>
wsServers: "wss://example.org:8443"
usePreloadedRoute: true
The Route header will look like Route: <sip:example.org:8443;lr;transport=ws>
userAgentString
If this is set then the User-Agent header will have this string appended after name and version.
userAgentString: "myAwesomeApp"
The User-Agent header will look like User-Agent: myAwesomeApp
wsServerMaxReconnection
The number of times to attempt to reconnect to a WebSocket when the connection drops. The default value is 3.
wsServerReconnectionTimeout
The time (in seconds) to wait between WebSocket reconnection attempts. The default timeout is 4 seconds.