DingRTC RTM API-Real-Time Communication(RTC)-阿里云帮助中心

This topic provides details about the DingRTC Web RTM software development kit (SDK) API.

Data types

Type	Description	Minimum supported version
RTMSession	The structure of RTM session information.	1.0.0
RTMSessionUser	The user information in an RTM session.	1.0.0
RTMMessage	The structure of a message published by a remote user.	1.0.0

Properties

Property	Type	Description	Minimum supported version
sessions	RTMSession[]	The list of current sessions on the RTM instance.	1.0.0
connectionState	string	The connection state between the SDK instance and the service.	1.0.0

API list

API	Description	Minimum supported version
join()	Joins a channel. Use this API when you use RTM independently.	1.0.0
leave()	Leaves a channel. Use this API when you use RTM independently.	1.0.0
joinSession()	Joins an RTM session.	1.0.0
leaveSession()	Leaves an RTM session.	1.0.0
closeSession()	Closes an RTM session.	1.0.0
publish()	Publishes a broadcast or peer-to-peer message in a specified session.	1.0.0
off()	Cancels the listener callback for a specified event.	1.0.0
on()	Listens for a specified event and sets a callback function.	1.0.0
once()	Listens for a specified event once. The callback function is removed after it is triggered.	1.0.0
removeAllListeners()	Cancels the listener callbacks for a specified event or all events of the object.	1.0.0

Event list

DingRTC global events

Event	Callback type	Description	Minimum supported version
"session-add"	(session: RTMSession) => void;	A new RTM session is created in the channel.	1.0.1
"session-remove"	(session: RTMSession) => void;	An RTM session is closed in the channel.	1.0.1
"session-user-join"	(sessionId: string, userId: string) => void;	Notification that a user has joined an RTM session.	1.0.2
"session-user-left"	(sessionId: string, userId: string) => void;	Notification that a user has left an RTM session.	1.0.2
"message"	(messgae: RTMMessage) => void;	Notification of a message published by a remote user.
"connection-state-change"	(curState:ConnectionState, revState:ConnectionState, reason?:DisconnectedReason) => void	Callback for when the connection state between the SDK and the server changes.	1.0.1

Data types

RTMSession

The structure for RTM session information.

Property	Type	Description	Version
joined	boolean	Indicates whether the current user has joined the session.	1.0.0
users	RTMSessionUser[]	The list of users currently in the RTM session.	1.0.0
id	string	The RTM session ID.	1.0.0

RTMSessionUser

The structure for user information in an RTM session.

Property	Type	Description	Version
userId	string	The user ID in the RTM session.	1.0.0
userNmae	string	The username in the RTM session.	1.0.0

RTMMessage

The structure for a message published by a remote user.

Property	Type	Description	Version
message	Uint8Array	The message payload.	1.0.0
uid	string	The UID of the publisher.	1.0.0
sessionId	string	The ID of the session to which the message belongs.	1.0.0
broadcast	boolean	Indicates whether the message is a broadcast or a peer-to-peer message.	1.0.0

API details

join()

Joins a channel, which allows users in the same channel to communicate with each other. You can call this API when you use RTM independently. You do not need to call this API if you use RTM with DingRTC.

Type signature

join(joinInfo: JoinParam): Promise<void>;

Parameters:

Parameter	Type	Description
joinInfo	JoinParam	The parameters required to join a channel.

Back

Promise<void>

leave()

Leaves a channel. You can call this API when you use RTM independently. You do not need to call this API if you use RTM with DingRTC.

Type signature

leave(): void;

Back

void

joinSession()

Joins a session. If other members are in the session or join later, you will receive the session-user-join event notification.

Type signature

joinSession(sessionId: string): Promise<void>;

Parameters:

Parameter	Type	Description
sessionId	string	The RTM session ID. It supports uppercase letters, lowercase letters, digits, and underscores (_). The length cannot exceed 64 characters.

Back

Promise<void>

leaveSession()

Leaves an RTM session. After you leave, you will no longer receive broadcast messages from other members in the session, and they cannot send peer-to-peer messages to you.

Type signature

leaveSession(sessionId: string): Promise<void>;

Parameters:

Parameter	Type	Description
sessionId	string	The RTM session ID.

Back

Promise<void>

closeSession()

Closes a session. After the session is closed, all members in the session, including yourself, receive the session-remove event notification. The session is then no longer active.

Type signature

closeSession(sessionId: string): Promise<void>;

Parameters:

Parameter	Type	Description
sessionId	string	The RTM session ID.

Back

Promise<void>

publish()

Publishes a broadcast or peer-to-peer message in a specified session.

Type signature

publish(sessionId: string, message: Uint8Array, targetUid?: string): void;

Parameters:

Parameter	Type	Description
sessionId	string	The RTM session ID.
message	Uint8Array	The message to publish, in binary format.
targetUid	string	Optional. If specified, a peer-to-peer message is published. The publisher and the recipient must be in the same specified session. If not specified, a broadcast message is published in the session.

Back

void

on()

Listens for a specified event and sets a callback function.

Type signature

on(event: string, fn: Function): void;

Parameters

Parameter	Type	Description
event	string	The specified event to listen for.
fn	Function	The callback function to be triggered when the event occurs.

Back

void

off()

Cancels the listener callback for a specified event.

Type signature

off(event: string, fn: Function): void;

Parameters

Parameter	Type	Description
event	string	The specified event to listen for.
fn	Function	The callback function to be triggered when the event occurs.

Back

void

once()

Listens for a specified event once. The callback function is removed after it is triggered.

Type signature

once(event: string, fn: Function): void;

Parameters

Parameter	Type	Description
event	string	The specified event to listen for.
fn	Function	The callback function to be triggered when the event occurs.

Back

void

removeAllListeners()

Cancels the listener callbacks for a specified event or all events of the object.

Type signature

removeAllListeners(event?: string): void;

Parameters

Parameter	Type	Description
event	string	(Optional) If a specific event is set, its listener callbacks are cleared. If this parameter is not specified, the listener callbacks for all events of the object are cleared.

Back

void

Event details

"message"

Receiving a remotely published message

Type signature

RTMMessage'message': (message: <a baseurl="t2883904_v1_0_0.xdita" data-node="5585225" data-root="16740" data-tag="xref" href="#d0bb3b0c700zz" id="371905bb769dk">RTMMessage</a>) => void;

Example

rtm.on('message', (message) => {
 console.log(message);
});

"session-add"

A new session has been created in the channel.

Type signature

RTMSession'session-add': (session: <a baseurl="t2883904_v1_0_0.xdita" data-node="5585225" data-root="16740" data-tag="xref" href="#abd20cd94bq0g" id="0561a205cf7d2">RTMSession</a>) => void;

Example

rtm.on('session-add', (session) => {
 console.log(session);
});

"session-remove"

A session on the channel is closed.

Type signature

'session-remove': (session: RTMSession) => void;

Example

rtm.on('session-remove', (session) => {
 console.log(session);
});

"session-user-join"

Indicates that a user has joined an RTM session.

Type signature

'session-user-join': (sessionId: string, uid: string) => void;

Example

rtm.on('session-user-join', (sessionId, uid) => {
 console.log(sessionId, uid);
});

"session-user-left"

Occurs when a user leaves an RTM session.

Type signature

'session-user-left': (sessionId: string, uid: string) => void;

Example

rtm.on('session-user-left', (sessionId, uid) => {
 console.log(sessionId, uid);
});

"connection-state-change"

This callback is triggered when the connection state between the SDK and the server changes. It is only required for standalone RTM implementations, not for those that use RTM with DingRTC.

Type signature

'connection-state-change': (curState: ConnectionState, prevState: ConnectionState, reason?: DisconnectedReason) => void;

Example

rtm.on('connection-state-change', (curState, prevState, reason) => {
 console.log(curState, prevState, reason);
});