Stream channels

Stream channels are based on the room model. In Signaling, communication through stream channels requires use of specific APIs. This page shows you how to join, leave, and send messages in stream channels.

To use stream channels, you first create a stream channel object instance. The channel instance gives you access to all stream channel management methods. Use the stream channel instance to:

• Join and leave a channel
• Join and leave topics
• Subscribe to and unsubscribe from topics
• Send messages
• Destroy the channel instance

After joining a stream channel, you listen to event notifications in the channel. To send and receive messages in the channel, you use topics. Signaling allows thousands of stream channels to exist simultaneously in your app. However, due to client-side performance and bandwidth limitations, a single client may only join a limited number of channels concurrently. For details, see API usage restrictions.

Ensure that you have:

• Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.

• Activated the stream channel capability.

  Important

  Stream channel activation requirements

  Please note that the activation of Stream Channel functionality in Signaling directly depends on the activation of the 128-host feature in Real-Time Communication (RTC). To ensure proper activation:

  • Submit a formal request to support@agora.io.
  • Specifically request activation of the 128-host feature.
  • Wait for confirmation before implementing Stream Channel features.

  For further assistance or questions regarding this requirement, please contact Agora Support.

This section shows you how to use the Signaling SDK to implement stream channel communication in your app.

To use stream channel functionality, call createStreamChannel to create a RTMStreamChannel object instance.

const channelName = "chat_room";

const streamChannel = rtmClient.createStreamChannel(channelName);

This method creates only one RTMStreamChannel instance at a time. If you need to create multiple instances, call the method multiple times.

// Create the first instance

const streamChannel = rtmClient.createStreamChannel("chat_room_1");

// Create the second instance

const streamChannel = rtmClient.createStreamChannel("chat_room_2");

info

Signaling enables you to create unlimited stream channel instances in a single app. However, best practice is to create channels based on your actual requirements to maintain optimal client-side performance. For instance, if you hold multiple stream channel instances, destroy the ones that are no longer in use to prevent resource blocking, and recreate them when they are needed again.

Call the join method on the RTMStreamChannel instance with appropriate options as follows:

const options = {

token: "your_token",

withPresence: true,

withLock: true,

withMetadata: true

};

try {

const result = await streamChannel.join(options);

} catch (status) {

const { operation, reason, errorCode } = status;

console.log(`${operation} failed, ErrorCode: ${errorCode}, due to: ${reason}.`);

}

When joining a channel, set the token parameter in JoinChannelOptions with a temporary token from Agora Console.

const options = {

token: "your_token",

withPresence: true,

withLock: true,

withMetadata: true

};

try {

const result = await streamChannel.join(options);

} catch (status) {

const { operation, reason, errorCode } = status;

console.log(`${operation} failed, ErrorCode: ${errorCode}, due to: ${reason}.`);

}

In stream channels, message flow is managed using topics. Even if you configure a global message listener, you must still join a topic to send messages. Similarly, to receive messages you must subscribe to a topic. See Topics for more information.

To send a message to a stream channel:

• Create a RTMStreamChannel instance.
• Use the join method to join a channel.
• Call joinTopic to register as a message publisher for the specified topic. See Topics.

Call publishTopicMessage to publish a message to a topic. This method sends a message to a single topic at a time. To deliver messages to multiple topics, call the method separately for each topic.

Refer to the following sample code for sending messages:

• String message

  // Sending a string message
  

  const payload = "Hello Agora!"; // Message content
  

  const topicName = "chat_topic"; // Topic to which the message is sent
  

  const options = { customType: "PlainTxt" }; // Options for sending the message
  

  try {
  

  const result = await streamChannel.publishTopicMessage(topicName, payload, options); // Sending the message asynchronously
  

  } catch (status) {
  

  const { operation, reason, errorCode } = status;
  

  console.log(`${operation} failed, ErrorCode: ${errorCode}, due to: ${reason}.`); // Logging error information if message sending fails
  

  }
  

• Binary message

  // Sending a binary message
  

  const message = "Hello Agora!"; // Binary message content
  

  const payload = new TextEncoder().encode(message); // Encoding message to binary data
  

  const topicName = "chat_topic"; // Topic to which the message is sent
  

  const options = { customType: "ByteArray" }; // Options for sending the message
  

  try {
  

  const result = await streamChannel.publishTopicMessage(topicName, payload, options); // Sending the message asynchronously
  

  } catch (status) {
  

  const { operation, reason, errorCode } = status;
  

  console.log(`${operation} failed, the error code is ${errorCode}, because of: ${reason}.`); // Logging error information if message sending fails
  

  }
  

In Signaling, a user may register as a message publisher for up to 8 topics concurrently. However, there are no limitations on the number of users a single topic can accommodate. You can achieve a message transmission frequency to a topic of up to 120 QPS. This capability is useful in use-cases that demand high-frequency and high-concurrency data processing, such as Metaverse location status synchronization, collaborative office sketchpad applications, and parallel control operation-instructions transmission.

To leave a channel, call the leave method on the RTMStreamChannel instance:

try {

const result = await streamChannel.leave();

} catch (status) {

const { operation, reason, errorCode } = status;

console.log(`${operation} failed, ErrorCode ${errorCode}, due to: ${reason}.`);

}

To rejoin a stream channel, call the join method again. You can join and leave as long as the corresponding RTMStreamChannel instance remains active and has not been destroyed.

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Signaling SDK imposes size limits on message payload packets sent in message type channels and stream type channels: 32 KB for message type channels and 1 KB for stream type channels. The message payload packet size includes the message payload itself plus the size of the customType field. If the message payload package size exceeds the limit, you will receive an error message.

// Status

{

error = true;

errorCode = -11010;

Operation = "PublishTopicMessageOperation"; // Or "PublishOperation"

Reason = "Publish too long message.";

}

To avoid sending failure due to message payload packet size exceeding the limit, check the packet size before sending.

• createStreamChannel
• join
• publishTopicMessage
• leave