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 AgoraRtmStreamChannel object instance.

Swift

do {    let streamChannel = try rtmClient.createStreamChannel("exampleChannel")    print("Stream channel created successfully: \(streamChannel)")    // You can now use the streamChannel instance} catch {    print("Failed to create stream channel: \(error)")}

Objective-C

NSError* create_error = nil;AgoraRtmStreamChannel* stream_channel = [rtm createStreamChannel:@"your_channel" error:&create_error];

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

Swift

do {    let stream_channel = try RtmClient?.createStreamChannel(channelName1)    if stream_channel != nil {        print("create stream channel success");    } } catch let error {    print("error\(error)")}do {    let stream_channel = try RtmClient?.createStreamChannel(channelName2)    if stream_channel != nil {        print("create stream channel success");    } } catch let error {    print("error\(error)")}

Objective-C

NSError* create_error = nil;// Create the first instanceAgoraRtmStreamChannel* stream_channel1 = [rtm createStreamChannel:@"your_channel1" error:&create_error];// Create the second instanceAgoraRtmStreamChannel* stream_channel2 = [rtm createStreamChannel:@"your_channel2" error:&create_error];

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.

Swift

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

let join_option = AgoraRtmJoinChannelOption();join_option.token = "your_token"stream_channel.join(join_option, completion: { (res, error) in    if error != nil {        print("\(error?.operation) failed! error reason is \(error?.reason)")    } else {        print("success")    }    })

Objective-C

Call the joinWithOption method on the AgoraRtmStreamChannel instance with appropriate options as follows:

AgoraRtmJoinChannelOption* join_opt =  [[AgoraRtmJoinChannelOption alloc] init];join_opt.token =  @"your_token";[stream_channel joinWithOption:join_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {    if (errorInfo == nil) {        NSLog(@"join channel success!!");    } else {        NSLog(@"join channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);    }}];

When joining a channel, set the token parameter in AgoraRtmJoinChannelOption to a valid temporary token string. For testing purposes, use the Token Builder .

Swift

let join_option = AgoraRtmJoinChannelOption();join_option.token = "your_token"join_option.features = [.presence, .storage]stream_channel.join(join_option, completion: { (res, error) in    if error != nil {        print("\(error?.operation) failed! error reason is \(error?.reason)")    } else {        print("success")    }    })

Objective-C

AgoraRtmJoinChannelOption* join_opt =  [[AgoraRtmJoinChannelOption alloc] init];join_opt.token =  @"your_token";join_opt.features = join_opt.features | AgoraRtmJoinChannelFeatureLock;[stream_channel joinWithOption:join_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {    if (errorInfo == nil) {        NSLog(@"join channel success!!");    } else {        NSLog(@"join channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.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 an AgoraRtmStreamChannel instance.
• Join a stream 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

  Swift

  let message = "Hello Agora!"  streamChannel.publishTopicMessage("your_topic", message: message, option: nil) { response, errorInfo in      if errorInfo == nil {          print("publish success!!")      } else {          print("publish failed, errorCode \(errorInfo!.errorCode), reason \(errorInfo!.reason)")      }  }

  Objective-C

  // Send a string message  NSString* message = @"Hello Agora!"; // Message content  [stream_channel publishTopicMessage:@"your_topic" message:message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {      if (errorInfo == nil) {          NSLog(@"publish success!!");      } else {          NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);      }  }];

• Binary message

  Swift

  let bytes: [UInt8] = [ /* your raw values */ ]  let rawMessage = Data(bytes: bytes, count: bytes.count)  streamChannel.publishTopicMessage("your_topic", data: rawMessage, option: nil) { response, errorInfo in      if errorInfo == nil {          print("publish success!!")      } else {          print("publish failed, errorCode \(errorInfo!.errorCode), reason \(errorInfo!.reason)")      }  }

  Objective-C

  // Send a binary message  unsigned char bytes[32] = { /* your raw values */ }; // Binary message content  NSData* raw_message = [[NSData alloc] initWithBytes:bytes length:32]; // Creating NSData object with binary message  [stream_channel publishTopicMessage:@"your_topic" data:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {      if (errorInfo == nil) {          NSLog(@"publish success!!");      } else {          NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);      }  }];

In Signaling, a user may register as a message publisher for up to 8 topics concurrently. However, there is no limit 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 AgoraRtmStreamChannel instance:

Swift

stream_channel.leave({ res, error in    if error != nil {        print("\(error?.operation) failed! error reason is \(error?.reason)")    } else {        print("success")    }})

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

Objective-C

[stream_channel leave:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {    if (errorInfo == nil) {        NSLog(@"leave channel success!!");    } else {        NSLog(@"leave channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);    }}];

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

To destroy the stream channel instance, call destroy:

Swift

stream_channel.destroy();stream_channel = nil;

Objective-C

[stream_channel destroy];stream_channel = nil;

info

Destroying a stream channel removes the AgoraRtmStreamChannel instance from your app. This action is local to your app and does not affect other users or the Signaling channel.

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 channels and Stream channels. The limit is 32 KB for Message channels and 1 KB for Stream 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 receive an error message.

Swift

// errorInfo{    errorInfo.errorCode = .channelMessageLengthExceedLimitation    errorInfo.reason = "Publish too long message."    errorInfo.operation = "publish"; // or "publishTopicMessage}

Objective-C

// errorInfo{    errorInfo.errorCode = AgoraRtmErrorChannelMessageLengthExceedLimitation;    errorInfo.reason = @"Publish too long message.";    errorInfo.Operation = @"publish"; // or "publishTopicMessage"}

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

Swift

• createStreamChannel
• join
• publishTopicMessage
• leave
• destroy

Objective-C

• createStreamChannel
• joinWithOption
• publishTopicMessage
• leave
• destroy