Class: Conversation

Conversation

Conversation

Users are able to interact with each other by entering a conversation in a N-N fashion.
The client is able to listen to conversation events that will be fired once the conversation is joined

Extends

Methods


<static> getAvailableEvents()

Returns available events for this class

Returns:
Type
Array.<string>

bind(options)

Binds the conversation represented by this one to cloud.

Parameters:
Name Type Description
options object
Properties
Name Type Description
session Session

Session.

Returns:
Type
Promise.<string>

cancelJoin()

Cancels an ongoing join request.

Returns:

True on success, false otherwise.

Type
boolean

cancelPushData(id)

Cancels an ongoing push data operation.

Parameters:
Name Type Description
id String

Push data operation identifier (from transferBegun event).


checkAccess(options)

Returns the access status of the conference represented by this one.

Parameters:
Name Type Description
options Object

Optional data.

Properties
Name Type Description
force Boolean

Whether not to use cache.

Returns:
Type
Promise.<ConferenceAccessStatus>

checkLowerpriority(priority, isRemote)

Check if priority is the highest among published streams

Parameters:
Name Type Description
priority number

priority

isRemote boolean
Returns:

True if there is not stream with higher priority, false otherwise.

Type
boolean

destroy()

Cleans up all local resources attached to this one.


destroyReservedStream(streamId)

Delete reserved stream from the list

Parameters:
Name Type Description
streamId string
Returns:
Type
void

enablePointerSharing(enabled)

Enables or disables pointer sharing for this one.

Parameters:
Name Type Description
enabled boolean

true to enable, false to disable.

Returns:
Type
Promise

fetchMediaList(session, options)

Fetches media specific to this conversation

Parameters:
Name Type Description
session Session

May be null.

options object
Returns:

mediaList

Type
Promise.<object>

fetchMessageHistory(session, options)

Loads message history for this conversation

Parameters:
Name Type Description
session Session

May be null.

options Object
Returns:
Type
Promise.<Array.<ConversationMessage>>

getAvailableMediaList()

Returns information for media streams available in the conversation

Deprecated:
  • Yes
Returns:

contact list

Type
Array.<StreamInfo>

getAvailableStreamList()

Returns information for media streams available in the conversation

Returns:

contact list

Type
Array.<StreamInfo>

getBandwidthRequirement(mediaType)

Gets the network bandwidth required for a media.

Parameters:
Name Type Description
mediaType string

Type of the media. Either 'videoSD', 'videoLD', 'videoHD', 'videoFullHD', 'AUDIOONLY' or 'VIDEOONLY'.

Returns:

Required bandwidth value for publishing/subscribing to the stream.

Type
number

getCloudConversationId()

Returns Apizee cloud conversation id for this conversation, will be set to null if conversation is not joined

Returns:
Type
string

getContacts()

Returns contact list for conversation

Returns:

contact list

Type
Object.<string, Contact>

getContactsNumber()

Returns contacts list for conversation

Returns:

contacts number

Type
number

getConversationCall(stream)

Returns the conversation call handle for a given stream.

Parameters:
Name Type Description
stream Stream

A stream, result of preceding publish or subscribe call.

Returns:

A conversation call handle on success, null otherwise.

Type
ConversationCall

getData()

Returns conversation persistent data

Returns:

data

Type
Object

getName()

Returns this conversation's room name

Returns:
Type
string

getNetworkCap()

Gets the network capacity of this one.

Returns:

available upload bandwidth and available download bandwidth

Type
Array

getRecordingInfo()

Returns the recoding information, if any.

Returns:
Type
RecordingInfo | null

getReservedStreamInfo(streamId)

Gets information on the reserved stream

Parameters:
Name Type Description
streamId string

Stream ID

Returns:

Stream info

Type
array

getStatus()

Returns conversation status

Returns:
Type
Symbol

getStreamInfo()

Returns information for the media stream

Properties:
Name Type Description
streamId string
Returns:

stream information

Type
StreamInfo

getWaitingRoomContacts()

Returns contacts in the waiting room, returns empty if conversation is not joined or user is not a moderator

Returns:

contact list

Type
Object.<string, Contact>

isBound()

Tests whether the conversation represented by this one is bound to cloud.

Returns:

True if this one is bound to cloud, false otherwise.

Type
boolean

isGroupChatJoined()

Returns:

True if the group chat has been joined, false otherwise.

Type
Boolean

isJoined()

Checks if the conversation is joined

Returns:
Type
Boolean

isPublishedStream(stream)

Does the stream is currently published in conversation

Parameters:
Name Type Description
stream Stream

Stream for which you want to know the publish status

Returns:
Type
boolean

isRecorded()

Tests whether the call represented by this one is recorded.

Returns:
Type
boolean

join(options)

Connects to a conversation if not already joined
Once in the conversation, the user will be able to see other contacts inside it, send and receive messages, publish streams and subscribe to conversation's streams

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

joinGroupChat()

Joins group chat.

Returns:
Type
Promise

leave()

Leaves conversation
The user will automatically stop publishing its streams to the conversation and stop subscribing to streams from the conversation.
The user will no longer receive events from the conversation
The user will no longer see who's within the conversation

Returns:
Type
Promise

leaveGroupChat()

Leaves group chat.

Returns:
Type
Promise

muteLowestPriorityStream(isRemote)

Mute the lowest priority stream

Parameters:
Name Type Description
isRemote boolean
Returns:

True if there is not stream with higher priority, false otherwise.

Type
boolean

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

publish(stream, options)

Publish stream to conversation
The stream will be able to be subscribed by other contacts within the conversation

Parameters:
Name Type Description
stream Stream

Stream to publish

options PublishOptions

Publish options.

Returns:

Published stream in promise.

Type
Promise.<Stream>

pushData(data, options)

Pushes data to this one.

Parameters:
Name Type Description
data PushDataFileDescriptor | PushDataBufferDescriptor

data - Descriptor of the data to transfer.

options PushDataOptions
Returns:
Type
Promise.<CloudMediaInfo>

pushMedia(media, options)

Pushes media specific to this conversation

Parameters:
Name Type Description
media string

dataURI media

options object
Properties
Name Type Description
filename string

Mandatory when overwriting.

overwrite boolean

Whether the overwriting is enabled. By default, overwriting is not enabled.

ttl number

The time to live of the data after being successfully pushed. By default, the data is persistent.

Returns:

cloud media info in promise

Type
Promise.<CloudMediaInfo>

releaseResources(streamId)

Release network bandwidth

Parameters:
Name Type Description
streamId string
Returns:

True on success, false otherwise.

Type
boolean

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

reserveResources(mediaType, streamId, isRemote, priority)

Reserves network bandwidth

Parameters:
Name Type Description
mediaType string

Type of the media. Either 'videoSD', 'videoLD', 'videoHD', 'videoFullHD', 'AUDIOONLY' or 'VIDEOONLY'.

streamId string

streamId.

isRemote string

True if the stream is remote, false if it is local.

priority number
Returns:

True on success, false otherwise.

Type
boolean

sendCustomEvent(event, content)

Sends a custom data event to everyone in the conversation

Parameters:
Name Type Description
event string

event key

content Object
Returns:
Type
Promise

sendData(data, options)

Sends data message to contacts in conversation.

Parameters:
Name Type Description
data Object

Data to send.

options Object
Returns:
Type
Promise

sendInvitation(contact, options)

Invites a contact to this conversation

Parameters:
Name Type Description
contact Contact

to invite

options Object
Properties
Name Type Description
expirationTime number

Time for an invite to expire after being sent

Returns:
Type
SentInvitation

sendMessage(message, options)

Sends string message to contacts in conversation

Parameters:
Name Type Description
message String

message to send

options Object

options

Properties
Name Type Description
metadata Object

Optional user metadata.

Returns:
  • Promise with message uuid.
Type
Promise.<number>

sendPointerLocation(source, x, y, data)

Sends a given pointer location to every other participant.

Parameters:
Name Type Description
source object

The display source identifier.

x number

The X coordinate of the mouse pointer in source coordinates.

y number

The Y coordinate of the mouse pointer in source coordinates.

data object

Optional data to send with.


sendRawData(data, options)

Sends raw data message to contacts in conversation, for backwards compatibility purposes
Equivalent to Session.sendRawData() but to send to everyone in the conversation

Parameters:
Name Type Description
data Object

data to send

options Object
Returns:
Type
Promise

setData(data)

Sets conversation persistent data (cloud user only)

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

setNetworkCap(upload, download)

Sets the network capacity of this one. Shall be done to enable resources reservation.

Parameters:
Name Type Description
upload number

Available upload bandwidth

download number

Available download bandwidth

Returns:

True on success, false otherwise.

Type
boolean

startComposite()

Starts the composite stream on the video bridge.

Returns:
Type
Promise

startNewWhiteboardSession()

Starts a new whiteboard session for this conversation and notifies contacts in conversation

Properties:
Name Type Description
canvasId string

Identifier of the canvas to use for whiteboard

cursorColor string

User cursor color, sets the user cursor color that will be seen by other participants. Set to '#000000' to have a black cursor. Default value is invisible

Returns:
Type
Promise

startRecording(options)

Starts recording the conversation represented by this one.

The audioOnly and videoOnly parameters allow you to directly select
audio/video input for all streams in the room. For custom stream selection,
you shall let those parameters aside and use the following parameters instead: mode,
labelEnabled, labels.

The mode parameter allows you to configure how streams will rendered in the media
file. In the complete mode, selected audio-only streams will occupied the same amount
of place than video streams. In the efficient mode, selected audio-only streams will
not occupied any video space. In the audioOnly mode, only the audio part of selected
streams will be rendered and the media file will not contain any video component.

The labelEnabled parameter activates the use of label(s) for stream selection.

The labels parameter allows you to select stream(s). Only streams with matching label
will be rendered in the final media file.

Parameters:
Name Type Description
options Object

Recording preferences.

Properties
Name Type Description
audioOnly boolean

Whether to record only audio.

videoOnly boolean

Whether to record only video.

customIdInFilename string

This string will be added to the name of the final file.

mode string

Recording mode. Either 'complete' (default), 'efficient', 'audioOnly'.

labelEnabled string

Whether streams are selected based on label(s).

labels Object

Array of labels (string) to select stream in the room.

data Object

Additional user data.

Returns:
Type
Promise.<RecordingInfo>

stopComposite()

Stops the composite stream on the video bridge.

Returns:
Type
Promise

stopNewWhiteboardSession()

Stops whiteboard session for this conversation and notifies contacts in conversation

Returns:
Type
Promise

stopRecording()

Stops recording.

Returns:
Type
Promise.<RecordingInfo>

subscribeToStream(streamId, options)

Subscribes to a stream.

The subscription will automatically stop if the contact publishing the stream unpublishes it.

The Conversation#streamAdded event will be fired when the stream becomes available.
The Conversation#streamRemoved event will be fired when the stream is no longer available.
The Conversation#hangup event will be fired the subscription is terminated.

Note that multiple Conversation#streamAdded and Conversation#streamRemoved events might be
fired in case failure correction.

Parameters:
Name Type Description
streamId String

Identifies the stream to subscribe to.

options SubscribeOptions
Returns:
Type
Promise

unMuteHighestPriorityStream(isRemote)

Unmute the highest priority stream

Parameters:
Name Type Description
isRemote boolean
Returns:

True if there is not stream with higher priority, false otherwise.

Type
boolean

unpublish(stream, options)

Unpublishes currently published stream to conversation
If other users within the conversation subscribed to this stream, it will be stopped on their side

Parameters:
Name Type Description
stream Stream

Stream to unpublish

options Object
Returns:
Type
Void

unsubscribeToStream(streamId)

Unsubscribes from a conversation's stream
The stream will be stopped on the user's side

Parameters:
Name Type Description
streamId String
Returns:
Type
Void

updateData()

Forces conversation persistent data update

Returns:

data in promise

Type
Promise.<Object>

updateSubscribedStream(streamId, options)

Updates the call configuration for a given subscribed stream.

Parameters:
Name Type Description
streamId String

Stream identifier.

options SubscribeOptions

New call configuration.

Returns:

When it is done.

Type
Promise

Events


audioAmplitude

Fired when the audio amplitude change happened on conversation stream (indicating user speaking or not)

Type: object
Properties:
Name Type Description
callId string
descriptor descriptor

availableStreamsUpdated

Fired when available streams in conversation have been updated

Type: Array.<StreamInfo>

callStatsUpdate

Type: object
Properties:
Name Type Description
callId string
stats CallStats

closed

Fired when conversation has been closed

Type: void

contactJoined

Fired when a contact joined the conversation

Type: Contact

contactJoinedWaitingRoom

Contact joined the waiting room event (moderator only)

Type: Contact

contactLeft

Fired when a contact left the conversation

Type: Contact

contactLeftWaitingRoom

Contact left the waiting room event (moderator only)

Type: Contact

customEvent

Fired when a custom data event has been received from a contact within the conversation.

Type: object
Properties:
Name Type Description
event string

event identifier

sender Contact
content object

data

Fired when data is received from a contact within the conversation

Type: object
Properties:
Name Type Description
content object

data

sender Contact

disconnectionWarning

Fired when a disconnection happened on conversation stream

Type: object
Properties:
Name Type Description
streamInfo Array.<StreamInfo>

Stream information


error

Fired when an error happened on conversation stream

Type: object
Properties:
Name Type Description
streamInfo Array.<StreamInfo>

Stream information

errorCode string

Code description of the error. Check possible values below.

errorInfo string

Code information about the error. Check possible values below.

Possible errors values are the following: (errorInfo, errorCode)

Connection errors:
  • ice disconnection detected: ICE_CONNECTION_STATE_DISCONNECTED
  • ice connection failed detected: ICE_CONNECTION_STATE_FAILED
  • distant ice disconnection detected: DISTANT_ICE_CONNECTION_STATE_DISCONNECTED
  • distant ice connection failed detected: DISTANT_ICE_CONNECTION_STATE_FAILED
Errors on signaling processing:
  • 200OK received but callId is not matching, no process : NOT_MATCHING_CALLID_ON_200OK
  • Cannot find call to process Update : CALL_NOT_FOUND_ON_UPDATE
  • Cannot find call to process 200 Update : CALL_NOT_FOUND_ON_200UPDATE
  • Call aborted after calls retries (maxCallsRetriesDuration reached) : CALL_ABORTED
Errors on Media establishment processing:
  • Set local Description Failure : SET_LOCAL_DESCRIPTION_FAILURE
  • Set remote Description Failure : SET_REMOTE_DESCRIPTION_FAILURE
Errors on calling API:
  • parameter error when calling function: setUnidirectionalCall(): PARAMETER_ERROR_SETUNIDIRCALL
  • parameter error when calling function: setNtoNConf(): PARAMETER_ERROR_SETNTONCONF
  • parameter error when calling function: setRTPMedia(): PARAMETER_ERROR_SETRTPMEDIA
  • parameter error when calling function: setMediaRoutingMode(): PARAMETER_ERROR_SETMEDIAROUTINGMODE
  • parameter error when calling function: setUserAcceptOnIncomingCall(): PARAMETER_ERROR_SETUSERACCEPTONINCOCALL
  • parameter error when calling function: hideLocalVideoOnCall(): PARAMETER_ERROR_SETHIDELOCALVIDEOONCALL
  • Trying to add a listener on an unknown event: UNKNOWN_EVENT_ON_ADDLISTENER
  • parameter error when calling function: setAllowMultipleCalls(): PARAMETER_ERROR_SETALLOWMULTIPLECALLS
Errors about recording :
  • Room not found when starting recording: START_RECORD_ROOM_NOT_FOUND
  • Caller not found when starting recording: START_RECORD_CALLER_NOT_FOUND
  • Media not found when starting recording: START_RECORD_MEDIA_FOUND
  • Recording is already ongoing: START_RECORD_ALREADY_ON
  • Room not found when stopping recording: STOP_RECORD_ROOM_NOT_FOUND
  • Caller not found when stopping recording: STOP_RECORD_CALLER_NOT_FOUND
  • Media not found when stopping recording: STOP_RECORD_MEDIA_FOUND
  • Recorder not found when stopping recording: STOP_RECORD_ENDPOINT_NOT_FOUND
  • Recording is not started stopping recording: STOP_RECORD_NOT_STARTED
  • Recorder is not ready yet, record is not started: STOP_RECORD_RECORDER_NOT_READY
Errors about media play:
  • Autoplay was prevented: IOS_AUTOPLAY_PREVENTED
Errors about media streams:
  • Error during media update on call: MEDIA_UPDATE_ERROR
Errors about user media:
  • Error during media media access: USER_MEDIA_ERROR
Errors about remote stream:
  • Error during subscription: STREAM_NOT_AVAILABLE
descriptor ConversationIceErrorDescriptor | object

Detailed descriptor of the error


hangup

Fired when a publish or subscribe is terminated.

Type: object
Properties:
Name Type Description
from string

'local' or 'remote'.

reason string

Hangup reason.


joined

Fired when conversation has been joined by the user.

Type: void

left

Fired when conversation has been left by the user.

Type: void

localStreamUpdated

Fired when local stream properties changed.

Type: object
Properties:
Name Type Description
callId string

Call ID.

streamId string

Stream ID.

audio boolean

Whether an audio line has been negotiated and active.

audioMuted boolean

Whether the audio line is muted.

video boolean

Whether a video line has been negotiated and active.

videoMuted boolean

Whether the video line is muted.

cause string

Either 'adaptation' or 'userAction'.


message

Fired when a message is received from contact in the conversation

Type: object
Properties:
Name Type Description
content string

content of the message

sender Contact
time Date

receive time


messageNotDelivered

Type: Object
Properties:
Name Type Description
error ApiRTCError

Hint.

contact Contact

Message recipient.

event String

Event (optional).

command String

Command (optional).


moderatorConnected

Fired when moderator joined the conversation

Type: object
Properties:
Name Type Description
moderator Contact

newMediaAvailable

Fired when a new media is available in the conversation.

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

newWhiteboardSession

Fired when a contact in the conversation starts a new whiteboard session

Type: object
Properties:
Name Type Description
sender Contact

participantEjected

Fired when a participant has been ejected from the conference.

Type: object
Properties:
Name Type Description
self boolean
contact Contact

persistentDataUpdated

Fired when conversation persistent data has been updated.

Type: object

pointerLocationChanged

Fired when a pointer location changed.

Type: object
Properties:
Name Type Description
sender Contact

sender.

source object

source identifier.

x number

The X coordinate of the mouse pointer in source coordinates.

y number

The Y coordinate of the mouse pointer in source coordinates.

data object

Optional data.


pointerSharingEnabled

Fired when pointer sharing is enabled or disabled.

Type: object
Properties:
Name Type Description
enabled boolean

True when enabled, false when disabled.


recordingAvailable

Fired when a recording is available for play or download.

Type: RecordingInfo

recordingStarted

Fired when a recording started.

Type: RecordingInfo

recordingStopped

Fired when a recording stopped.

Type: RecordingInfo

remoteStreamUpdated

Fired when remote stream properties changed.

Type: object
Properties:
Name Type Description
callId string

Call ID.

audio boolean

Whether an audio line has been negotiated and active.

audioMuted boolean

Whether the audio line is muted.

video boolean

whether a video line has been negotiated and active.

videoMuted boolean

Whether the video line is muted.

cause string

Either 'adaptation' or 'userAction'.


roomModeChanged

Fired when the mode of conference room is changing or changed.

Type: object
Properties:
Name Type Description
oldMode string

Represents the previous mode, being replaced (or replaced) by the new mode. Either 'mesh' or 'sfu'.

newMode string

Represents the new mode, replacing the previous mode. Either 'mesh' or 'sfu'.

state string

Represents the state of the room mode change. Either 'ongoing' or 'complete'.


Fired when a slow link is detected.

Type: object
Properties:
Name Type Description
callId string

callId


streamAdded

Fired when a stream is received from this conversation after a subscription

Type: Stream

streamListChanged

Fired when available stream list changed

Type: StreamInfo

streamRemoved

Fired when stream is removed from this conversation after an unsubscription

Type: Stream

transferBegun

Fired when a transfer begun (push data).

Type: object
Properties:
Name Type Description
id string

transfer id.

name string

filename.


transferEnded

Fired when a transfer ended (push data).

Type: object
Properties:
Name Type Description
id string

transfer id.

name string

filename.


transferProgress

Fired with progress status during a transfer (push data).

Type: object
Properties:
Name Type Description
id string

transfer id.

name string

filename.

size number

total transfered byte count.

remBytes number

remaining byte count.

percentage number

progress ratio.


waitingForModeratorAcceptance

Fired when entering the waiting room of a conversation, requiring the moderator to accept before joining the room

Type: object
Properties:
Name Type Description
moderator Contact