Skip to content

Commit

Permalink
Bringing the feature branch for chat API version 2020-11-01-preview3 …
Browse files Browse the repository at this point in the history 
…to master (#18388)

Co-authored-by: Camilo Ramirez <juramir@microsoft.com>
  • Loading branch information
@juancamilor
juancamilor and Camilo Ramirez authored Feb 3, 2021
1 parent 950dcb0 commit bbf2c76
Show file tree
Hide file tree
Showing 102 changed files with 8,952 additions and 7,884 deletions.
7 changes: 7 additions & 0 deletions sdk/communication/Azure.Communication.Chat/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
# Release History

## 1.0.0-beta.4 (Unreleased)
# Breaking
- Support for CreateChatThreadResult and AddChatParticipantsResult to handle partial errors in batch calls.
- Added idempotency identifier parameter for chat creation calls.
- Added support for readreceipts and getparticipants pagination.
- Added new model for messages
- Removed priority field
- Added new model for errors


## 1.0.0-beta.3 (2020-11-16)
Expand Down
130 changes: 64 additions & 66 deletions sdk/communication/Azure.Communication.Chat/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Azure Communication Chat client library for .NET

> Server Version:
Chat client: 2020-09-21-preview2
> Server - Chat Api Version: 2020-11-01-preview3
> Client - Chat SDK Version: 1.0.0-beta.3
This package contains a C# SDK for Azure Communication Services for chat.

Expand Down Expand Up @@ -37,8 +37,6 @@ For the generation of user access tokens, refer to [User Access Tokens][useracce

### Using statements
```C# Snippet:Azure_Communication_Chat_Tests_E2E_UsingStatements
using Azure.Core;
using Azure.Communication;
using Azure.Communication.Identity;
using Azure.Communication.Chat;
```
Expand All @@ -54,19 +52,17 @@ ChatClient chatClient = new ChatClient(

### Create a ChatThreadClient

The ChatThreadClient will allow you to perform operations specific to a chat thread, like update the chat thread topic, send a message, add members to the chat thread, etc.
The ChatThreadClient will allow you to perform operations specific to a chat thread, like update the chat thread topic, send a message, add participants to the chat thread, etc.

You can instantiate a new ChatThreadClient instance using the ChatClient:

```C# Snippet:Azure_Communication_Chat_Tests_E2E_InitializeChatThreadClient
ChatThreadClient chatThreadClient1 = chatClient.CreateChatThread("Thread topic", members);
// Alternatively, if you have created a chat thread before and you have its threadId, you can create a ChatThreadClient instance using:
ChatThreadClient chatThreadClient2 = chatClient.GetChatThreadClient("threadId");
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient("threadId");
```

## Key concepts

A chat conversation is represented by a thread. Each user in the thread is called a thread member. Thread members can chat with one another privately in a 1:1 chat or huddle up in a 1:N group chat. Users also get near-real time updates for when others are typing and when they have read the messages.
A chat conversation is represented by a thread. Each user in the thread is called a thread participant. Thread participants can chat with one another privately in a 1:1 chat or huddle up in a 1:N group chat. Users also get near-real time updates for when others are typing and when they have read the messages.

Once you initialized a `ChatClient` class, you can do the following chat operations:

Expand All @@ -91,12 +87,12 @@ Once you initialized a `ChatThreadClient` class, you can do the following chat o
### Update a thread

```C# Snippet:Azure_Communication_Chat_Tests_E2E_UpdateThread
chatThreadClient.UpdateThread(topic: "Launch meeting");
chatThreadClient.UpdateTopic(topic: "Launch meeting");
```

### Send a message
```C# Snippet:Azure_Communication_Chat_Tests_E2E_SendMessage
SendChatMessageResult sendChatMessageResult = chatThreadClient.SendMessage("Let's meet at 11am");
string messageId = chatThreadClient.SendMessage("Let's meet at 11am");
```
### Update a message
```C# Snippet:Azure_Communication_Chat_Tests_E2E_UpdateMessage
Expand All @@ -114,25 +110,25 @@ Pageable<ChatMessage> messages = chatThreadClient.GetMessages();
```C# Snippet:Azure_Communication_Chat_Tests_E2E_DeleteMessage
chatThreadClient.DeleteMessage(messageId);
```
### Get a list of members
```C# Snippet:Azure_Communication_Chat_Tests_E2E_GetMembers
Pageable<ChatThreadMember> chatThreadMembers = chatThreadClient.GetMembers();
### Get a list of participants
```C# Snippet:Azure_Communication_Chat_Tests_E2E_GetParticipants
Pageable<ChatParticipant> chatParticipants = chatThreadClient.GetParticipants();
```
### Add members
```C# Snippet:Azure_Communication_Chat_Tests_E2E_AddMembers
chatThreadClient.AddMembers(members: new[] { newMember });
### Add participants
```C# Snippet:Azure_Communication_Chat_Tests_E2E_AddParticipants
chatThreadClient.AddParticipants(participants: new[] { newParticipant });
```
### Remove a member
```C# Snippet:Azure_Communication_Chat_Tests_E2E_RemoveMember
chatThreadClient.RemoveMember(user: memberToBeRemoved);
### Remove a participant
```C# Snippet:Azure_Communication_Chat_Tests_E2E_RemoveParticipant
chatThreadClient.RemoveParticipant(user: participantToBeRemoved);
```
### Send a typing notification
```C# Snippet:Azure_Communication_Chat_Tests_E2E_SendTypingNotification
chatThreadClient.SendTypingNotification();
```
### Get a list of read receipts
```C# Snippet:Azure_Communication_Chat_Tests_E2E_GetReadReceipts
Pageable<ReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();
Pageable<ChatMessageReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();
```
### Send a read receipt
```C# Snippet:Azure_Communication_Chat_Tests_E2E_SendReadReceipt
Expand All @@ -144,7 +140,7 @@ The following sections provide several code snippets covering some of the most c

- [Thread Operations](#thread-operations)
- [Message Operations](#message-operations)
- [Thread Member Operations](#thread-member-operations)
- [Thread Participant Operations](#thread-participant-operations)
- [Events Operations](#events-operations)

## Thread Operations
Expand All @@ -153,27 +149,28 @@ The following sections provide several code snippets covering some of the most c

Use `CreateChatThread` to create a chat thread client object.
- Use `topic` to give a thread topic.
- The following are the supported attributes for each thread member:
- `communicationUser`, required, it is the identification for the thread member.
- `displayName`, optional, is the display name for the thread member
- `shareHistoryTime`, optional, time from which the chat history is shared with the member.
- The following are the supported attributes for each thread participant:
- `communicationUser`, required, it is the identification for the thread participant.
- `displayName`, optional, is the display name for the thread participant
- `shareHistoryTime`, optional, time from which the chat history is shared with the participant.

`ChatThreadClient` is the result returned from creating a thread, you can use it to perform other operations on the chat thread.

**Important:** Make sure the user creating the chat thread is explicitely added to the list of members, otherwise the creation call will fail.
**Important:** Make sure the user creating the chat thread is explicitely added to the list of participants, otherwise the creation call will fail.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_CreateChatClient
ChatClient chatClient = new ChatClient(
new Uri(endpoint),
new CommunicationTokenCredential(userToken));
```
```C# Snippet:Azure_Communication_Chat_Tests_Samples_CreateThread
var chatThreadMember = new ChatThreadMember(new CommunicationUserIdentifier(threadCreatorId))
var chatParticipant = new ChatParticipant(threadCreator)
{
DisplayName = "UserDisplayName"
};
ChatThreadClient chatThreadClient = await chatClient.CreateChatThreadAsync(topic: "Hello world!", members: new[] { chatThreadMember });
string threadId = chatThreadClient.Id;
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
string threadId = createChatThreadResult.ChatThread.Id;
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId);
```
### Get a thread

Expand All @@ -184,9 +181,9 @@ Use `GetChatThread` to retrieve a chat thread from the service.
ChatThread chatThread = await chatClient.GetChatThreadAsync(threadId);
```

### Get threads (for a member)
### Get threads (for a participant)

Use `GetChatThreadsInfo` to get the list of chat threads for the member that instantiated the chatClient.
Use `GetChatThreadsInfo` to get the list of chat threads for the participant that instantiated the chatClient.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_GetThreads
AsyncPageable<ChatThreadInfo> chatThreadsInfo = chatClient.GetChatThreadsInfoAsync();
Expand All @@ -207,12 +204,12 @@ await chatClient.DeleteChatThreadAsync(threadId);

### Update a thread

Use `UpdateChatThread` to update the chat thread properties.
Use `UpdateTopic` to update the chat thread topic.
- `topic` is used to describe the updated topic for the thread.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_UpdateThread
var topic = "new topic";
await chatThreadClient.UpdateThreadAsync(topic);
await chatThreadClient.UpdateTopicAsync(topic);
```

## Message Operations
Expand All @@ -229,9 +226,9 @@ Use `SendMessage` to send a message to a thread.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_SendMessage
var content = "hello world";
var priority = ChatMessagePriority.Normal;
var type = ChatMessageType.Html;
var senderDisplayName = "sender name";
SendChatMessageResult sendMessageResult = await chatThreadClient.SendMessageAsync(content, priority, senderDisplayName);
var messageId = await chatThreadClient.SendMessageAsync(content, type, senderDisplayName);
```
### Get a message

Expand All @@ -251,7 +248,7 @@ Use `GetMessages` to retrieve all messages for the chat thread.
AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
Console.WriteLine($"{message.Id}:{message.Sender.Id}:{message.Content}");
Console.WriteLine($"{message.Id}:{message.Content}");
}
```
### Update a message
Expand All @@ -272,43 +269,44 @@ Use `DeleteMessage` to delete a message.
await chatThreadClient.DeleteMessageAsync(messageId);
```

## Thread Member Operations
## Thread Participant Operations

### Get thread members
### Get thread participants

Use `GetMembers` to retrieve the members of the chat thread.
Use `GetParticipants` to retrieve the participants of the chat thread.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_GetMembers
AsyncPageable<ChatThreadMember> allMembers = chatThreadClient.GetMembersAsync();
await foreach (ChatThreadMember member in allMembers)
```C# Snippet:Azure_Communication_Chat_Tests_Samples_GetParticipants
AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
Console.WriteLine($"{member.User.Id}:{member.DisplayName}:{member.ShareHistoryTime}");
Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}
```
### Add thread members
### Add thread participants

Use `AddMembers` to add members to the chat thread. The following are the supported attributes for each thread member:
- `communicationUser`, required, it is the identification for the thread member.
- `displayName`, optional, is the display name for the thread member.
- `shareHistoryTime`, optional, time from which the chat history is shared with the member.
Use `AddParticipants` to add one or more participants to the chat thread. The following are the supported attributes for each thread participant(s):
- `communicationUser`, required, it is the identification for the thread participant.
- `displayName`, optional, is the display name for the thread participant.
- `shareHistoryTime`, optional, time from which the chat history is shared with the participant.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_AddMembers
var members = new[]
```C# Snippet:Azure_Communication_Chat_Tests_Samples_AddParticipants
var participants = new[]
{
new ChatThreadMember(new CommunicationUserIdentifier(memberId1)) { DisplayName ="display name member 1"},
new ChatThreadMember(new CommunicationUserIdentifier(memberId2)) { DisplayName ="display name member 2"},
new ChatThreadMember(new CommunicationUserIdentifier(memberId3)) { DisplayName ="display name member 3"}
new ChatParticipant(josh) { DisplayName = "Josh" },
new ChatParticipant(gloria) { DisplayName = "Gloria" },
new ChatParticipant(amy) { DisplayName = "Amy" }
};
await chatThreadClient.AddMembersAsync(members);

await chatThreadClient.AddParticipantsAsync(participants);
```

### Remove thread member
### Remove thread participant

Use `RemoveMember` to remove a thread member from the thread.
`communicationUser` is the identification of the chat member.
Use `RemoveParticipant` to remove a thread participant from the thread.
`communicationUser` is the identification of the chat participant.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_RemoveMember
await chatThreadClient.RemoveMemberAsync(new CommunicationUserIdentifier(memberId));
```C# Snippet:Azure_Communication_Chat_Tests_Samples_RemoveParticipant
await chatThreadClient.RemoveParticipantAsync(gloria);
```

## Events Operations
Expand All @@ -323,21 +321,21 @@ await chatThreadClient.SendTypingNotificationAsync();

### Send read receipt

Use `SendReadReceipt` to notify other members that the message is read by the user.
Use `SendReadReceipt` to notify other participants that the message is read by the user.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_SendReadReceipt
await chatThreadClient.SendReadReceiptAsync(messageId);
```

### Get read receipts

Use `GetReadReceipts` to check the status of messages to see which ones are read by other members of a chat thread.
Use `GetReadReceipts` to check the status of messages to see which ones are read by other participants of a chat thread.

```C# Snippet:Azure_Communication_Chat_Tests_Samples_GetReadReceipts
AsyncPageable<ReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ReadReceipt readReceipt in allReadReceipts)
AsyncPageable<ChatMessageReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ChatMessageReadReceipt readReceipt in allReadReceipts)
{
Console.WriteLine($"{readReceipt.ChatMessageId}:{readReceipt.Sender.Id}:{readReceipt.ReadOn}");
Console.WriteLine($"{readReceipt.ChatMessageId}:{((CommunicationUserIdentifier)readReceipt.Sender).Id}:{readReceipt.ReadOn}");
}
```

Expand All @@ -347,7 +345,7 @@ A `RequestFailedException` is thrown as a service response for any unsuccessful
```C# Snippet:Azure_Communication_Chat_Tests_Samples_Troubleshooting
try
{
ChatThreadClient chatThreadClient_ = await chatClient.CreateChatThreadAsync(topic: "Hello world!", members: new[] { chatThreadMember });
CreateChatThreadResult createChatThreadErrorResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { josh });
}
catch (RequestFailedException ex)
{
Expand Down
Loading

0 comments on commit bbf2c76

Please sign in to comment.