Documentation

Class: Session

Session

Session represent the connected environment of an UA.
It's created after UA registration.

new Session()

Fires:

Extends

Methods

<static> getActiveSession()

Returns currently active session

Returns:
Type
Session

<static> getAvailableEvents()

Returns available events for this class

Returns:
Type
Array.<string>

allowMultipleCalls(value)

Set the possibilty for the user to have multiple calls at the same time (default true)

Parameters:
Name Type Description
value boolean
Returns:
Type
void

cloudRequest(url, params, method)

A promise for generic ApiRTC cloud platform REST requests
Avoid using this method unless you know what you are doing

Parameters:
Name Type Description
url String
params Object
method String
Returns:

json result in promise

Type
Promise.<object>

createConversation(conversationName, options)

Gets a conversation from name for N-N communication.

Deprecated in favor of Session#getOrCreateConversation.

Parameters:
Name Type Description
conversationName String

can be set to null to generate a random conversation name
options Object
Deprecated:
  • Yes
Returns:

returned conversation

Type
Conversation

disconnect(options)

Disconnects this session
Session will no longer receive events once disconnected

Parameters:
Name Type Description
options DisconnectOptions
Returns:
Type
Promise.<void>

getActiveConferences(options)

Gets all currently joined conferences

Parameters:
Name Type Description
options Object
Returns:

returned active conferences

Type
Object.<string, Conference>

getActiveConversations(options)

Gets all currently joined conversations

Parameters:
Name Type Description
options Object
Returns:

returned active conversations

Type
Object.<string, Conversation>

getApzToken()

Returns Apizee token associated to the session

Returns:

token

Type
string

getCall()

Returns call with Id

Returns:

call

Type
Object.<string, Call>

getCalls()

Returns call list

Returns:

call list

Type
Object.<string, Call>

getConference(conferenceName, options)

Gets a conference from name for enterprise N-N communication.

Deprecated in favor of Session#getOrCreateConversation.

Parameters:
Name Type Description
conferenceName string

can be set to null to generate a random conference name
options Object
Deprecated:
  • Yes
Returns:

returned conference

Type
Conference

getContact(id)

Returns contact from id. Deprecated : please use getOrCreateContact

Parameters:
Name Type Description
id String
Deprecated:
  • Yes
Returns:

contact

Type
Contact

getContactFromWebSession(webSessionId)

Gets contact from a websessionId

Parameters:
Name Type Description
webSessionId string
Returns:

Associated contact in promise

Type
Promise.<Contact>

getContacts(group)

Returns contact list

Parameters:
Name Type Description
group String

If defined, restrict list to user inside defined group
Returns:

contact list

Type
Object.<string, Contact>

getContactsArray(group)

Returns contact list array

Parameters:
Name Type Description
group String

If defined, restrict list to user inside defined group
Returns:

contact list array

Type
Array.<Contact>

getConversation(conversationName, options)

Gets a conversation from name for N-N communication.

Deprecated in favor of Session#getOrCreateConversation.

Parameters:
Name Type Description
conversationName String

can be set to null to generate a random conversation name
options Object
Deprecated:
  • Yes
Returns:

returned conversation

Type
Conversation

getId()

Returns this session's id

Returns:

id

Type
string

getOnlineContactsArray(group)

Returns online contact list array

Parameters:
Name Type Description
group String

If defined, restrict list to user inside defined group
Returns:

online contact list array

Type
Array.<Contact>

getOrCreateConference(name, options)

Gets or creates a conference for a given name.
If the given name matches the pattern ([^:]+): then a Conference is returned,
otherwise a Conversation is returned.
Note that options are only used to create Conference, i.e. if the Conference
already exists, options are ignored.

Parameters:
Name Type Description
name String

Conference name.
options object
Properties
Name Type Default Description
meshModeEnabled boolean false

Whether the mesh mode is enabled.
meshOnlyEnabled boolean false

Whether the mesh mode is the only mode allowed, i.e. no transition to another mode will occur.
Returns:

A Conversation or a Conference, depending on the given name.

Type
Conversation | Conference

getOrCreateContact(id)

Returns contact from id. Contact will be created if doesn't exist.

Parameters:
Name Type Description
id String
Returns:

contact

Type
Contact

getOrCreateConversation(name, options)

Gets or creates a Conversation for a given name.
If the given name matches the pattern ([^:]+): then a Conference is returned,
otherwise a Conversation is returned.
Note that options are only used to create Conversation, i.e. if the Conversation
already exists, options are ignored.

Parameters:
Name Type Description
name string

Conversation name.
options object
Properties
Name Type Default Description
e2ee E2EEOptions

Whether end-to-end encryption is enabled.
meshModeEnabled boolean false

Whether the mesh mode is enabled.
meshOnlyEnabled boolean false

Whether the mesh mode is the only mode allowed, i.e. no transition to another mode will occur.
moderationEnabled boolean false

Whether moderation is enabled for the new Conversation.
moderator boolean false

Whether the UserAgent shall be added to the list of moderators.
Returns:

A Conversation or a Conference, depending on the given name.

Type
Conversation | Conference

getPhotoUrl()

Gets this session's photo URL

Returns:

photo URL on success, null otherwise.

Type
string

getPresenceGroup()

Gets presence group in an array

Returns:

Presence group array

Type
Array.<string>

getSubscribedPresenceGroup()

Gets all subscribed presence group in an array

Returns:

Subscribed presence group array

Type
Array.<string>

getToken()

Returns this session's token if this is a cloud user's session, otherwise returns null

Returns:

token

Type
string

getUserAgent()

Returns this session's user agent

Returns:

ua

Type
UserAgent

getUserData()

Gets user data for this user session

Returns:

contact's userdata

Type
Object

getUsername()

Gets this session's username

Returns:

contact's username

Type
string

getWhiteboardClient()

Returns whiteboard client

Returns:

WhiteboardClient

Type
WhiteboardClient

joinConversationSpace(conversationSpace)

Join conversationSpace

Parameters:
Name Type Description
conversationSpace String

conversationSpace to join
Returns:
Type
Void

joinGroup(group)

Joins and subscribes to a group
The user will be visible to both users inside the group and users who subscribed to it

Parameters:
Name Type Description
group string

Presence group to join
Returns:
Type
void

joinPointerSharingRoom(roomId)

Joins a pointer sharing room identified by a given roomId.

Parameters:
Name Type Description
roomId string
Returns:
Type
Promise.<PointerSharingRoom>

leaveConversationSpace(conversationSpace)

Leave conversationSpace

Parameters:
Name Type Description
conversationSpace String

conversationSpace to leave
Returns:
Type
Void

leaveGroup(group)

Leaves and unsubscribes to a group
Users within the group and users who subscribed to it will be notified

Parameters:
Name Type Description
group String

Presence group to leave
Returns:
Type
Void

on(listener)

Adds a listener to a Observable event

Parameters:
Name Type Description
listener function
Inherited From:
Overrides:
Returns:

this instance for chaining

Type
Observable

removeListener(eventType, listener)

Remove existing listener to Observable event

Parameters:
Name Type Description
eventType String
listener function
Inherited From:
Overrides:
Returns:

this instance for chaining

Type
Observable

sendRawData(contact, data)

Promise to send rawData for older apps compatibility

Parameters:
Name Type Description
contact Contact
data Object
Returns:
Type
Promise.<void>

setCallStatsMonitoringEnabled(enabled, interval)

Enables call stats monotoring.

Parameters:
Name Type Description
enabled enabled

Whether to enable call stats monitoring
interval interval

Update interval in milliseconds
Returns:
Type
void

setMCUServer(server)

Sets MCU server to be used
Clients on different MCU servers will be unable to see each other's streams in a conversation / conference even if they are in the same room

Parameters:
Name Type Description
server string
Returns:
Type
void

setPhotoUrl(url)

Set session's photo URL

Parameters:
Name Type Description
url string
Returns:
Type
void

setQualityEvaluatingEnabled(enabled, interval)

Enables quality evaluating.

Parameters:
Name Type Description
enabled enabled

Whether to enable quality evaluating
interval interval

Update interval in milliseconds
Returns:
Type
void

setUserData(userData)

Sets user data for this user session
User data is visible from other users

Parameters:
Name Type Description
userData Object
Returns:
Type
void

setUsername(username)

Set session's username

Parameters:
Name Type Description
username string
Returns:
Type
void

startRecordingOutgoingStream(mode, filename)

Starts recording the first user's outgoing stream
NOTE : This function is present for backward compatibility purposes, prefer the use of a recorded call or Stream.startRecord() instead

Parameters:
Name Type Description
mode string

can be 'AUDIO-ONLY', 'VIDEO-ONLY', 'AUDIO-VIDEO'
filename string
Returns:
Type
void

stopRecordingOutgoingStream()

Stops the recording started with Session.startRecordingOutgoingStream() and returns information to get the record from the server
NOTE : This function is present for backward compatibility purposes, prefer the use of a recorded call or Stream.startRecord() instead

Returns:

Record information in promise

Type
Promise.<RecordInformation>

subscribeToGroup(group)

Subscribe to a group and know who is present in the group
Unless you also joined the group, the user will not be visible to others within this group

Parameters:
Name Type Description
group string

Presence group to subscribe to
Returns:
Type
void

unsubscribeToGroup(group)

Unsubscribe to a group, the session will no longer receive events from user joining and leaving this group

Parameters:
Name Type Description
group string

Presence group to unsubscribe to
Returns:
Type
void

Events

contactData

Fired when data is received from a contact

Type: object
Properties:
Name Type Description
sender Contact
content object

contactListUpdate

Fired when the contact list has been updated
The contact list is updated when a contact leaves a group, joins a group or if its user data changed

Type: object
Properties:
Name Type Description
leftGroup Object.<string, Array.<Contact>>

Contacts who left a group mapped by group
joinedGroup Object.<string, Array.<Contact>>

Contacts who joined a group mapped by group
userDataChanged Array.<Contact>

Contacts whose userdata changed

contactMessage

Fired when a message is received from a contact

Type: object
Properties:
Name Type Description
sender Contact
content string

content of the message
uuid integer

message unique id
time date

date of when the message was received

conversationData

Fired when conversation data is received

Type: object
Properties:
Name Type Description
sender Contact
conversation Conversation
content object

conversationInvitation

Fired when a conversation invitation is received

Type: ReceivedConversationInvitation

conversationJoinRequest

Fired when a conversation join request is received
This event is fired only if the user is the moderator from the conversation

Type: ReceivedConversationJoinRequest

conversationMessage

Fired when a conversation message is received

Type: object
Properties:
Name Type Description
sender Contact
content string

content of the message
conversation Conversation

customEvent

Fired when a custom data event has been received

Type: object
Properties:
Name Type Description
event string

event identifier
content object
sender Contact
conversation Conversation

Associated conversation, field may not be present

dataChannelInvitation

Fired when a data channel invitation is received

Type: ReceivedDataChannelInvitation

disconnect

Fired on disconnection with CCS server

Type: Void

error

Fired when an error is detected on connection with CCS server

Type: Void

fileTransferInvitation

Fired when a file transfer invitation is received

Type: ReceivedFileTransferInvitation

incomingCall

Fired when user receives an incoming call

Type: ReceivedCallInvitation

incomingScreenSharingCall

Fired when user receives an incoming screenSharing call

Type: Call

incomingScreenSharingCallInvitation

Fired when user receives an incoming screenSharing call Invitation

Type: ReceivedCallInvitation

newMediaAvailableFromContact

Fired when a new media is available from a contact

Type: object
Properties:
Name Type Description
sender Contact
media CloudMediaInfo

pointerLocationChanged

Fired when the pointer location changed for a contact.

Type: object
Properties:
Name Type Description
sender Contact
source object
x number
y number
data object

pointerSharingInvitation

Fired when a pointer sharing invitation is received

Type: ReceivedPointerSharingInvitation

rawData

Fired when raw data is received from a contact (for older apiRTC app compatibility)

Type: object
Properties:
Name Type Description
sender Contact
content object

reconnecting

Fired when a new connection to server is tried

Type: Void

reconnection

Fired when connectivity to the network has been recovered

Type: Void

whiteboardInvitation

Fired when a whiteboard session invitation is received

Type: ReceivedWhiteboardInvitation

whiteboardRoomMemberUpdate

Fired when a member connect or disconnect from whiteboard room.

Type: object
Properties:
Name Type Description
roomId string

event identifier
status string

online / offline
contacts Array.<Contact>

contacts updated

whiteboardRoomMemberUpdate

Fired when a member connect or disconnect from whiteboard room

Type: object
Properties:
Name Type Description
roomId string

event identifier
status string

online / offline
contacts Array.<Contact>

contacts updated