/ home / the Javascript SIP library / Documentation / API / JsSIP.UA

Class JsSIP.UA

JsSIP SIP User Agent class.

Instantiation

A User Agent is associated to a SIP user account. This class requires some configuration parameters for its initialization which are provided through a configuration object. Check the full UA Configuration Parameters list.

Instantiation of this class will raise an exception if any of the mandatory parameters is not defined or due to a malformed parameter value.

Throws

Example

var socket = new JsSIP.WebSocketInterface('wss://sip.example.com');
var configuration = {
  sockets : [ socket ],
  uri     : 'sip:alice@example.com',
  ha1     : '350fe29ce3890bd85d105998b0a95cf7',
  realm   : 'sip.example.com'
};

var ua = new JsSIP.UA(configuration);

Instance Methods

start()

Connects to the signaling server and restores the previous state if previously stopped. For a fresh start, registers with the SIP domain if register parameter in the UA’s configuration is set to true.

stop()

Saves the current registration state and disconnects from the signaling server after gracefully unregistering and terminating active sessions if any.

register()

Registers the UA.

Note: If register parameter is set to true in UA Configuration Parameters, the UA will register automatically.

unregister(options=null)

Unregisters the UA.

Parameters

options
Optional Object with extra parameters (see below).

Fields in options Object

all
Optional Boolean for unregistering all bindings of the same SIP user. Default value is false.
var options = {
  all: true
};

ua.unregister(options);

registrator()

Gets the JsSIP.Registrator instance.

call(target, options=null)

Makes an outgoing multimedia call.

Parameters

target
Destination of the call. String representing a destination username or a complete SIP URI, or a JsSIP.URI instance.
options
Optional Object with extra parameters (see below).

Fields in options Object

mediaConstraints
Object with two valid fields (audio and video) indicating whether the session is intended to use audio and/or video and the constraints to be used. Default value is both audio and video set to true.
mediaStream
MediaStream to transmit to the other end.
pcConfig
Object representing the RTCPeerConnection RTCConfiguration.
rtcConstraints
Object representing RTCPeerconnection constraints.
rtcOfferConstraints
Object representing constraints for RTCPeerconnection createOffer().
rtcAnswerConstraints
Object representing constraints for RTCPeerconnection createAnswer() (to be used for future incoming reINVITE or UPDATE with SDP offer).
eventHandlers
Optional Object of event handlers to be registered to each call event. Define an event handler for each event you want to be notified about.
extraHeaders
Array of Strings with extra SIP headers for the INVITE request.
anonymous
Boolean field indicating whether the call should be done anonymously. Default value is false.
sessionTimersExpires
Number (in seconds) for the default Session Timers interval (default value is 90, do not set a lower value).
fromUserName
String to override the user name in the From header.
fromDisplayName
String to override the display name in the From header. Overrides the UA configuration parameter display_name.

Example

// HTML5 <video> elements in which local and remote video will be shown
var views = {
  'selfView':   document.getElementById('my-video'),
  'remoteView': document.getElementById('peer-video')
};

// Register callbacks to desired call events
var eventHandlers = {
  'progress':   function(data){ /* Your code here */ },
  'failed':     function(data){ /* Your code here */ },
  'confirmed':  function(data){ /* Your code here */ },
  'ended':      function(data){ /* Your code here */ }
};

var options = {
  'eventHandlers': eventHandlers,
  'extraHeaders': [ 'X-Foo: foo', 'X-Bar: bar' ],
  'mediaConstraints': {'audio': true, 'video': true},
  'pcConfig': {
    'iceServers': [
      { 'urls': ['stun:a.example.com', 'stun:b.example.com'] },
      { 'urls': 'turn:example.com', 'username': 'foo', 'credential': ' 1234' }
    ]
  }
};

ua.call('sip:bob@example.com', options);

sendMessage(target, body, options=null)

Sends an instant message making use of SIP MESSAGE method.

Parameters

target
Destination of the message. String representing a destination username or a complete SIP URI, or a JsSIP.URI instance.
body
Message content. String representing the body of the message.
options
Optional Object with extra parameters (see below).

Fields in options Object

contentType
Optional String representing the content-type of the body. Default text/plain.
eventHandlers
Optional Object of event handlers to be registered to each JsSIP.Message event. Define an event handler for each event you want to be notified about.
extraHeaders
Optional Array of Strings with extra SIP headers for each MESSAGE request.
fromUserName
String to override the user name in the From header. New!
fromDisplayName
String to override the display name in the From header. Overrides the UA configuration parameter display_name. New!

Example

var text = 'Hello Bob!';

var eventHandlers = {
  'succeeded': function(data){ /* Your code here */ },
  'failed':    function(data){ /* Your code here */ };
};

var options = {
  'eventHandlers': eventHandlers
};

ua.sendMessage('sip:bob@example.com', text, options);

sendOptions(target, body, options=null)

Sends a SIP OPTIONS request to a remote endpoint.

Parameters

target
Destination of the request. String representing a destination username or a complete SIP URI, or a JsSIP.URI instance.
body
Optional String representing the body of the request.
options
Optional Object with extra parameters (see below).

Fields in options Object

contentType
Optional String representing the content-type of the body. Default application/sdp.
eventHandlers
Optional Object of event handlers to be registered to each JsSIP.Options event. Define an event handler for each event you want to be notified about.
extraHeaders
Optional Array of Strings with extra SIP headers for the OPTIONS request.

Example

var eventHandlers = {
  'succeeded': function(data){ /* Your code here */ },
  'failed':    function(data){ /* Your code here */ };
};

var options = {
  'eventHandlers': eventHandlers
};

ua.sendOptions('sip:bob@example.com', null, options);

terminateSessions(options=null)

Terminates ongoing calls.

Parameters

options
Optional Object with extra parameters as defined in JsSIP.RTCSession for call termination.

isRegistered()

Returns true if the UA is registered, false otherwise.

isConnected()

Returns true if the transport is connected, false otherwise.

get(parameter)

Retrieves the computed configuration parameter once in runtime. Currently the following values can be retrieved: authorization_user, realm, ha1 and authorization_jwt.

parameter
UA configuration parameter name.

set(parameter, value)

Modifies the given UA configuration parameter in runtime (once started). Currently just authorization_user, password, realm, ha1, authorization_jwt and display_name can be modified.

Returns true if the modifitation could be done.

parameter
UA configuration parameter name.
value
New value.

Events

JsSIP.UA class defines a series of events. Each of them allows callback functions registration in order to let the user execute a handler for each given stimulus.

connecting

Fired for each transport connection attempt.

Event data fields

socket
JsSIP.Socket instance being connecting.
attempts
Number indicating the transport connection attempts.

connected

Fired when the transport connection is established.

Event data fields

socket
JsSIP.Socket instance which has connected.

disconnected

Fired when the transport connection attempt (or automatic re-attempt) fails.

Event data fields

socket
JsSIP.Socket instance.
error
Boolean indicating whether the socket disconnected due to an error
code
Optional Number indicating the socket disconnection code.
reason
Optional String indicating the socket disconnection reason.

registered

Fired for a successfull registration.

Event data fields

response
JsSIP.IncomingResponse instance of the received SIP 2XX response.

unregistered

Fired for an unregistration. This event is fired in the following scenarios:

  • As a result of a unregistration request. UA.unregister().
  • If being registered, a periodic re-registration fails.

Event data fields

response
JsSIP.IncomingResponse instance of the received SIP response for a (un)REGISTER SIP request.
cause
null for possitive response to un-REGISTER SIP request. In other case, one value of Failure and End Causes.

registrationFailed

Fired for a registration failure.

Event data fields

response
JsSIP.IncomingResponse instance of the received SIP negative response if the failure is generated by the recepcion of such response, null otherwise.
cause
One value of Failure and End Causes.

registrationExpiring

Fired a few seconds before the registration expires. If the application does not set any listener for this event, JsSIP will just re-register as usual.

If the application subscribes to this event, it’s responsible of calling ua.register() within the registrationExpiring event (otherwise the registration will expire).

This event provides the application with a chance to perform async operations before re-registering. Useful for those environments using an externally obtained “token” within a custom SIP header in the REGISTER request.

newRTCSession

Fired for an incoming or outgoing session/call.

Event data fields for an incoming session

originator
‘remote’ String. The new session is generated by the remote peer.
session
JsSIP.RTCSession instance of the session.
request
JsSIP.IncomingRequest instance of the received INVITE request.

Event data fields for an outgoing session

originator
‘local’ String. The new session is generated by the local user.
session
JsSIP.RTCSession instance of the session.
request
JsSIP.OutgoingRequest instance of the outgoing INVITE request.

newMessage

Fired for an incoming or outgoing MESSAGE request.

Event data fields for an incoming message

originator
‘remote’ String. The new message is generated by the remote peer.
message
JsSIP.Message instance.
request
JsSIP.IncomingRequest instance of the received MESSAGE request.

Event data fields for an outgoing message

originator
‘local’ String. The new message is generated by the local user.
message
JsSIP.Message instance.
request
JsSIP.OutgoingRequest instance of the outgoing MESSAGE request.

newOptions

Fired for an incoming or outgoing OPTIONS request.

Event data fields for an incoming OPTIONS request

originator
‘remote’ String. The new options is generated by the remote peer.
message
JsSIP.Options instance.
request
JsSIP.IncomingRequest instance of the received OPTIONS request.

Event data fields for an outgoing OPTIONS request

originator
‘local’ String. The new options is generated by the local user.
message
JsSIP.Options instance.
request
JsSIP.OutgoingRequest instance of the outgoing OPTIONS request.

sipEvent

Fired for an incoming out of dialog NOTIFY request.

Event data fields

event
Event instance. See below.
request
JsSIP.IncomingRequest instance of the received NOTIFY request.

event parameter

event
‘event-type’ defined in the Event header field.
params
Object containing the parameters received in the Event header field.

/ home / the Javascript SIP library / Documentation / API / JsSIP.UA