Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Signaling Quickstart

Updated

Rapidly develop your first Signaling app.

Use Signaling SDK to add low-latency, high-concurrency signaling and synchronization capabilities to your app.

Signaling also helps you enhance the user experience in Video Calling, Voice Calling, Interactive Live Streaming, and Broadcast Streaming applications.

This page shows you how to use the Signaling SDK to rapidly build a simple application that sends and receives messages. It shows you how to integrate the Signaling SDK in your project and implement pub/sub messaging through Message channels. To get started with stream channels, follow this guide to create a basic Signaling app and then refer to the Stream channels guide.

Understand the tech

To use Signaling features in your app, you initialize a Signaling client instance and add event listeners. To connect to Signaling, you login using an authentication token. To send a message to a message channel, you publish the message. Signaling creates a channel when a user subscribes to it. To receive messages other users publish to a channel, your app listens for events.

To create a pub/sub session for Signaling, implement the following steps in your app:

Prerequisites

To implement the code presented on this page you need to have:

  • An Agora account and project.

  • Enabled Signaling in Agora Console

  • A device running Ubuntu 18.04 or Debian 9.9, aarch64 (arm64) or x86-64 architecture.

  • Java 8 or above.

  • Maven.

  • Ensure that a firewall is not blocking your network communication.

Signaling 2.x is an enhanced version compared to 1.x with a wide range of new features. It follows a new pricing structure. See Pricing for details.

Project setup

Create a project

Create the following folder structure for your project:

RTM_quickstart/
├── src/main/java/io/agora/
└── lib/

Integrate the SDK using Maven Central

To integrate the Linux Java Signaling SDK into your project using Maven:

  1. Create a pom.xml file in the RTM_quickstart folder with the following content:

    Replace x.y.z with the specific SDK version number, such as 2.3.0. To get the latest version number, check the Release notes.

    The artifactId is architecture-specific. Use rtm-java-aarch64 for aarch64 (arm64) devices, or rtm-java-x86_64 for x86-64 devices.

  2. Maven doesn't distribute the native libraries the SDK depends on, so download the SDK package separately, unzip it, and copy the *.so files to the project's lib folder.

Implement Signaling

A complete code sample that implements the basic features of Signaling is presented here for your reference. To use the sample code, copy the following lines into the src/main/java/io/agora/RtmJavaDemo.java file.

Follow the implementation steps to understand the core API calls in the sample code or use the snippets in your own code.

Import Agora classes

To use Signaling APIs in your project, import the relevant Agora classes and interfaces:

import io.agora.rtm.*;

Initialize the Signaling engine

Before calling any other Signaling SDK API, initialize an RtmClient object instance:

RtmConfig config = new RtmConfig.Builder(APP_ID, userId)
        .eventListener(eventListener)
        .build();
rtmClient = RtmClient.create(config);

Add an event listener

Add an event listener to receive message, presence, and connection state events:

private final RtmEventListener eventListener = new RtmEventListener() {
    @Override
    public void onMessageEvent(MessageEvent event) {
        // Handle incoming messages
    }

    @Override
    public void onPresenceEvent(PresenceEvent event) {
        // Handle presence events
    }

    @Override
    public void onLinkStateEvent(LinkStateEvent event) {
        // Handle connection state changes
    }
};

Log in to Signaling

To log in to Signaling, call login and pass in a token:

rtmClient.login(token, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        // Handle login success
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        // Handle login failure
    }
});

Publish a message

To send a message to a channel, call publish. If no user has subscribed to the channel yet, Signaling creates it:

rtmClient.publish(channelName, message, options, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        // Handle publish success
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        // Handle publish failure
    }
});

Subscribe and unsubscribe

To receive messages published to a channel, call subscribe:

SubscribeOptions options = new SubscribeOptions();
options.setWithMessage(true);

rtmClient.subscribe(channelName, options, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        // Handle subscribe success
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        // Handle subscribe failure
    }
});

When you no longer need to receive messages from a channel, call unsubscribe:

rtmClient.unsubscribe(channelName, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        // Handle unsubscribe success
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        // Handle unsubscribe failure
    }
});

Log out of Signaling

When you no longer need to use Signaling, log out and release the client instance:

rtmClient.logout(new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        // Handle logout success
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        // Handle logout failure
    }
});

RtmClient.release();

Test Signaling

Take the following steps to test the sample code:

  1. Generate a temporary token for your project.

  2. In your code, replace <Your App ID> with your app ID from Agora Console and <Your token> with the generated token. Make sure Signaling is activated for your project in Agora Console.

  3. In the terminal, run the following commands to compile the project:

    mvn clean
mvn package

  4. Set the library path and run the app:

    export LD_LIBRARY_PATH=<path to your lib folder>
java -jar target/RTM-Java-Demo-1.0-SNAPSHOT.jar

  5. Follow the prompts to log in and subscribe to a channel.

  6. Run another instance of the app using a different user ID. Follow the prompts to publish a message to the same channel that you subscribed to from the other instance.

  7. You see the message displayed in the instance that you used to subscribe to the channel.

    Congratulations! You have successfully integrated Signaling into your project.

Reference

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

Token authentication

In this guide you retrieve a temporary token from Agora Console. To understand how to create an authentication server for development purposes, see Secure authentication with tokens.

Sample project

Agora provides an open source sample project on GitHub for your reference. Download it or view the source code for a more detailed example.

API reference

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved