Azure Communication Chat contains the APIs used in chat applications for Azure Communication Services.

Source code |Package (Maven) |API reference documentation|Product documentation

Getting started

Prerequisites

• An Azure account with an active subscription.Create an account for free.
• Java Development Kit (JDK) version 8 or above.
• Apache Maven.
• A deployed Communication Services resource. You can use theAzure Portal or theAzure PowerShell to set it up.

Include the package

Include the BOM file

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number.To learn more about the BOM, see theAZURE SDK BOM README.

<dependencyManagement>    <dependencies>        <dependency>            <groupId>com.azure</groupId>            <artifactId>azure-sdk-bom</artifactId>            <version>{bom_version_to_target}</version>            <type>pom</type>            <scope>import</scope>        </dependency>    </dependencies></dependencyManagement>

and then include the direct dependency in the dependencies section without the version tag.

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

Include direct dependency

If you want to take dependency on a particular version of the library that is not present in the BOM,add the direct dependency to your project as follows.

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

Key concepts

A chat conversation is represented by a chat thread. Each user in the chat thread is called a participant. Participants can chat with one another privately in a 1:1 chat or huddle up in a 1:N group chat.

Once you initialized aChatClient and aChatThreadClient class, you can do the following chat operations:

Create, get, list, update, and delete chat threads

Send, get, list, update, and delete chat messages

Get, add, and remove participants

Send and get read receipts

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQ or contactopencode@microsoft.com with any additional questions or comments.

Set Azure Communication Resource endpoint after it is created

endpoint = "https://Azure-Communication-Resource-Name.communications.azure.com"

Request a User Access Token

User access tokens enable you to build client applications that directly authenticate to Azure Communication Services.You generate these tokens on your server, pass them back to a client device, and then use them to initialize the Communication Services SDKs.

Learn how to generate user access tokens fromUser Access Tokens

Examples

The following sections provide several code snippets covering some of the most common tasks, including:

• Create the Chat Client
• Chat Thread Operations
• Chat Message Operations
• Chat Thread Participant Operations
• Read Receipt Operations
• Typing Notification Operations

Create the Chat Client

String endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com";// Your user access token retrieved from your trusted serviceString token = "SECRET";CommunicationTokenCredential credential = new CommunicationTokenCredential(token);// Initialize the chat clientfinal ChatClientBuilder builder = new ChatClientBuilder();builder.endpoint(endpoint)    .credential(credential);ChatClient chatClient = builder.buildClient();

Chat Thread Operations

Create a chat thread

To create a chat client, you will use the Communications Service endpoint and the access token that was generated as part of pre-requisite steps. User access tokens enable you to build client applications that directly authenticate to Azure Communication Services. Once you generate these tokens on your server, pass them back to a client device. You need to use the CommunicationTokenCredential class from the Common SDK to pass the token to your chat client.

Use thecreateChatThread method to create a chat thread.createChatThreadOptions is used to describe the thread request, an example is shown in the code snippet below.

• Usetopic to give a thread topic;
• Useparticipants to list the thread participants to be added to the thread;

CreateChatThreadResult is the response returned from creating a chat thread.It contains agetChatThread() method which returns theChatThread object that can be used to get the thread client from which you can get theChatThreadClient for performing operations on the created thread: add participants, send message, etc.TheChatThread object also contains thegetId() method which retrieves the unique ID of the thread.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();ChatParticipant firstParticipant = new ChatParticipant()    .setCommunicationIdentifier(user1)    .setDisplayName("Participant Display Name 1");ChatParticipant secondParticipant = new ChatParticipant()    .setCommunicationIdentifier(user2)    .setDisplayName("Participant Display Name 2");participants.add(firstParticipant);participants.add(secondParticipant);CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")    .setParticipants(participants);CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);String chatThreadId = result.getChatThread().getId();

Get a chat thread properties

ThegetChatThreadProperties method retrieves a thread's properties from the service.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient("Id");ChatThreadProperties chatThreadProperties = chatThreadClient.getProperties();

Delete a thread

UsedeleteChatThread method to delete a chat threadchatThreadId is the unique ID of the chat thread.

String chatThreadId = "Id";chatClient.deleteChatThread(chatThreadId);

Get a chat thread client

ThegetChatThreadClient method returns a thread client for a thread that already exists. It can be used for performing operations on the created thread: add participants, send message, etc.chatThreadId is the unique ID of the existing chat thread.

String chatThreadId = "Id";ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Update a chat thread topic

UseupdateTopic method to update a thread's topictopic is used to hold the new topic of the thread.

chatThreadClient.updateTopic("New Topic");

Chat Message Operations

Send a chat message

Use thesendMessage method to send a chat message to the chat thread that thechatThreadClient was created with.sendChatMessageOptions is used to describe the chat message request, an example is shown in the code snippet below.

• Usecontent to provide the chat message content;
• Usepriority to specify the chat message priority level, such as 'Normal' or 'High';
• UsesenderDisplayName to specify the display name of the sender;

ASendChatMessageResult response returned from sending a chat message, it contains an id, which is the unique ID of the message.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()    .setContent("Message content")    .setSenderDisplayName("Sender Display Name");SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

Get a chat message

ThegetMessage method retrieves a chat message from the service.chatMessageId is the unique ID of the chat message.

String chatMessageId = "Id";ChatMessage chatMessage = chatThreadClient.getMessage(chatMessageId);

Get chat messages

You can retrieve chat messages using thelistMessages method on the chat thread client at specified intervals (polling).

PagedIterable<ChatMessage> chatMessagesResponse = chatThreadClient.listMessages();chatMessagesResponse.iterableByPage().forEach(resp -> {    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),        resp.getRequest().getUrl(), resp.getStatusCode());    resp.getElements().forEach(message ->        System.out.printf("Message id is %s.", message.getId()));});

listMessages returns the latest version of the message, including any edits or deletes that happened to the message using.editMessage() and.deleteMessage().

For deleted messages,chatMessage.getDeletedOn() returns a datetime value indicating when that message was deleted.

For edited messages,chatMessage.getEditedOn() returns a datetime indicating when the message was edited.

The original time of message creation can be accessed usingchatMessage.getCreatedOn(), and it can be used for ordering the messages.

listMessages returns different types of messages which can be identified bychatMessage.getType(). These types are:

• text: Regular chat message sent by a thread participant.

• html: HTML chat message sent by a thread participant.

• topicUpdated: System message that indicates the topic has been updated.

• participantAdded: System message that indicates one or more participants have been added to the chat thread.

• participantRemoved: System message that indicates a participant has been removed from the chat thread.

For more details, seeMessage Types.

Update a chat message

UseupdateMessage to update a chat message identified by chatThreadId and messageId.chatMessageId is the unique ID of the chat message.updateChatMessageOptions is used to describe the request of a chat message update, an example is shown in the code snippet below.

• Usecontent to provide a new chat message content;

String chatMessageId = "Id";UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()    .setContent("Updated message content");chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

Delete a chat message

UseupdateMessage to update a chat message identified by chatMessageId.chatMessageId is the unique ID of the chat message.

String chatMessageId = "Id";chatThreadClient.deleteMessage(chatMessageId);

Chat Thread Participant Operations

List chat participants

UselistParticipants to retrieve a paged collection containing the participants of the chat thread.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();chatParticipantsResponse.iterableByPage().forEach(resp -> {    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),        resp.getRequest().getUrl(), resp.getStatusCode());    resp.getElements().forEach(chatParticipant ->        System.out.printf("Participant id is %s.", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId()));});

Add participants

UseaddParticipants method to add participants to the chat thread.participants list of participants to be added to the thread;

• communicationIdentifier, required, is the CommunicationIdentifier you've created by using the CommunicationIdentityClient. More info at:Create A User.
• display_name, optional, is the display name for the thread member.
• share_history_time, optional, is the time from which the chat history is shared with the member. To share history since the inception of the chat thread, set this property to any date equal to, or less than the thread creation time. To share no history previous to when the member was added, set it to the current date. To share partial history, set it to the required date.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();ChatParticipant firstParticipant = new ChatParticipant()    .setCommunicationIdentifier(user1)    .setDisplayName("Display Name 1");ChatParticipant secondParticipant = new ChatParticipant()    .setCommunicationIdentifier(user2)    .setDisplayName("Display Name 2");participants.add(firstParticipant);participants.add(secondParticipant);chatThreadClient.addParticipants(participants);

Remove participant

UseremoveParticipant method to remove a participant from the chat thread.identifier is the CommunicationIdentifier you've created.

chatThreadClient.removeParticipant(user);

Read Receipt Operations

Send read receipt

UsesendReadReceipt method to post a read receipt event to a chat thread, on behalf of a user.chatMessageId is the unique ID of the chat message that was read.

String chatMessageId = "Id";chatThreadClient.sendReadReceipt(chatMessageId);

Get read receipts

getReadReceipts method retrieves read receipts for a chat thread.

PagedIterable<ChatMessageReadReceipt> readReceiptsResponse = chatThreadClient.listReadReceipts();readReceiptsResponse.iterableByPage().forEach(resp -> {    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),        resp.getRequest().getUrl(), resp.getStatusCode());    resp.getElements().forEach(readReceipt ->        System.out.printf("Read message id is %s.", readReceipt.getChatMessageId()));});

Typing Notification Operations

Send typing notification

UsesendTypingNotification method to post a typing notification event to a chat thread, on behalf of a user.typingNotificationOptions is used to describe the typing notification request.

• UsesenderDisplayName to set the display name of the notification sender;

TypingNotificationOptions options = new TypingNotificationOptions();options.setSenderDisplayName("Sender Display Name");chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

Troubleshooting

In progress.

Next steps

Check out other client libraries for Azure communication service