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

SDK quickstart

Updated

A highly reliable global communication platform where users can chat one-to-one, in groups or in chat rooms.

Instant messaging enhances user engagement by enabling users to connect and form a community within the app. Increased engagement can lead to increased user satisfaction and loyalty to your app. An instant messaging feature can also provide real-time support to users, allowing them to get help and answers to their questions quickly. The Chat SDK enables you to embed real-time messaging in any app, on any device, anywhere.

This page guides you through implementing peer-to-peer messaging into your app using the Chat SDK.

Understand the tech

The following figure shows the workflow of sending and receiving peer-to-peer messages using Chat SDK.

Chat SDK workflow

  1. Clients retrieve an authentication token from your app server.
  2. Users log in to Chat using the App ID, their user ID, and token.
  3. Clients send and receive messages through Chat as follows:
    1. Client A sends a message to Client B. The message is sent to the Agora Chat server.
    2. The server delivers the message to Client B. When Client B receives a message, the SDK triggers an event.
    3. Client B listens for the event to read and display the message.

Prerequisites

In order to follow the procedure on this page, you must have:

Project setup

  1. Create a Unity project:

    1. In Unity Hub, select Projects, then click New Project.

    2. In All templates, select 3D. Set the Project name and Location, then click Create Project.

      Your project opens in Unity Editor.

  2. Integrate Chat SDK into your project:

    1. Unzip Chat SDK for Unity to a local folder:

    2. In Unity, click Assets > Import Package > Custom Package.

    3. Navigate to the Chat SDK package and click Open.

    4. In Import Unity Package, click Import.

Implement peer-to-peer messaging

This section shows how to use the Chat SDK to implement peer-to-peer messaging in your app, step by step.

Create the UI

In the quick start app, you create a simple UI that consists of the following elements:

  • A Button - TextMeshPro to log in or out of Agora Chat.
  • An Input Field - TextMeshPro to specify the recipient user ID.
  • An Input Field - TextMeshPro to enter a text message.
  • A Button - TextMeshPro to send the text message.
  • A Scroll View to display all sent and received messages.

To implement this user interface, in your Unity project:

  1. Set up the Scroll View

    1. In Unity Editor, right-click Sample Scene, then click Game Object > UI > Scroll View. A scroll view appears in the Scene Canvas. In Inspector, rename the Scroll View to scrollView.

      If you can't see the view clearly in Unity, zoom out and rotate the scene

    2. To adjust the scrollView size, change the following coordinates in Inspector:

      • Pos X - 0
      • Pos Y - 0
      • Width - 250
      • Height - 300

    3. In Hierarchy select scrollView > Viewport > Content. In Inspector click Add Component and choose Layout > Vertical Layout Group.

    4. In Inspector click Add Component again, and select Layout > Content Size Fitter. Set the Vertical fit property of the component to Preferred Size.

    5. In Inspector click Add Component again, and select UI > TextMeshPro - Text (UI). In the TMP Importer pop-up, click Import TMP Essentials. Your project imports the required components to your project. Expand the TextMeshPro - Text component properties and under Extra Settings set the Left, Top, Right and Bottom margins to 10.

  2. Add a login button

    1. In Hierarchy, right-click Sample Scene, then click UI > Button - TextMeshPro. A button appears in the Scene Canvas. In Inspector, rename Button to joinBtn, then change the following properties:

      • Pos X - 89
      • Pos Y - 160
      • Width - 70
      • Height - 30

    2. Select the Text (TMP) sub-item of joinBtn and in Inspector, change Text to Join.

  3. Add a send button

    1. Right-click Sample Scene, then click UI > Button - TextMeshPro. A button appears in the Scene Canvas. In Inspector, rename Button to sendBtn, then change the following properties:

      • Pos X - 97
      • Pos Y - -162
      • Width - 57
      • Height - 30

    2. Select the Text (TMP) sub-item of sendBtn and in Inspector, change Text to >>.

  4. Add input fields to enter a message and a recipient user ID

    1. Right-click Sample Scene, then click UI > Input Field - TextMeshPro. An input field appears in the Scene Canvas. In Inspector, rename InputField (TMP) to message, and change the following coordinates:

      • Pos X - -27
      • Pos Y - -162
      • Width - 195
      • Height - 30

    2. Repeat the procedure in the previous step to add another input field named userName. In Inspector set the following coordinates:

      • Pos X - -35
      • Pos Y - 160
      • Width - 180
      • Height - 30

Handle the system logic

In this section, you create a script file, add the necessary namespaces, and bind your script to the canvas.

  1. Create a new script

    1. In Project, open Assets > AgoraChat > Scripts. Right-click Scripts, then click Create > C# Script. In Assets, you see the NewBehaviourScript file that you use to implement Chat SDK in your app.

    2. In Inspector, click Open. NewBehaviourScript.cs opens in your default text editor.

  2. Import the relevant Agora and Unity classes

    In NewBehaviourScript.cs, add the following lines after using UnityEngine;:

    using UnityEngine.UI;
using TMPro;
using AgoraChat;
using AgoraChat.MessageBody;

  3. Bind your script to the canvas

    1. Drag NewBehaviourScript.cs from Assets/AgoraChat/Scripts, and drop it on to Canvas in the Hierarchy.

    2. Click Canvas, you see that your script is added to Canvas in Inspector.

Send and receive messages

When a user opens the app, you instantiate and initialize a SDKClient. When the user taps the Join button, the app logs in to Agora Chat. When a user types a message in the text box and then presses >>, the typed message is sent to Agora Chat. When the app receives a message from the server, the message is displayed in the message list. This simple workflow enables you to rapidly build a Chat client with basic functionality.

The following figure shows the API call sequence for implementing this workflow.

API call sequence

To implement this workflow in your app, take the following steps:

  1. Declare variables

    In the NewBehaviourScript class, add the following declarations:

    private TMP_Text messageList;
private string userId = "";
private string token = "";
private string appId = "";
private bool isJoined = false;
SDKClient agoraChatClient;

  2. Set up Chat when the app starts

    When the app starts, you set up a SDKClient and callbacks to handle Chat events. To do this, replace the Start method in the NewBehaviourScript class with the following:

    void Start()
{
    GameObject.Find("userName/Text Area/Placeholder").GetComponent<TMP_Text>().text = "Enter recipient name";
    GameObject.Find("message/Text Area/Placeholder").GetComponent<TMP_Text>().text = "Message";
    messageList = GameObject.Find("scrollView/Viewport/Content").GetComponent<TextMeshProUGUI>();
    messageList.fontSize = 14;
    messageList.text = "";
    GameObject button = GameObject.Find("joinBtn");
    button.GetComponent<Button>().onClick.AddListener(joinLeave);
    button = GameObject.Find("sendBtn");
    button.GetComponent<Button>().onClick.AddListener(sendMessage);
    setupChatSDK();
}

  3. Instantiate the SDKClient

    To implement peer-to-peer messaging, you use Chat SDK to initialize a SDKClient instance. In the NewBehaviourScript class, add the following method before Start.

    void setupChatSDK()
{
    if (appId == "")
    {
        Debug.Log("You should set your App ID first!");
        return;
    }
    // Initialize the Agora Chat SDK
    Options options = Options.InitOptionsWithAppId(appId);
    options.UsingHttpsOnly = true;
    options.DebugMode = true;
    agoraChatClient = SDKClient.Instance;
    agoraChatClient.InitWithOptions(options);
}

  4. Handle and respond to Chat events

    To receive notification of Chat events such as connection, disconnection, and token expiration, you use IChatManagerDelegate and IConnectionDelegate. When you receive the onMessageReceived notification, you display the message to the user. To implement these notifications in your app, do the following:

    1. In the NewBehaviourScript class, add the following at the end of setupChatSDK:

      agoraChatClient.ChatManager.AddChatManagerDelegate(this);

    2. Implement the IChatManagerDelegate and IConnectionDelegate interfaces in the NewBehaviourScript class. In NewBehaviourScript.cs, add the following after public class NewBehaviourScript : MonoBehaviour:

      , IChatManagerDelegate, IConnectionDelegate

    3. In the NewBehaviourScript class, add the following callbacks before setupChatSDK:

      public void OnMessagesReceived(List<Message> messages)
{
    foreach (Message msg in messages)
    {
        if (msg.Body.Type == MessageBodyType.TXT)
        {
            TextBody txtBody = msg.Body as TextBody;
            string Msg = msg.From + ":" + txtBody.Text;
            displayMessage(Msg, false);
        }
    }
}
public void OnCmdMessagesReceived(List<Message> messages)
{
    // This callback is triggered only by the reception of a command message that is usually invisible to users.
}
public void OnMessagesRead(List<Message> messages)
{
    // Occurs when a read receipt is received for a message.
}
public void OnMessagesDelivered(List<Message> messages)
{
    // Occurs when a delivery receipt is received.
}
public void OnMessagesRecalled(List<Message> messages)
{
    // Occurs when a received message is recalled.
}
public void OnReadAckForGroupMessageUpdated()
{
    // Occurs when the read status updates of a group message is received.
}
public void OnGroupMessageRead(List<GroupReadAck> list)
{
    // Occurs when a read receipt is received for a group message.
}
public void OnConversationsUpdate()
{
    // Occurs when the number of conversations changes.
}
public void OnConversationRead(string from, string to)
{
    // Occurs when the read receipt is received for a conversation.
}
public void MessageReactionDidChange(List<MessageReactionChange> list)
{
    // Occurs when the reactions change.
}
public void OnConnected()
{
    Debug.Log("Connected");
}
public void OnTokenExpired()
{
    // Occurs when the token has expired.
}
public void OnTokenWillExpire()
{
    // Occurs when the token is about to expire
}
public void OnAuthFailed()
{
    // Occurs when the user is forced to log out of the current account due to an authentication failure.
}
public void OnKickedByOtherDevice()
{
    // Occurs when the user is forced to log out of the current account on the current device due to login to another device.
}
public void OnLoginTooManyDevice()
{
    // Occurs when the user is forced to log out of the current account because he or she reached the maximum number of devices that the user can log in to with the current account.
}
public void OnChangedIMPwd()
{
    // Occurs when the user is forced to log out of the current account because the login password has changed.
}
public void OnForbidByServer()
{
    // Occurs when the current user account is banned.
}
public void OnRemovedFromServer()
{
    // Occurs when the current user account is removed from the server.
}
public void OnLoggedOtherDevice(string deviceName, string info)
{
    // Occurs when the user logs in to another device with the current account.
}
public void OnDisconnected()
{
    Debug.Log("Disconnected");
}
public void OnMessageContentChanged(Message msg, string operatorId, long operationTime)
{
}
public void OnMessagePinChanged(string messageId, string conversationId, bool isPinned, string operatorId, long operationTime)
{
}
public void OnLoggedOtherDevice(string str)
{
}
public void OnAppActiveNumberReachLimitation()
{
}
public void OnMessageContentChanged(Message msg, string operatorId, long operationTime)
{
}
public void OnMessagePinChanged(string messageId, string conversationId, bool isPinned, string operatorId, long operationTime)
{
}
public void OnOfflineMessageSyncStart()
{
}
public void OnOfflineMessageSyncFinish()
{
}

  5. Log in to Agora Chat

    When a user presses Join, your app logs in to Agora Chat. When a user presses Leave, the app logs out of Agora Chat. To implement this logic, in the NewBehaviourScript class, add the following method before Start:

    public void joinLeave()
{
    if (isJoined)
    {
        agoraChatClient.Logout(true, callback: new CallBack(
        onSuccess: () =>
        {
            Debug.Log("Logout succeed");
            isJoined = false;
            GameObject.Find("joinBtn").GetComponentInChildren<TextMeshProUGUI>().text = "Join";
        },
        onError: (code, desc) =>
        {
            Debug.Log($"Logout failed, code: {code}, desc: {desc}");
        }));
    }
    else
    {
        // Use LoginWithToken to replace LoginWithAgoraToken for the SDK of v1.3.0 or later
        agoraChatClient.LoginWithAgoraToken(userId, token, callback: new CallBack(
        onSuccess: () =>
        {
            Debug.Log("Login succeed");
            isJoined = true;
            GameObject.Find("joinBtn").GetComponentInChildren<TextMeshProUGUI>().text = "Leave";
        },
        onError: (code, desc) =>
        {
            Debug.Log($"Login failed, code: {code}, desc: {desc}");
        }));
    }
}

  6. Send a message

    To send a message to Agora Chat when a user presses the >> button, add the following method to the NewBehaviourScript class, before Start:

    public void sendMessage()
{
    string recipient = GameObject.Find("userName").GetComponent<TMP_InputField>().text;
    string Msg = GameObject.Find("message").GetComponent<TMP_InputField>().text;
    if (Msg == "" || recipient == "")
    {
        Debug.Log("You did not type your message");
        return;
    }
    Message msg = Message.CreateTextSendMessage(recipient, Msg);
    displayMessage(Msg, true);
    agoraChatClient.ChatManager.SendMessage(ref msg, new CallBack(
        onSuccess: () =>
        {
            Debug.Log($"Send message succeed");
            GameObject.Find("message").GetComponent<TMP_InputField>().text = "";
        },
        onError: (code, desc) =>
        {
            Debug.Log($"Send message failed, code: {code}, desc: {desc}");
        }));
}

  7. Display chat messages

    To display sent and received messages in your app, add the following method to the NewBehaviourScript class:

    public void displayMessage(string messageText, bool isSentMessage)
{
    if (isSentMessage)
    {
        messageList.text += "<align=\"right\"><color=black><mark=#dcf8c655 padding=\"10, 10, 0, 0\">" + messageText + "</color></mark>\n";
    }
    else
    {
        messageList.text += "<align=\"left\"><color=black><mark=#ffffff55 padding=\"10, 10, 0, 0\">" + messageText + "</color></mark>\n";
    }
}

  8. Clean up the resources

    When you quit the app, it calls OnApplicationQuit. You use this method for clean up. To Implement the clean up logic, in the NewBehaviourScript class, add the following after Start:

    void OnApplicationQuit()
{
    agoraChatClient.ChatManager.RemoveChatManagerDelegate(this);
    agoraChatClient.Logout(true, callback: new CallBack(
        onSuccess: () =>
        {
            Debug.Log("Logout succeed");
        },
        onError: (code, desc) =>
        {
            Debug.Log($"Logout failed, code: {code}, desc: {desc}");
        }));
}

Test your implementation

To ensure that you have implemented Peer-to-Peer Messaging in your app:

  1. Register a user in Agora Console and Generate a user token.

  2. In the NewBehaviourScript class, update userId, token, and appId with values from Agora Console. To get your App ID, see Get Chat project information.

  3. In Unity Editor, click Play. A moment later you see the project installed on your development device.

  4. Click Join to log in to Agora Chat.

  5. Type the recipient user name in the Recepient Name field.

  6. Type a message in the Message field and press >>.

    The message is sent and a confirmation message is displayed in the debug console.

  7. Register the recipient user in Agora Console and Generate a user token.

  8. In the NewBehaviourScript class, update userId and token with values you generated for recipient. Make sure you use the same appId as for both users.

  9. Save your changes and click Play to run the app.

  10. Click Join to log in to the Chat.

    You see a message in the scroll view that you sent earlier.

Reference

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

API reference​

Next steps

In a production environment, best practice is to deploy your own token server. Users retrieve a token from the token server to log in to Chat. To see how to implement a server that generates and serves tokens on request, see Secure authentication with tokens.

Contact Us

+1 (408) 879-5885

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

AgoraCopyright © 2026 AgoraAll rights reserved