API

SIP.Session

The class SIP.Session represents a WebRTC media (audio/video) session. It can be initiated by the local user or by a remote peer. Sessions are created via SIP INVITE messages. Sessions also implement one of SIP.ClientContext or SIP.ServerContext, depending on if they are the result of outbound (client) or inbound (server) INVITE requests.

Construction

The Session constructor is intended for internal use only. Instead, outbound Sessions are created through the SIP.UA.invite method. Inbound Sessions are obtained via the SIP.UA invite event callback.

Examples

// Create a new outbound (User Agent Client) Session
var session = myUA.invite('alice@example.com');
// Accept an inbound (User Agent Server) Session
myUA.on('invite', function (session) {
  session.accept();
});

Instance Variables

startTime

Date - Date object indicating the time when the session started. Takes its value at the moment when the accepted event is fired.

endTime

Date - Date object indicating the time when the session ended. Takes its value at the moment when the terminated event was fired.

ua

SIP.UA - Inherited from SIP.ClientContext or SIP.ServerContext.

method

String - The value of method is always "INVITE". Inherited from SIP.ClientContext or SIP.ServerContext.

request

SIP.IncomingRequest or SIP.OutgoingRequest - Inherited from SIP.ClientContext or SIP.ServerContext.

localIdentity

SIP.NameAddrHeader - Inherited from SIP.ClientContext or SIP.ServerContext.

remoteIdentity

SIP.NameAddrHeader - Inherited from SIP.ClientContext or SIP.ServerContext.

data

Object - Empty object for application to define custom data. Inherited from SIP.ClientContext or SIP.ServerContext.

Instance Methods

dtmf(tone[, options])

Send one or multiple DTMF tones making use of SIP INFO method.

Parameters

Name Type Description
tone String or Number One or multiple valid DTMF symbols. Converts Number to String using toString().
options Object Optional Object with extra parameters (see below).
options.extraHeaders Array Optional Array of Strings with extra SIP headers for each INFO request.
options.duration Number Positive decimal Number indicating the duration of the tone expressed in milliseconds. Default value is 100.
options.interToneGap Number Positive decimal Number indicating the interval between two tones expressed in milliseconds. Default value is 500.

Throws

TypeError INVALID_STATE_ERROR

Returns

Type Description
SIP.Session This Session

Example 1

call.dtmf(1);
call.dtmf(4);

Example 2

var tones = '1234#';

var extraHeaders = [ 'X-Foo: foo', 'X-Bar: bar' ];

var options = {
  'duration': 160,
  'interToneGap': 1200,
  'extraHeaders': extraHeaders
};

call.dtmf(tones, options);

bye([options])

Sends a BYE request on a confirmed session.

Parameters

Name Type Description
options Object Optional Object with extra parameters (see below).
options.status_code Number The SIP response code that will be used in the upcoming response instead of the default.
options.reason_phrase String The SIP reason phrase.
options.body String represents the SIP message body (in case this parameter is set, a corresponding Content-Type header field must be set in extraHeaders field).
options.extraHeaders Array of Strings Extra SIP headers for the request.

Throws

TypeError INVALID_STATE_ERROR

getLocalStreams()

Returns an array of MediaStream objects representing the streams that are currently sent in this Session.

Returns

Type Description
Array of MediaStream The local media stream

getRemoteStreams()

Returns an array of MediaStream objects representing the streams that are currently received in this session.

Type Description
Array of MediaStream The remote media stream

refer(target[, options])

Send a REFER request. A REFER occurs when persons A and B have an active call session, and A wants to transfer B to speak with C. This is called a transfer, and these transfers can be attended or blind. An attended transfer occurs when A creates a session with C before connecting B to speak with C. A blind transfer occurs when A causes B to create a session with C, so A and C have no contact. SIP.js only supports blind transfers.

Parameters

Name Type Description
target String The target address to be referred to.
options Object Optional Object with extra parameters (see below).
options.extraHeaders Array of Strings Extra SIP headers for the request.

Returns

Type Description
SIP.Session This session

Throws

TypeError INVALID_STATE_ERROR

mute([options])

Helper function that will call through to the MediaHandler mute function, then emit a muted event.

Name Type Description
options Object Optional Object with extra parameters.

unmute([options])

Helper function that will call through to the MediaHandler unmute function, then emit an unmuted event.

Name Type Description
options Object Optional Object with extra parameters.

Instance Methods (Outbound/Client)

cancel([options])

Overrides SIP.ClientContext.cancel

Instance Methods (Inbound/Server)

progress([options])

Overrides SIP.ServerContext.progress. Additional parameters specific to INVITE requests can be specified.

As per RFC 3262, non-100 provisional responses may be transmitted reliably. Support for this is determined by the initial invite request (see the rel100 parameter on ua.invite()). If the INVITE prohibits reliable provisional responses, all responses sent with progress will be transmitted unreliably. Likewise, if the INVITE requires 100rel, all non-100 responses will be sent reliably. If 100rel is supported, reliable transmission is determined by the options.rel100 parameter. Note that reliable provisional responses typically contain the SDP answer and so an options.media parameter is also provided.

Parameters

Name Type Description
options.rel100 Boolean If the INVITE request supports 100rel, progress responses will be transmitted reliably based on this option. If the INVITE request requires or does not support 100rel, this option is ignored.
options.media Object Media constraints to use in a reliable provisional response. After the response is PRACKed, early media will begin. If the session is later accepted, these media constraints will be used.
ServerContext Parameters   See SIP.ServerContext.progress.

accept([options])

Overrides SIP.ServerContext.accept. Additional parameters specific to INVITE requests can be specified.

Parameters

Name Type Description
options.RTCConstraints Object Object representing RTCPeerconnection constraints
options.media Object Optional Object with media related parameters (see below)
options.media.constraints Object 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. If media constraints are not provided, {audio: true, video: true} will be used
options.media.stream MediaStream MediaStream to transmit to the other end
options.media.render Object Video or audio elements that streams should be automatically rendered in. For example: { remote: { video: element, audio: element } }
ServerContext Parameters   See SIP.ServerContext.accept.

reject([options])

Overrides SIP.ServerContext.reject

reply([options])

Overrides SIP.ServerContext.reply

Events

The SIP.Session class defines a series of events. Each of them allows a callback function to be defined in order to let the user execute a handler for each given stimulus.

Every event handler is executed with a SIP.Event instance as the only argument.

progress

Fired each time a provisional (100-199) response is received.

on('progress', function (response) {})

Name Type Description
response SIP.IncomingResponse The received response

accepted

Fired each time a successful final (200-299) response is received.

on('accepted', function (data) {})

Outbound sessions emit accepted with the following parameters:

Name Type Description
data Object A wrapper object containing the event data
data.code Number The status code of the received response, between 200 and 299.
data.response SIP.IncomingResponse The received response

Inbound sessions do not currently provide any parameters when emitting the accepted event. Track this bug on GitHub.

rejected

Fired each time an unsuccessful final (300-699) response is received. Note: This will also emit a failed event.

on('rejected', function (response, cause) {})

Name Type Description
response SIP.IncomingResponse The received response
cause String The reason phrase associated with the SIP response code.

failed

Fired when the request fails, whether due to an unsuccessful final response or due to timeout, transport, or other error.

on('failed', function (response, cause) {})

Name Type Description
response SIP.IncomingResponse The received response. On a failure not due to a SIP message, this will be null.
cause String The reason phrase associated with the SIP response code, or one of Failure and End Causes.

connecting

Fired when ICE is starting to negotiate between the peers.

on('connecting', function () {})

There are no documented arguments for this event

terminated

Fired when an established call ends.

Please note: The terminated event in 0.6.x versions does not always behave as you would expect. Instead, to reliably determine the end of a call, it is recommended that you provide listeners for both the failed (for when a Session fails before being accepted) and bye (for when an accepted Session is terminated) events. Due to a bug, you also need to listen for the cancel event. This is a known issue and is resolved properly on the master branch, to be released in 0.7.0.

on('terminated', function(message, cause) {})

Name Type Description
message Object SIP.IncomingResponse instance of the received SIP response that caused the termination, if there was one.
cause   One value of Failure and End Causes, if there was one.

cancel

Fired when the session was canceled by the client.

on('cancel', function() {})

There are no documented arguments for this event

refer

Fired when a REFER is received, and the user would like to handle the transfer at the application level. To have SIP.js automatically follow the refer, use the session.followRefer(callback) function.

on('refer', function(request) {})

Name Type Description
request SIP.IncomingRequest Instance of the received SIP REFER request.

on('refer', session.followRefer(callback))

Name Type Description
callback function(request, newSession) Callback function to be called after the refer is followed.
request SIP.IncomingRequest Instance of the received SIP REFER request.
newSession SIP.Session The Session created by following the REFER

dtmf

Fired for an incoming or outgoing DTMF.

.on('dtmf', function(request, dtmf) {})

Name Type Description
request SIP.IncomingRequest Instance of the received SIP INFO request.
dtmf SIP.Session.DTMF DTMF instance.

muted

Fired when the session’s mute function is called and the MediaHandler’s mute function returns.

on('muted', function(data) {})

Name Type Description
data Object Contains which parts of the media stream were muted (See below).
data.audio boolean True if audio is muted, False if unmuted.
data.video boolean True if video is muted, False if unmuted.

unmuted

Fired when the session’s unmute function is called and the MediaHandler’s unmute function returns.

on('unmuted', function(data) {})

Name Type Description
data Object Contains which parts of the media stream were muted (See below).
data.audio boolean True if audio is unmuted, False if muted.
data.video boolean True if video is unmuted, False if muted.

bye

Fired when a BYE is sent.

on('bye', function(request) {})

Name Type Description
request SIP.IncomingRequest Instance of the received SIP BYE request.