---

name: azure-communication-chat-java description: "使用线程管理、消息传递、参与者和已读回执构建实时聊天应用程序。" risk: unknown source: community date_added: "2026-02-27"

Azure Communication Chat（Java）

使用线程管理、消息传递、参与者和已读回执构建实时聊天应用程序。

安装

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version>1.6.0</version>
</dependency>

客户端创建

import com.azure.communication.chat.ChatClient;
import com.azure.communication.chat.ChatClientBuilder;
import com.azure.communication.chat.ChatThreadClient;
import com.azure.communication.common.CommunicationTokenCredential;

// ChatClient 需要 CommunicationTokenCredential（用户访问令牌）
String endpoint = "https://<resource>.communication.azure.com";
String userAccessToken = "<user-access-token>";

CommunicationTokenCredential credential = new CommunicationTokenCredential(userAccessToken);

ChatClient chatClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

// 异步客户端
ChatAsyncClient chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildAsyncClient();

关键概念

| 类 | 用途 | |-------|---------| | ChatClient | 创建/删除聊天线程，获取线程客户端 | | ChatThreadClient | 线程内的操作（消息、参与者、回执） | | ChatParticipant | 聊天线程中带有显示名称的用户 | | ChatMessage | 消息内容、类型、发送者信息、时间戳 | | ChatMessageReadReceipt | 每个参与者的已读回执跟踪 |

创建聊天线程

import com.azure.communication.chat.models.*;
import com.azure.communication.common.CommunicationUserIdentifier;
import java.util.ArrayList;
import java.util.List;

// 定义参与者
List<ChatParticipant> participants = new ArrayList<>();

ChatParticipant participant1 = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-1>"))
    .setDisplayName("Alice");

ChatParticipant participant2 = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-2>"))
    .setDisplayName("Bob");

participants.add(participant1);
participants.add(participant2);

// 创建线程
CreateChatThreadOptions options = new CreateChatThreadOptions("Project Discussion")
    .setParticipants(participants);

CreateChatThreadResult result = chatClient.createChatThread(options);
String threadId = result.getChatThread().getId();

// 获取线程客户端进行操作
ChatThreadClient threadClient = chatClient.getChatThreadClient(threadId);

发送消息

// 发送文本消息
SendChatMessageOptions messageOptions = new SendChatMessageOptions()
    .setContent("Hello, team!")
    .setSenderDisplayName("Alice")
    .setType(ChatMessageType.TEXT);

SendChatMessageResult sendResult = threadClient.sendMessage(messageOptions);
String messageId = sendResult.getId();

// 发送 HTML 消息
SendChatMessageOptions htmlOptions = new SendChatMessageOptions()
    .setContent("<strong>Important:</strong> Meeting at 3pm")
    .setType(ChatMessageType.HTML);

threadClient.sendMessage(htmlOptions);

获取消息

import com.azure.core.util.paging.PagedIterable;

// 列出所有消息
PagedIterable<ChatMessage> messages = threadClient.listMessages();

for (ChatMessage message : messages) {
    System.out.println("ID: " + message.getId());
    System.out.println("Type: " + message.getType());
    System.out.println("Content: " + message.getContent().getMessage());
    System.out.println("Sender: " + message.getSenderDisplayName());
    System.out.println("Created: " + message.getCreatedOn());

    // 检查是否已编辑或删除
    if (message.getEditedOn() != null) {
        System.out.println("Edited: " + message.getEditedOn());
    }
}

管理参与者

// 添加参与者
ChatParticipant newParticipant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-3>"))
    .setDisplayName("Charlie");

threadClient.addParticipant(newParticipant);

// 列出参与者
PagedIterable<ChatParticipant> participantList = threadClient.listParticipants();
for (ChatParticipant p : participantList) {
    System.out.println(p.getDisplayName());
}

// 移除参与者
threadClient.removeParticipant(new CommunicationUserIdentifier("<user-id-3>"));

已读回执

// 发送已读回执
threadClient.sendReadReceipt(messageId);

// 列出已读回执
PagedIterable<ChatMessageReadReceipt> receipts = threadClient.listReadReceipts();
for (ChatMessageReadReceipt receipt : receipts) {
    System.out.println("Reader: " + receipt.getSenderCommunicationIdentifier());
    System.out.println("Read until: " + receipt.getReadOn());
}

更新和删除

// 更新消息
UpdateChatMessageOptions updateOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");
threadClient.updateMessage(messageId, updateOptions);

// 删除消息
threadClient.deleteMessage(messageId);

// 更新线程主题
threadClient.updateTopic("New Topic Name");

// 删除线程
chatClient.deleteChatThread(threadId);

输入指示器

// 发送输入通知
threadClient.sendTypingNotification();

最佳实践

• 使用异步客户端处理高吞吐量场景
• 实现分页以高效处理大型消息列表
• 使用已读回执跟踪消息送达状态
• 正确处理令牌过期和刷新
• 为生产应用实现错误处理和重试逻辑