Azure Communication Chat for Java: Setup, Usage & Best Practices

What This Skill Does

The Azure Communication Services Chat SDK for Java enables building real-time text chat applications with thread management, participant handling, read receipts, typing notifications, and message history. This skill provides the server-side infrastructure for chat features in applications, supporting group conversations, direct messaging, and integration with other Azure Communication Services like calling.

Unlike consumer messaging apps that provide complete experiences, this SDK provides building blocks for integrating chat into your applications. You control the UX, data retention, moderation rules, and user identity while Azure handles message delivery, real-time notifications, and scalable infrastructure.

The SDK's thread-based model organizes conversations logically. Each thread can have multiple participants, supports rich message types (text, HTML), maintains read status for each participant, and provides full message history. This architecture enables building customer support chats, team collaboration tools, or social messaging features.

Getting Started

Add the Maven dependency:

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

Create a ChatClient (requires user access token):

import com.azure.communication.chat.ChatClient;
import com.azure.communication.chat.ChatClientBuilder;
import com.azure.communication.common.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();

Key Features

Thread Management: Organize conversations into threads with topics, participants, and message history. Threads are persistent - participants can leave and rejoin without losing context.

Rich Messages: Send text or HTML-formatted messages with sender display names. Messages include timestamps, sender identification, and support for editing and deletion.

Participant Management: Add or remove participants dynamically, control message history visibility with share-history-time, and list current thread members.

Read Receipts: Track which participants have read which messages. Essential for understanding message acknowledgment in customer support or team collaboration scenarios.

Typing Notifications: Indicate when participants are typing. Provides real-time feedback improving the chat experience.

Message History: Access full conversation history with pagination. Retrieve messages, check for edits or deletions, and implement features like message search or archiving.

System Messages: Automatic system messages for thread events (participant added/removed, topic updated). Helps participants understand thread changes without manual notifications.

Usage Examples

Create a thread and send messages:

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

// Define participants
List<ChatParticipant> participants = new ArrayList<>();
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-1>"))
    .setDisplayName("Alice"));
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-2>"))
    .setDisplayName("Bob"));

// Create thread
CreateChatThreadOptions options = 
    new CreateChatThreadOptions("Project Discussion")
        .setParticipants(participants);

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

// Get thread client
ChatThreadClient threadClient = chatClient.getChatThreadClient(threadId);

// Send message
SendChatMessageOptions messageOptions = new SendChatMessageOptions()
    .setContent("Hello, team!")
    .setSenderDisplayName("Alice")
    .setType(ChatMessageType.TEXT);

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

Read messages and manage receipts:

// List messages
PagedIterable<ChatMessage> messages = threadClient.listMessages();

for (ChatMessage message : messages) {
    System.out.println(message.getSenderDisplayName() + ": " + 
                      message.getContent().getMessage());
    
    // Check if edited or deleted
    if (message.getEditedOn() != null) {
        System.out.println("  (edited)");
    }
    if (message.getDeletedOn() != null) {
        System.out.println("  (deleted)");
    }
}

// Send read receipt
threadClient.sendReadReceipt(messageId);

// Check who read the message
PagedIterable<ChatMessageReadReceipt> receipts = threadClient.listReadReceipts();
for (ChatMessageReadReceipt receipt : receipts) {
    System.out.println(receipt.getSenderCommunicationIdentifier() + 
                      " read message " + receipt.getChatMessageId());
}

Manage participants:

// List participants
PagedIterable<ChatParticipant> participants = threadClient.listParticipants();

// Add participant
List<ChatParticipant> newParticipants = new ArrayList<>();
newParticipants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier("<new-user-id>"))
    .setDisplayName("Charlie")
    .setShareHistoryTime(OffsetDateTime.now().minusDays(7))); // Share last 7 days

threadClient.addParticipants(newParticipants);

// Remove participant
threadClient.removeParticipant(
    new CommunicationUserIdentifier("<user-id>"));

Best Practices

Implement token refresh for long-running clients. User access tokens expire - use CommunicationTokenRefreshOptions to auto-refresh:

import com.azure.communication.common.CommunicationTokenRefreshOptions;

Callable<String> tokenRefresher = () -> fetchNewTokenFromServer();

CommunicationTokenRefreshOptions refreshOptions = 
    new CommunicationTokenRefreshOptions(tokenRefresher)
        .setRefreshProactively(true)
        .setInitialToken(currentToken);

CommunicationTokenCredential credential = 
    new CommunicationTokenCredential(refreshOptions);

Use pagination for large threads. Don't load all messages at once:

ListChatMessagesOptions listOptions = new ListChatMessagesOptions()
    .setMaxPageSize(20);

PagedIterable<ChatMessage> messages = threadClient.listMessages(listOptions);

Set share-history-time when adding participants. Control which messages new participants can see:

participant.setShareHistoryTime(OffsetDateTime.now().minusHours(24));

Filter system messages from user messages. System messages have type PARTICIPANT_ADDED, PARTICIPANT_REMOVED, TOPIC_UPDATED - filter these for user-facing chat UIs.

Handle document-level errors. Some participants may fail to add while others succeed - check individual results:

try {
    threadClient.addParticipants(participants);
} catch (HttpResponseException e) {
    // Handle errors
}

Send typing notifications when appropriate:

threadClient.sendTypingNotification();

Close clients properly:

// ChatClient and ChatThreadClient implement AutoCloseable
chatClient.close();

When to Use This Skill

Use Azure Communication Chat for building messaging features in customer support applications, team collaboration tools, social apps, or any application requiring real-time text communication.

This skill excels at customer service scenarios. Build support chat widgets on websites, help desk applications, or mobile support apps with message history and participant management.

Choose this skill when integrating chat with Azure Communication calling. Build unified communication experiences where users can escalate from text chat to voice/video calls seamlessly.

It's perfect for multi-platform messaging. The SDK works consistently across web, mobile, and server - use the same backend for iOS, Android, and web clients.

Use it for building custom chat UIs. Unlike off-the-shelf chat widgets, you control every aspect of the user experience while Azure handles infrastructure.

When NOT to Use This Skill

Avoid this skill for high-volume public broadcasting. Chat is designed for conversations, not one-to-many broadcasting to thousands. Use Event Grid or other pub/sub services for broadcast scenarios.

Don't use it for file sharing without additional implementation. Messages support text and HTML only - implement file sharing separately using blob storage and share URLs in messages.

Skip this for anonymous chat without user management. The SDK requires user identities and access tokens. For anonymous chat, implement user creation flows first.

Avoid for chat requiring end-to-end encryption. Messages are encrypted in transit and at rest, but Azure has access. For E2E encryption, implement encryption client-side before sending.

This skill doesn't provide push notifications. Implement push notifications separately using Azure Notification Hubs or platform-specific services.

Related Skills

• azure-communication-callautomation-java - Add voice calling to chat applications
• azure-communication-common-java - Shared authentication and identity utilities
• azure-notification-hubs - Push notifications for chat messages

Source

Official SDK: azure-sdk-for-java/sdk/communication/azure-communication-chat

API Documentation: Azure Communication Chat