Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Android
iOS
macOS
Web
Linux C++
Unity

Message channels

Signaling provides message channels for implementing publish-subscribe, or pub/sub messaging in your app. In a message channel, you subscribe to a channel to receive messages. However, you do not need to join the channel to publish messages. This page shows you how to use Signaling SDK pub/sub messaging to implement various communication model into your app.

Understand the tech

Pub/sub is the simplest form of messaging. Signaling creates a channel when a user subscribes to it. Your app listens for events which contain messages users publish to a channel.

Signaling allows thousands of message channels to exist in your app at the same time. However, due to client-side performance and bandwidth limitations, a single client may only subscribe to a limited number of channels concurrently. For details, see API usage restrictions.

Communication models in message channels

Signaling SDK enables you to implement a variety of communication models using message channels. A communication model refers to the data flow relationship between the message sender and receiver within a channel. Using the pub/sub message distribution mechanism, you can seamlessly implement the following communication models:

1-to-1 channel: This model facilitates communication between two users. It is ideal for creating private chat channels, one-on-one customer service support, and personal interactions.

Group channel: A group channel facilitates many-to-many communication, making user groups within the channel visible to each other. This model is suitable for workgroups, family discussions, and community interactions. Access control options in Signaling SDK enable you to implement open or invitation-based participation.

Broadcast channel: A broadcast channel enables one-to-many communication, where a single sender broadcasts messages to multiple recipients. This model is useful for group announcements, surveys, and disseminating information to a large audience.

Unicast channel: This model allows many users to send messages to a single recipient. This model is beneficial for scenarios such as questionnaire feedback collection, IoT sensor data aggregation, and centralized data collection.

Prerequisites

Ensure that you have integrated the Signaling SDK in your project and implemented the framework functionality from the SDK quickstart page.

Implement message channels

This section shows you how to subscribe, unsubscribe, and send messages to a message channel.

Subscribe to a channel

Use the subscribe method to subscribe to a message channel. After you subscribe, you receive onMessageEvent and other event notifications within the channel.


_17
String channelName = "test_channel";
_17
SubscribeOptions options = new SubscribeOptions();
_17
options.setWithMessage(true);
_17
options.setWithPresence(true);
_17
options.setWithMetadata(true);
_17
options.setWithLock(true);
_17
mRtmClient.subscribe(channelName, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void responseInfo) {
_17
log(CALLBACK, "subscribe channel " + channelName + " success");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
log(ERROR, errorInfo.toString());
_17
}
_17
});

To subscribe to multiple channels, call subscribe multiple times:


_31
String channelName1 = "chats.room1";
_31
String channelName2 = "chats.room2";
_31
SubscribeOptions options = new SubscribeOptions();
_31
options.setWithMessage(true);
_31
options.setWithPresence(true);
_31
options.setWithMetadata(true);
_31
options.setWithLock(true);
_31
_31
mRtmClient.subscribe(channelName1, options, new ResultCallback<Void>() {
_31
@Override
_31
public void onSuccess(Void responseInfo) {
_31
log(CALLBACK, "subscribe channel " + channelName1 + " success");
_31
}
_31
_31
@Override
_31
public void onFailure(ErrorInfo errorInfo) {
_31
log(ERROR, errorInfo.toString());
_31
}
_31
});
_31
_31
mRtmClient.subscribe(channelName2, options, new ResultCallback<Void>() {
_31
@Override
_31
public void onSuccess(Void responseInfo) {
_31
log(CALLBACK, "subscribe channel " + channelName2 + " success");
_31
}
_31
_31
@Override
_31
public void onFailure(ErrorInfo errorInfo) {
_31
log(ERROR, errorInfo.toString());
_31
}
_31
});

info

Signaling allows a single client to subscribe to up to 50 message channels simultaneously. However, to optimize client performance and bandwidth usage, best practice is to limit subscriptions to 30 channels. If you have very large or highly active channels, consider further reducing the number of simultaneous subscriptions.

Send a message

To send messages in a message channel, simply call the publish method without subscribing to the channel. This method sends messages to one channel at a time. To send messages to multiple channels, call this method multiple times. Signaling SDK does not limit the number of channels to which you can send messages, or the number of users who can send messages to a channel. However, there are certain restrictions on the frequency at which you can send messages to a channel simultaneously. See API usage restrictions for details.

Info

The publish method can only be used with a message channel and a user channel; it does not apply to a stream channel.

Refer to the following sample code for sending messages:

  • String message


    _17
    // Send a string message
    _17
    String message = "Hello World"; // Declaring a string variable for the message content
    _17
    String channelName = "my_channel"; // Specifying the name of the channel to which the message will be sent
    _17
    var options = new PublishOptions(); // Creating options for publishing the message
    _17
    options.customType = "PlainTxt"; // Setting the custom message type to "PlainTxt"
    _17
    _17
    mRtmClient.publish(channelName, message, options, new ResultCallback<Void>() { // Publishing the message to the channel
    _17
    @Override
    _17
    public void onSuccess(Void responseInfo) {
    _17
    log(CALLBACK, "send message success"); // Logging a success message upon successful message transmission
    _17
    }
    _17
    _17
    @Override
    _17
    public void onFailure(ErrorInfo errorInfo) {
    _17
    log(ERROR, errorInfo.toString()); // Logging an error message in case of transmission failure
    _17
    }
    _17
    });

  • Binary message


    _16
    // Send a binary message
    _16
    byte[] message = new byte[] { 00, 01, 35, 196 }; // Defining a byte array for the binary message
    _16
    String channelName = "my_channel"; // Specifying the name of the channel to which the message will be sent
    _16
    var options = new PublishOptions(); // Creating options for publishing the message
    _16
    options.customType = "ByteArray"; // Setting the custom message type to "ByteArray"
    _16
    mRtmClient.publish(channelName, message, options, new ResultCallback<Void>() { // Publishing the message to the channel
    _16
    @Override
    _16
    public void onSuccess(Void responseInfo) {
    _16
    log(CALLBACK, "send message success"); // Logging a success message upon successful message transmission
    _16
    }
    _16
    _16
    @Override
    _16
    public void onFailure(ErrorInfo errorInfo) {
    _16
    log(ERROR, errorInfo.toString()); // Logging an error message in case of transmission failure
    _16
    }
    _16
    });

info

Signaling currently supports only string and binary message formats. To send other types of data such as a JSON objects, or data from third-party data construction tools such as protobuf, serialize the data before sending the message. For information on how to effectively construct the payload data structure and recommended serialization methods, refer to Message payload structuring.

Customize channel subscription

By default, you receive message events for all channels you subscribe to. If you don't wish to receive messages from specific channels, while still receiving other types of event notifications from these channels, adjust the subscription settings accordingly. Refer to the following code snippet:


_18
String channelName = "test_channel";
_18
SubscribeOptions options = new SubscribeOptions();
_18
options.setWithMessage(false); // Disable message reception
_18
options.setWithPresence(true); // Enable presence notifications
_18
options.setWithMetadata(true); // Enable metadata retrieval
_18
options.setWithLock(true); // Enable lock status updates
_18
_18
mRtmClient.subscribe(channelName, options, new ResultCallback<Void>() {
_18
@Override
_18
public void onSuccess(Void responseInfo) {
_18
log(CALLBACK, "Successfully subscribed to channel: " + channelName);
_18
}
_18
_18
@Override
_18
public void onFailure(ErrorInfo errorInfo) {
_18
log(ERROR, "Failed to subscribe to channel: " + channelName + ", Error: " + errorInfo.toString());
_18
}
_18
});

In this example, options.setWithMessage(false) ensures that messages from test_channel do not trigger event notifications. However, you continue to receive notifications for other events, such as presence updates, metadata changes, and lock status alterations.

Unsubscribe from a channel

To stop receiving message and all other event notifications from a channel, call unsubscribe.


_12
String channelName = "chats.room1";
_12
mRtmClient.unsubscribe(channelName, new ResultCallback<Void>() {
_12
@Override
_12
public void onSuccess(Void responseInfo) {
_12
log(CALLBACK, "unsubscribe channel " + channelName + " success");
_12
}
_12
_12
@Override
_12
public void onFailure(ErrorInfo errorInfo) {
_12
log(ERROR, errorInfo.toString());
_12
}
_12
});

This method only unsubscribes from one channel at a time. To unsubscribe from multiple channels, call this method multiple times.

Reference

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

Message payload size

Signaling SDK imposes limits on the size of the message payload sent in message channels and stream channels. The limit is 32 KB for message channels and 1 KB for stream channels. The message payload 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.


_6
// ErrorInfo
_6
ErrorInfo {
_6
errorCode = -11010;
_6
reason = "Publish too long message.";
_6
operation = "publishTopicMessage"; // or "publish"
_6
}

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

API reference

Signaling