azure-communication-chat-java
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.
Install
npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-communication-chat-java
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
git clone https://github.com/microsoft/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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)withmaxPageSizefor large threads - Share History - Set
shareHistoryTimewhen 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 (skills)
-
references
-
examples.md 11.3 KB
Loading…
-
-
SKILL.md 9.3 KB
--- name: azure-communication-chat-java description: 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. license: MIT metadata: author: Microsoft version: "1.0.0" package: com.azure:azure-communication-chat --- # Azure Communication Chat (Java) Build real-time chat applications with thread management, messaging, participants, and read receipts. ## Installation ```xml <dependency> <groupId>com.azure</groupId> <artifactId>azure-communication-chat</artifactId> <version>1.6.0</version> </dependency> ``` ## Client Creation ```java 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 ```java 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 ```java // 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 ```java 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 ```java // Update message UpdateChatMessageOptions updateOptions = new UpdateChatMessageOptions() .setContent("Updated message content"); threadClient.updateMessage(messageId, updateOptions); // Delete message threadClient.deleteMessage(messageId); ``` ## Manage Participants ```java // 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 ```java // 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 ```java 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 ```java // 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 ```java // 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 ```java 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 ```java 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 ```bash AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com AZURE_COMMUNICATION_USER_TOKEN=<user-access-token> ``` ## Best Practices 1. **Token Management** - User tokens expire; implement refresh logic with `CommunicationTokenRefreshOptions` 2. **Pagination** - Use `listMessages(options)` with `maxPageSize` for large threads 3. **Share History** - Set `shareHistoryTime` when adding participants to control message visibility 4. **Message Types** - Filter system messages (`PARTICIPANT_ADDED`, etc.) from user messages 5. **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"
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.