Azure Communication Chat Java

1---
2name: azure-communication-chat-java
3description: 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.
4package: com.azure:azure-communication-chat
5---
6 
7# Azure Communication Chat (Java)
8 
9Build real-time chat applications with thread management, messaging, participants, and read receipts.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-communication-chat</artifactId>
17    <version>1.6.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23```java
24import com.azure.communication.chat.ChatClient;
25import com.azure.communication.chat.ChatClientBuilder;
26import com.azure.communication.chat.ChatThreadClient;
27import com.azure.communication.common.CommunicationTokenCredential;
28 
29// ChatClient requires a CommunicationTokenCredential (user access token)
30String endpoint = "https://<resource>.communication.azure.com";
31String userAccessToken = "<user-access-token>";
32 
33CommunicationTokenCredential credential = new CommunicationTokenCredential(userAccessToken);
34 
35ChatClient chatClient = new ChatClientBuilder()
36    .endpoint(endpoint)
37    .credential(credential)
38    .buildClient();
39 
40// Async client
41ChatAsyncClient chatAsyncClient = new ChatClientBuilder()
42    .endpoint(endpoint)
43    .credential(credential)
44    .buildAsyncClient();
45```
46 
47## Key Concepts
48 
49| Class | Purpose |
50|-------|---------|
51| `ChatClient` | Create/delete chat threads, get thread clients |
52| `ChatThreadClient` | Operations within a thread (messages, participants, receipts) |
53| `ChatParticipant` | User in a chat thread with display name |
54| `ChatMessage` | Message content, type, sender info, timestamps |
55| `ChatMessageReadReceipt` | Read receipt tracking per participant |
56 
57## Create Chat Thread
58 
59```java
60import com.azure.communication.chat.models.*;
61import com.azure.communication.common.CommunicationUserIdentifier;
62import java.util.ArrayList;
63import java.util.List;
64 
65// Define participants
66List<ChatParticipant> participants = new ArrayList<>();
67 
68ChatParticipant participant1 = new ChatParticipant()
69    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-1>"))
70    .setDisplayName("Alice");
71 
72ChatParticipant participant2 = new ChatParticipant()
73    .setCommunicationIdentifier(new CommunicationUserIdentifier("<user-id-2>"))
74    .setDisplayName("Bob");
75 
76participants.add(participant1);
77participants.add(participant2);
78 
79// Create thread
80CreateChatThreadOptions options = new CreateChatThreadOptions("Project Discussion")
81    .setParticipants(participants);
82 
83CreateChatThreadResult result = chatClient.createChatThread(options);
84String threadId = result.getChatThread().getId();
85 
86// Get thread client for operations
87ChatThreadClient threadClient = chatClient.getChatThreadClient(threadId);
88```
89 
90## Send Messages
91 
92```java
93// Send text message
94SendChatMessageOptions messageOptions = new SendChatMessageOptions()
95    .setContent("Hello, team!")
96    .setSenderDisplayName("Alice")
97    .setType(ChatMessageType.TEXT);
98 
99SendChatMessageResult sendResult = threadClient.sendMessage(messageOptions);
100String messageId = sendResult.getId();
101 
102// Send HTML message
103SendChatMessageOptions htmlOptions = new SendChatMessageOptions()
104    .setContent("<strong>Important:</strong> Meeting at 3pm")
105    .setType(ChatMessageType.HTML);
106 
107threadClient.sendMessage(htmlOptions);
108```
109 
110## Get Messages
111 
112```java
113import com.azure.core.util.paging.PagedIterable;
114 
115// List all messages
116PagedIterable<ChatMessage> messages = threadClient.listMessages();
117 
118for (ChatMessage message : messages) {
119    System.out.println("ID: " + message.getId());
120    System.out.println("Type: " + message.getType());
121    System.out.println("Content: " + message.getContent().getMessage());
122    System.out.println("Sender: " + message.getSenderDisplayName());
123    System.out.println("Created: " + message.getCreatedOn());
124    
125    // Check if edited or deleted
126    if (message.getEditedOn() != null) {
127        System.out.println("Edited: " + message.getEditedOn());
128    }
129    if (message.getDeletedOn() != null) {
130        System.out.println("Deleted: " + message.getDeletedOn());
131    }
132}
133 
134// Get specific message
135ChatMessage message = threadClient.getMessage(messageId);
136```
137 
138## Update and Delete Messages
139 
140```java
141// Update message
142UpdateChatMessageOptions updateOptions = new UpdateChatMessageOptions()
143    .setContent("Updated message content");
144 
145threadClient.updateMessage(messageId, updateOptions);
146 
147// Delete message
148threadClient.deleteMessage(messageId);
149```
150 
151## Manage Participants
152 
153```java
154// List participants
155PagedIterable<ChatParticipant> participants = threadClient.listParticipants();
156 
157for (ChatParticipant participant : participants) {
158    CommunicationUserIdentifier user = 
159        (CommunicationUserIdentifier) participant.getCommunicationIdentifier();
160    System.out.println("User: " + user.getId());
161    System.out.println("Display Name: " + participant.getDisplayName());
162}
163 
164// Add participants
165List<ChatParticipant> newParticipants = new ArrayList<>();
166newParticipants.add(new ChatParticipant()
167    .setCommunicationIdentifier(new CommunicationUserIdentifier("<new-user-id>"))
168    .setDisplayName("Charlie")
169    .setShareHistoryTime(OffsetDateTime.now().minusDays(7))); // Share last 7 days
170 
171threadClient.addParticipants(newParticipants);
172 
173// Remove participant
174CommunicationUserIdentifier userToRemove = new CommunicationUserIdentifier("<user-id>");
175threadClient.removeParticipant(userToRemove);
176```
177 
178## Read Receipts
179 
180```java
181// Send read receipt
182threadClient.sendReadReceipt(messageId);
183 
184// Get read receipts
185PagedIterable<ChatMessageReadReceipt> receipts = threadClient.listReadReceipts();
186 
187for (ChatMessageReadReceipt receipt : receipts) {
188    System.out.println("Message ID: " + receipt.getChatMessageId());
189    System.out.println("Read by: " + receipt.getSenderCommunicationIdentifier());
190    System.out.println("Read at: " + receipt.getReadOn());
191}
192```
193 
194## Typing Notifications
195 
196```java
197import com.azure.communication.chat.models.TypingNotificationOptions;
198 
199// Send typing notification
200TypingNotificationOptions typingOptions = new TypingNotificationOptions()
201    .setSenderDisplayName("Alice");
202 
203threadClient.sendTypingNotificationWithResponse(typingOptions, Context.NONE);
204 
205// Simple typing notification
206threadClient.sendTypingNotification();
207```
208 
209## Thread Operations
210 
211```java
212// Get thread properties
213ChatThreadProperties properties = threadClient.getProperties();
214System.out.println("Topic: " + properties.getTopic());
215System.out.println("Created: " + properties.getCreatedOn());
216 
217// Update topic
218threadClient.updateTopic("New Project Discussion Topic");
219 
220// Delete thread
221chatClient.deleteChatThread(threadId);
222```
223 
224## List Threads
225 
226```java
227// List all chat threads for the user
228PagedIterable<ChatThreadItem> threads = chatClient.listChatThreads();
229 
230for (ChatThreadItem thread : threads) {
231    System.out.println("Thread ID: " + thread.getId());
232    System.out.println("Topic: " + thread.getTopic());
233    System.out.println("Last message: " + thread.getLastMessageReceivedOn());
234}
235```
236 
237## Pagination
238 
239```java
240import com.azure.core.http.rest.PagedResponse;
241 
242// Paginate through messages
243int maxPageSize = 10;
244ListChatMessagesOptions listOptions = new ListChatMessagesOptions()
245    .setMaxPageSize(maxPageSize);
246 
247PagedIterable<ChatMessage> pagedMessages = threadClient.listMessages(listOptions);
248 
249pagedMessages.iterableByPage().forEach(page -> {
250    System.out.println("Page status code: " + page.getStatusCode());
251    page.getElements().forEach(msg -> 
252        System.out.println("Message: " + msg.getContent().getMessage()));
253});
254```
255 
256## Error Handling
257 
258```java
259import com.azure.core.exception.HttpResponseException;
260 
261try {
262    threadClient.sendMessage(messageOptions);
263} catch (HttpResponseException e) {
264    switch (e.getResponse().getStatusCode()) {
265        case 401:
266            System.out.println("Unauthorized - check token");
267            break;
268        case 403:
269            System.out.println("Forbidden - user not in thread");
270            break;
271        case 404:
272            System.out.println("Thread not found");
273            break;
274        default:
275            System.out.println("Error: " + e.getMessage());
276    }
277}
278```
279 
280## Message Types
281 
282| Type | Description |
283|------|-------------|
284| `TEXT` | Regular chat message |
285| `HTML` | HTML-formatted message |
286| `TOPIC_UPDATED` | System message - topic changed |
287| `PARTICIPANT_ADDED` | System message - participant joined |
288| `PARTICIPANT_REMOVED` | System message - participant left |
289 
290## Environment Variables
291 
292```bash
293AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
294AZURE_COMMUNICATION_USER_TOKEN=<user-access-token>
295```
296 
297## Best Practices
298 
2991. **Token Management** - User tokens expire; implement refresh logic with `CommunicationTokenRefreshOptions`
3002. **Pagination** - Use `listMessages(options)` with `maxPageSize` for large threads
3013. **Share History** - Set `shareHistoryTime` when adding participants to control message visibility
3024. **Message Types** - Filter system messages (`PARTICIPANT_ADDED`, etc.) from user messages
3035. **Read Receipts** - Send receipts only when messages are actually viewed by user
304 
305## Trigger Phrases
306 
307- "chat application Java", "real-time messaging Java"
308- "chat thread", "chat participants", "chat messages"
309- "read receipts", "typing notifications"
310- "Azure Communication Services chat"
311