Thread Messages

Threads enable users to create a separate conversation from a specific message within a chat group to keep the main chat uncluttered.

This page shows how to use the Agora Chat SDK to send, receive, recall, and retrieve thread messages in your app.

Understand the tech

The Agora Chat SDK allows you to implement the following features:

• Send a thread message
• Receive a thread message
• Recall a thread message
• Retrieve a thread message

The following figure shows the workflow of how clients send and receive peer-to-peer messages.

As shown in the figure, the workflow of peer-to-peer messaging is as follows:

1. Clients retrieve a token from your app server.
2. Client A and Client B log in to Agora Chat.
3. Client A sends a message to Client B. The message is sent to the Agora Chat server and the server delivers the message to Client B. When Client B receives the message, the SDK triggers an event. Client B listens for the event and gets the message.

Prerequisites

Before proceeding, ensure that you meet the following requirements:

• You have initialized the Agora Chat SDK. For details, see Get Started with Web.
• You understand the call frequency limit of the Agora Chat APIs supported by different pricing plans as described in Limitations.

Implementation

This section describes how to call the APIs provided by the Agora Chat SDK to implement thread features.

Send a thread message

Send a thread message is similar to send a message in a chat group. The difference lies in the isChatThread field, as shown in the following code sample:

function sendTextMessage() {
    let option = {
        chatType: 'groupChat',     // Sets `chatType` to `groupChat` as a thread belongs to a chat group.
        type: 'txt',               // Sets `type` to `txt` to create and send a text message.
        to: chatThreadId,          // Sets `to` to the ID of a thread that receives the text message.
        msg: 'message content'     // Sets `msg` to the content of the text message.
        isChatThread:true,         // Sets `isChatThread` to `true` to mark this message as a thread message.
    }
    // Calls `create` to create a text message.
    let msg = WebIM.message.create(option); 
    // Calls `send` to send the text message.
    connection.send(msg).then(() => {
        console.log('send private text Success');  
    }).catch((e) => {
        console.log("Send private text error");  
    })
};

For more information about sending a message, see Send Messages.

Receive a thread message

Once a thread has a new message, all chat group members receive the onChatThreadChange callback triggered by the update event. Thread members can also listen for the onTextMessage callback to receive thread messages, as shown in the following code sample:

// The SDK triggers the `onTextMessage` callback when it receives a message.
// After receiving this callback, the SDK parses the message and displays it.
connection.addEventHandler('THREADMESSAGE',{
  onTextMessage:(message) =>{
            if(message.chatThread && JSON.stringify(message.chatThread)!=='{}'){
        console.log(message)
        // You can implement subsequent settings in this callback.
      }
    },
});

For more information about receiving a message, see Receive Messages.

Recall a thread message

Send a thread message is similar to send a message in a chat group. The difference lies in the isChatThread field.

Once a message is recalled in a thread, all chat group members receive the onChatThreadChange callback triggered by the update event. Thread members can also listen for the onRecallMessage callback, as shown in the following code sample:

let option = {
  mid: 'msgId',           // The ID of the message to be recalled.
  to: 'userID',           // The username of the message receiver.
  chatType: 'groupChat'   // Sets `chatType` to `groupChat` as a thread belongs to a chat group.
  isChatThread: true      // Sets `isChatThread` to `true` to mark this message as a thread message.
};
// Calls `recallMessage` to recall a message.
connection.recallMessage(option).then((res) => {
  console.log('success', res)
}).catch((error) => {
  // Occurs when the message fails to be recalled within the default time limit of two minutes.
  console.log('fail', error)
})
// The SDK triggers the `onRecallMessage` callback when it recalls a message.
// After receiving this callback, the SDK parses the message and updates its display.
conn.addEventHandler('MESSAGES',{
   onRecallMessage: => (msg) {
       // You can implement subsequent settings in this callback.
          console.log('Message recall succeeds.'，msg) 
   }, 
})

For more information about recalling a message, see Recall Messages.

Retrieve thread messages from the server

For details about how to retrieve messages from the server, see Retrieve Historical Messages.