Documentation

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

new Conversation()

Fires:

Extends

Methods

<static> getAvailableEvents()

Returns available events for this class

Returns:
Type
Array.<string>

allowEntry(contact, options)

Allows entry to contact in waiting room as moderator.

Parameters:
Name Type Description
contact Contact

The contact to grant access to.
options object
Properties
Name Type Description
invitationId string
answer string
ackEnabled boolean
Returns:
Type
Promise.<void>

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 transferPending or transferBegun events).
Returns:
Type
Promise

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.
password string

Conference password (if necessary).
session Session
Returns:
Type
Promise.<ConferenceAccessStatus>

denyEntry(contact, options)

Denies entry to contact in waiting room as moderator.

Parameters:
Name Type Description
contact Contact

The contact to deny access to.
options object
Properties
Name Type Description
invitationId string
answer string
reason string
Returns:
Type
Promise.<void>

destroy()

Cleans up all local resources attached to this one.

eject(contact, data)

Ejects a given contact from the converation.

Parameters:
Name Type Description
contact Contact

The contact to eject.
data object

User data (optional).
Returns:
Type
Promise.<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
Properties
Name Type Description
token string
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
Properties
Name Type Description
token string
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
Deprecated in favor of streamListChanged event.

Deprecated:
  • Yes
Returns:

contact list

Type
Array.<StreamInfo>

getCloudConversationId()

Returns ApiRTC 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>

getContactsArray()

Returns contact list for conversation

Returns:

contact list

Type
Array.<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 publish).
Returns:

A conversation call handle on success, null otherwise.

Type
ConversationCall | null

getData()

Returns conversation persistent data

Returns:

data

Type
Object

getE2EEStatus()

Returns if the encryption is enabled on this conversation or not

Returns:
Type
boolean

getFriendlyName()

Returns this conference's name as it is displayed on your ApiRTC cloud platform

Deprecated:
  • Please note that FriendLyName is now deprecated and will be removed in a future release.
Returns:
Type
string | null

getInstanceId()

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

Returns:
Type
string | null

getMedia()

Returns media files. This function manage authorization token to access media file

Properties:
Name Type Description
mediaURL mediaURL

Media URL.
Returns:

Media as a blob

Type
Promise.<Blob>

getModerator()

Returns conversation moderator.

Returns:

moderator or null if no moderator or moderator unknown

Type
Contact | null

getName()

Returns this conversation's room name

Returns:
Type
string

getNetworkCap(options)

Gets the network capacity of this one.

Parameters:
Name Type Description
options object
Properties
Name Type Description
capacity object

Returns the overall capacity rather than the remaining available bandwidth.
Returns:

available upload bandwidth and available download bandwidth

Type
Array.<number> | null

getRecordingInfo()

Returns the recoding information, if any.

Returns:
Type
RecordingInfo | null

getRole()

Returns UserAgent's role for this conversation, will be set to null if conversation is not joined

Returns:
Type
string | null

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

getSubscribedStream()

Returns subscribed stream with its identifier

Properties:
Name Type Description
streamId string
Returns:

stream

Type
Stream

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

Optional data.
Returns:
Type
Promise.<JoinResult>

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

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>

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

replacePublishedStream(oldStream, newStream, callbacks)

Replaces the currently published stream by a given one.
If the first parameter is null then the second parameter must provides a property named
getStream. The getStream property shall be a function returning a Promise of a Stream.

Parameters:
Name Type Description
oldStream Stream

Stream that was published
newStream Stream

New stream to be published
callbacks object

Callbacks.

Properties
Name Type Description
getStream function

A function returning a promise of a stream.
Returns:

The newly assigned stream.

Type
Promise.<Stream>

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)

Sends data message to contacts in conversation.

Parameters:
Name Type Description
data Object

Data to send.
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.
token Object

Optional token to overload the Session.getToken() token.
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)

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
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 resource 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 Default Description
canvasId string

Identifier of the canvas to use for whiteboard
cursorColor string invisible

User cursor color, sets the user cursor color that will be seen by other participants. Set to '#000000' to have a black cursor.
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 boolean

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.
ttl number

The time to live (in seconds) of the recording after being successfully created. By default, the data is persistent.
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 number | string

Stream ID. Represents the stream to subscribe to.
options SubscribeOptions
Returns:
Type
Promise

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
streamId number | string

Stream ID.
callId string

Call ID.
amplitude number
isSpeaking boolean
descriptor object

Deprecated.

availableStreamsUpdated

Fired when available streams in conversation have been updated

Type: Array.<StreamInfo>

callStatsUpdate

Type: object
Properties:
Name Type Description
streamId number | string

Stream ID.
callId string

Call ID.
mesh boolean

Whether the stats belongs to one of the sub-calls of a published stream in mesh mode.
contact Contact

If mesh is true, the contact to whom the stream is sent to.
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

entryAllowed

Fired when moderator allows user to enter

Type: void

entryDenied

Fired when moderator denies user to enter

Type: void

error

Fired when an error happened on conversation stream

Type: object
Properties:
Name Type Description
streamId number | string

Stream ID.
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
  • 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.
streamId number | string

Stream ID.

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.
streamId number

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'.

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'.

simulcastFeedChanged

Fired when the simulcast selection feed changed.

Type: object
Properties:
Name Type Description
streamId number

Stream ID.
callId string

Call ID.
simulcast object
Properties
Name Type Description
streamQuality string

Substream selection. Either 'high', 'medium' or 'low'.
streamFrameRate string

Temporal layer selection. Either 'high', 'medium' or 'low'.

Fired when a slow link is detected.
An optional advice can be set. When advice is 'subscribeToAudioComposite', the
application should start the audio composite (#startComposite) and then subscribe
to the audio composite stream instead of subscribing to every stream individually.

Type: object
Properties:
Name Type Description
callId string

Call ID.
streamId number | string

Stream ID.
advice string

Optional advice.

streamAdded

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

Type: Stream

streamListChanged

Fired when a change occurs in the available stream list. An entry in the
available stream list represents a stream that has been successfully
published by one of the participants and that one can subscribe to.

Type: StreamInfo
Example

use streamListChanged events

conversation.on('streamListChanged', function (streamInfo) {
    if (streamInfo.listEventType === 'added') {
        // A new stream has been published.
        // Add it to me own list copy?
        if (streamInfo.isRemote) {
            // The stream has been published by an other participant.
            // Subscribe to it?
        } else {
            // The stream has been published by me.
            // Subscribe to it?
        }
    } else if (streamInfo.listEventType === 'removed') {
        // A stream has been unpublished.
        // Remove it from with own list copy.
    } else if (streamInfo.listEventType === 'updated') {
        // Properties of the published stream has changed.
    }
});

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.

transferPending

Fired when a transfer is pending (push data).

Type: object
Properties:
Name Type Description
id string

transfer id.
name string

filename.
rank number

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