Azure Communication Chat Java

MicrosoftOfficialCreated by Microsoft

Skill
Tool integration
Software development
MIT
No issues found

From the author

Build real-time chat applications with Azure Communication Services Chat Java SDK. Use when implementing chat threads, messaging, participants, read receipts, typing notifications, or real-time chat features.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Azure Communication Chat Java SDK provides a comprehensive set of tools for developers to build real-time chat functionality into their Java applications. It supports core messaging features including thread management, participant handling, read receipts, and typing notifications. The SDK offers both synchronous and asynchronous client patterns, allowing for flexible integration into various application architectures.

What it does

Create and manage chat threads and their properties
Send and receive text and HTML-formatted messages
Manage chat participants, including adding and removing users
Implement read receipts to track message status
Send and receive typing notifications for real-time engagement
List and paginate through chat history and thread metadata

When to use it

When building real-time messaging features in a Java-based application
When you need to manage chat threads and participant access control
When implementing advanced chat features like read receipts or typing indicators
When integrating Azure Communication Services into a backend service

Advantages

Provides both synchronous and asynchronous client options
Supports robust error handling for API interactions
Includes built-in support for pagination of large message histories
Offers granular control over participant history visibility

Usage examples

“How do I create a new chat thread with two participants using the Java SDK?”: The agent provides code to instantiate a ChatClient, define ChatParticipant objects with identifiers, and use CreateChatThreadOptions to initialize the thread.
“Show me how to send a text message to an existing chat thread.”: The agent demonstrates using the ChatThreadClient to send a SendChatMessageOptions object containing the message content and sender display name.
“How can I list all messages in a chat thread with pagination?”: The agent explains using ListChatMessagesOptions with a defined maxPageSize and iterating through the PagedIterable results.
“How do I handle errors when sending a message?”: The agent provides a try-catch block example using HttpResponseException to handle specific status codes like 401, 403, and 404.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/azure-communication-chat-java/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip azure-communication-chat-java.zip -d .agents/skills

Documentation by Microsoft

Azure Communication Chat (Java)

Build real-time chat applications with thread management, messaging, participants, and read receipts.

Installation

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

Client Creation

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 requires a CommunicationTokenCredential (user access token)
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();

// Async client
ChatAsyncClient chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildAsyncClient();

Key Concepts

Class	Purpose
`ChatClient`	Create/delete chat threads, get thread clients
`ChatThreadClient`	Operations within a thread (messages, participants, receipts)
`ChatParticipant`	User in a chat thread with display name
`ChatMessage`	Message content, type, sender info, timestamps
`ChatMessageReadReceipt`	Read receipt tracking per participant

Create Chat Thread

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<>();

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);

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

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

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

Send Messages

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

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

// Send HTML message
SendChatMessageOptions htmlOptions = new SendChatMessageOptions()
    .setContent("<strong>Important:</strong> Meeting at 3pm")
    .setType(ChatMessageType.HTML);

threadClient.sendMessage(htmlOptions);

Get Messages

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

// List all messages
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());
    
    // Check if edited or deleted
    if (message.getEditedOn() != null) {
        System.out.println("Edited: " + message.getEditedOn());
    }
    if (message.getDeletedOn() != null) {
        System.out.println("Deleted: " + message.getDeletedOn());
    }
}

// Get specific message
ChatMessage message = threadClient.getMessage(messageId);

Update and Delete Messages

// Update message
UpdateChatMessageOptions updateOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

threadClient.updateMessage(messageId, updateOptions);

// Delete message
threadClient.deleteMessage(messageId);

Manage Participants

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

for (ChatParticipant participant : participants) {
    CommunicationUserIdentifier user = 
        (CommunicationUserIdentifier) participant.getCommunicationIdentifier();
    System.out.println("User: " + user.getId());
    System.out.println("Display Name: " + participant.getDisplayName());
}

// Add participants
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
CommunicationUserIdentifier userToRemove = new CommunicationUserIdentifier("<user-id>");
threadClient.removeParticipant(userToRemove);

Read Receipts

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

// Get read receipts
PagedIterable<ChatMessageReadReceipt> receipts = threadClient.listReadReceipts();

for (ChatMessageReadReceipt receipt : receipts) {
    System.out.println("Message ID: " + receipt.getChatMessageId());
    System.out.println("Read by: " + receipt.getSenderCommunicationIdentifier());
    System.out.println("Read at: " + receipt.getReadOn());
}

Typing Notifications

import com.azure.communication.chat.models.TypingNotificationOptions;

// Send typing notification
TypingNotificationOptions typingOptions = new TypingNotificationOptions()
    .setSenderDisplayName("Alice");

threadClient.sendTypingNotificationWithResponse(typingOptions, Context.NONE);

// Simple typing notification
threadClient.sendTypingNotification();

Thread Operations

// Get thread properties
ChatThreadProperties properties = threadClient.getProperties();
System.out.println("Topic: " + properties.getTopic());
System.out.println("Created: " + properties.getCreatedOn());

// Update topic
threadClient.updateTopic("New Project Discussion Topic");

// Delete thread
chatClient.deleteChatThread(threadId);

List Threads

// List all chat threads for the user
PagedIterable<ChatThreadItem> threads = chatClient.listChatThreads();

for (ChatThreadItem thread : threads) {
    System.out.println("Thread ID: " + thread.getId());
    System.out.println("Topic: " + thread.getTopic());
    System.out.println("Last message: " + thread.getLastMessageReceivedOn());
}

Pagination

import com.azure.core.http.rest.PagedResponse;

// Paginate through messages
int maxPageSize = 10;
ListChatMessagesOptions listOptions = new ListChatMessagesOptions()
    .setMaxPageSize(maxPageSize);

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

pagedMessages.iterableByPage().forEach(page -> {
    System.out.println("Page status code: " + page.getStatusCode());
    page.getElements().forEach(msg -> 
        System.out.println("Message: " + msg.getContent().getMessage()));
});

Error Handling

import com.azure.core.exception.HttpResponseException;

try {
    threadClient.sendMessage(messageOptions);
} catch (HttpResponseException e) {
    switch (e.getResponse().getStatusCode()) {
        case 401:
            System.out.println("Unauthorized - check token");
            break;
        case 403:
            System.out.println("Forbidden - user not in thread");
            break;
        case 404:
            System.out.println("Thread not found");
            break;
        default:
            System.out.println("Error: " + e.getMessage());
    }
}

Message Types

Type	Description
`TEXT`	Regular chat message
`HTML`	HTML-formatted message
`TOPIC_UPDATED`	System message - topic changed
`PARTICIPANT_ADDED`	System message - participant joined
`PARTICIPANT_REMOVED`	System message - participant left

Environment Variables

AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
AZURE_COMMUNICATION_USER_TOKEN=<user-access-token>

Best Practices

Token Management - User tokens expire; implement refresh logic with CommunicationTokenRefreshOptions
Pagination - Use listMessages(options) with maxPageSize for large threads
Share History - Set shareHistoryTime when adding participants to control message visibility
Message Types - Filter system messages (PARTICIPANT_ADDED, etc.) from user messages
Read Receipts - Send receipts only when messages are actually viewed by user

Trigger Phrases

"chat application Java", "real-time messaging Java"
"chat thread", "chat participants", "chat messages"
"read receipts", "typing notifications"
"Azure Communication Services chat"

Files

ATTRIBUTION.mdAdded by AutoGineer994 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md9.3 KiB
references/examples.md11.3 KiB

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/azure-sdk-java/skills/azure-communication-chat-java · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download azure-communication-chat-java.zip