Миграция из чата бесед Twilio в Службы коммуникации Azure

Необходимые компоненты

• Учетная запись Azure. Убедитесь, что ваша учетная запись Azure активна. Новые пользователи могут создать бесплатную учетную запись в Microsoft Azure.
• Node.js 18. Убедитесь, что в системе установлена Node.js 18. Скачайте из Node.js.
• Ресурс служб коммуникации. Настройте ресурс служб коммуникации через портал Azure и запишите строка подключения.
• Azure CLI. Следуйте инструкциям по установке Azure CLI в Windows.
• Маркер доступа пользователей: создайте маркер доступа пользователя для создания экземпляра клиента чата. Вы можете создать его с помощью Azure CLI следующим образом:

az communication identity token issue --scope voip --connection-string "yourConnectionString"

Дополнительные сведения см. в статье "Использование Azure CLI для создания маркеров доступа и управления ими".

Установка

Установка пакета SDK для чата Службы коммуникации Azure

npm install Используйте команду для установки пакета SDK Службы коммуникации Azure для JavaScript.

npm install @azure/communication-chat --save

Параметр --save добавляет библиотеку как зависимость в файле пакета package.json.

Удаление пакета SDK Twilio из проекта

Вы можете удалить пакет SDK Twilio из проекта, удалив пакет.

npm uninstall twilio-conversations

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации для JavaScript.

Имя	Описание
ChatClient	Этот класс необходим для функции Чата. Создайте экземпляр с информацией о подписке и используйте ее для создания, получения, удаления потоков и подписки на события чата.
ChatThreadClient	Этот класс необходим для функции "Поток чата". Получите экземпляр с помощью приложения ChatClientи используйте его для отправки и получения, обновления и удаления сообщений, добавления и удаления и получения пользователей, отправки уведомлений о вводе и чтения.

Инициализация клиента чата

Twilio

/* Initialization */
import { Client } from '@twilio/conversations';

const token = await fetch(token_url);
const client = new Client(token);
client.on('stateChanged', (state) => {
  if (state === 'failed') {
    // The client failed to initialize
    return;
  }

  if (state === 'initialized') {
    // Use the client
  }
});

Службы коммуникации Azure

Как и Twilio, первым шагом является получение маркера доступа и конечной точки службы коммуникации, созданной в рамках необходимых действий. Замените заполнители в коде.

import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');

Запуск потока чата

Twilio

Запустите поток чата в беседах Twilio. Используется FriendlyName для предоставления удобочитаемого человека имени этой беседе.

let conversation = await client.createConversation({
    friendlyName: "Testing Chat"
});
await conversation.join();

Службы коммуникации Azure

Для создания потока чата используйте метод createThread.

Используется createThreadRequest для описания запроса потока:

• Используйте topic для указания темы этого чата. обновите после topic создания потока чата UpdateThread с помощью функции.
• Используйте participants, чтобы получить список участников, добавляемых в поток чата.

При разрешении метода createChatThread возвращается CreateChatThreadResult. Эта модель содержит свойство chatThread, в котором можно получить доступ к id только что созданного потока. Затем используйте его id для получения экземпляра ChatThreadClient. Затем используйте операцию в потоке ChatThreadClient , например отправку сообщений или перечисление участников.

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

Получение клиента потока чата

Twilio

Получение потока чата (беседы) в Twilio.

if (selectedConversation) {
      conversationContent = (
        <Conversation
          conversationProxy={selectedConversation}
          myIdentity={this.state.name}
        />
      );
    } else if (status !== "success") {
      conversationContent = "Loading your conversation!";
    } else {
      conversationContent = "";
    }

Службы коммуникации Azure

Метод getChatThreadClient возвращает chatThreadClient для потока, который уже существует. Используйте его для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д. Это threadId уникальный идентификатор существующего потока чата.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

Добавьте этот код вместо комментария в <CREATE CHAT THREAD CLIENT>client.js, обновите вкладку браузера и проверьте консоль. Должно отображаться следующее:

Chat Thread client for threadId: <threadId>

Добавление пользователя в качестве участника в поток чата

После создания потока чата можно добавить и удалить пользователей из него. Добавив пользователей, вы предоставляете им доступ для отправки сообщений в поток чата и добавления и удаления других участников.

Twilio

Добавьте участника в поток чата.

// add chat participant to the conversation by its identity
await conversation.add('identity');

// adds yourself as a conversations sdk user to this conversation
// use after creating the conversation from the SDK
await conversation.join();

conversation.on('participantJoined', (participant) => {
  // fired when a participant has joined the conversation
});

Службы коммуникации Azure

Перед вызовом addParticipants метода обязательно приобретите новый маркер доступа и удостоверение для этого пользователя. Пользователю требуется маркер доступа для инициализации клиента чата.

addParticipantsRequest описывает объект запроса, в котором participants перечислены участники, которые нужно добавить в поток чата:

• id (требуется) — это идентификатор обмена данными, который должен быть добавлен в поток чата.
• displayName (необязательно) — это отображаемое имя для участника потока.
• shareHistoryTime (необязательно) — это время, в течение которого участнику предоставляется доступ к журналу чата. Чтобы предоставить общий доступ к журналу с момента запуска потока чата, установите для этого свойства любую дату, равную или меньше времени создания потока. Чтобы в журнале отображались только записи с момента добавления участника, задайте для свойства текущую дату. Чтобы предоставить общий доступ к части журнала, задайте для него дату по своему усмотрению.

const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

Замените NEW_PARTICIPANT_USER_ID новым идентификатором пользователя

Отправка сообщения в поток чата

В отличие от Twilio, Службы коммуникации Azure не имеет отдельных функций для отправки текстовых сообщений или мультимедиа.

Twilio

Отправка текстового сообщения в Twilio.

// Send Text Message
await conversation
  .prepareMessage()
  .setBody('Hello!')
  .setAttributes({foo: 'bar'})
  .build()
  .send();

Отправка мультимедиа в Twilio.

 const file =
  await fetch("https://v.fastcdn.co/u/ed1a9b17/52533501-0-logo.svg");
const fileBlob = await file.blob();
// Send a media message
const sendMediaOptions = {
    contentType: file.headers.get("Content-Type"),
    filename: "twilio-logo.svg",
    media: fileBlob
};

await conversation
  .prepareMessage()
  .setBody('Here is some media!')
  .addMedia(sendMediaOptions);

Службы коммуникации Azure

Используйте метод sendMessage для отправки сообщения в поток, идентифицируемый с помощью threadId.

sendMessageRequest используется для описания запроса сообщения:

• Используйте content, чтобы указать содержимое сообщения в чате.

Используется sendMessageOptions для описания необязательных парам операций:

• Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
• Используется type для указания типа сообщения, например text или html.

Создание свойства Media в Twilio.

• Используйте metadata необязательно, чтобы включить любые другие данные, которые вы хотите отправить вместе с сообщением. Это поле позволяет разработчикам расширить функцию сообщения чата и добавить пользовательские сведения для вашего варианта использования. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment: true в метаданные, чтобы приложение получателя могло проанализировать их и отобразить соответствующим образом. Дополнительные сведения см. в разделе "Общий доступ к файлам".

SendChatMessageResult — это ответ, возвращенный в результате отправки сообщения. Он содержит уникальный идентификатор сообщения.

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

Получение сообщений из потока чата

В отличие от Twilio, Службы коммуникации Azure не имеет отдельных функций для получения текстовых сообщений или мультимедиа. Службы коммуникации Azure использует Сетка событий Azure для обработки событий. Дополнительные сведения см. в разделе "Обработка событий".

Twilio

Получение текстового сообщения в Twilio.

// Receive text message
 let paginator =
  await conversation.getMessages(
    30,0,"backwards"
  );

const messages = paginator.items;

Получение мультимедиа в Twilio.

// Receive media
// Return all media attachments (possibly empty array), without temporary urls
const media = message.attachedMedia;

// Get a temporary URL for the first media returned by the previous method
const mediaUrl = await media[0].getContentTemporaryUrl();

Службы коммуникации Azure

С помощью оповещений в реальном времени можно подписываться на прослушивание новых входящих сообщений и обновлять текущие сообщения в памяти соответствующим образом. Службы коммуникации Azure поддерживают список событий, на которые можно подписываться.

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

Кроме того, можно получать сообщения чата, выполняя опрос метода listMessages через определенные интервалы.

const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

listMessagesвозвращает различные типы сообщений, которые можно определить.chatMessage.type

Дополнительные сведения см. в разделе "Типы сообщений".

Подписка на состояние подключения уведомлений в режиме реального времени

Аналогично Twilio, Службы коммуникации Azure позволяет подписаться на уведомления о событиях.

Подписка на события realTimeNotificationConnected и realTimeNotificationDisconnected позволяет узнать, когда подключение к серверу вызова активно.

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

Необходимые компоненты

• Создайте учетную запись Azure с активной подпиской. Дополнительные сведения см. в статье "Создание учетной записи бесплатно".

• Установить Visual Studio.

• Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в кратком руководстве по созданию ресурсов Служб коммуникации и управлению ими. Запишите конечную точку ресурса и строка подключения.

• Маркер доступа пользователя. Не забудьте задать область чата и запишите строку токена и user_id строку. Вы также можете использовать Azure CLI и выполнить следующую команду с строка подключения для создания пользователя и маркера доступа.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Дополнительные сведения см. в статье "Использование Azure CLI для создания маркеров доступа и управления ими".

Концептуальное различие

Беседы Twilio и Службы коммуникации Azure Чат предлагают аналогичные функции, но их реализация отличается из-за окружающих экосистем и базовых философий платформы. Беседы Twilio предоставляют API обмена данными с несколькими каналами. Службы коммуникации Azure чат ориентирован в основном на чат в экосистеме Azure. Это руководство по миграции предоставляет базовое сопоставление общих операций в Twilio и их эквивалентов в Службы коммуникации Azure чате, помогая вам перенести код .NET.

Удостоверения

Twilio

Беседы Twilio используют строки удостоверений напрямую.

Службы коммуникации Azure

Службы коммуникации Azure требует создания пользователей CommunicationIdentityClientс помощью .

Установка

Установка пакета

Чтобы начать миграцию из чата Twilio Conversations, сначала необходимо установить пакет SDK для чата Службы коммуникации Azure для .NET в проект.

dotnet add package Azure.Communication.Chat

Объектная модель

Указанные ниже классы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для C#.

Имя	Описание
ChatClient	Этот класс требуется для реализации всех функций чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatThreadClient	Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения участников, а также для отправки уведомлений о вводе и уведомления о прочтении.

Создание клиента чата

Twilio

Twilio требует настройки клиента Twilio с помощью учетных данных учетной записи:

var twilio = new TwilioRestClient(accountSid, authToken);

Службы коммуникации Azure

Чтобы создать клиент чата в Службы коммуникации Azure, используйте конечную точку Служб коммуникации и маркер доступа, созданный в рамках необходимых действий. Чтобы создать пользователя и выдать маркер для передачи клиенту чата, необходимо использовать класс CommunicationIdentityClient из пакета SDK для удостоверений.

Дополнительные сведения о маркерах доступа пользователей см. здесь.

// Your unique Azure Communication service endpoint
Uri endpoint = new Uri("<replace with your resource endpoint>");
CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);

Запуск потока чата

Беседы Twilio

var conversation = ConversationResource.Create(
    friendlyName: "My Conversation",
    messagingServiceSid: "<MessagingServiceSid>"
);

Службы коммуникации Azure

В Службы коммуникации Azure создается поток, эквивалентный беседе в Twilio.

Чтобы создать поток чата createChatThread , используйте метод в чатеClient:

• Используйте topic для предоставления раздела этому чату; вы можете обновить topic после создания потока чата UpdateTopic с помощью функции.
• Используйте свойство participants для передачи списка объектов ChatParticipant, добавляемых в поток чата. Инициализация ChatParticipantCommunicationIdentifier объекта с помощью объекта. CommunicationIdentifier может быть типом CommunicationUserIdentifier, MicrosoftTeamsUserIdentifierили PhoneNumberIdentifier. Например, чтобы получить CommunicationIdentifier объект, необходимо передать идентификатор доступа, созданный после инструкций по созданию пользователя.

Объект ответа из метода createChatThread содержит подробные сведения о chatThread. Чтобы взаимодействовать с операциями потока чата, такими как добавление участников, отправка сообщения, удаление сообщения и т. д., создание chatThreadClient экземпляра клиента с помощью GetChatThreadClient метода на клиенте ChatClient .

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Получение клиента потока чата

Twilio

В беседах Twilio вы взаимодействуете непосредственно с беседой с помощью идентификатора безопасности беседы (уникальный идентификатор). Вот как обычно получить беседу и взаимодействовать с ней:

var conversationSid = "<CONVERSATION_SID>";
var conversation = ConversationResource.Fetch(pathSid: conversationSid);

// Example: Fetching all messages in the conversation
var messages = MessageResource.Read(pathConversationSid: conversationSid);
foreach (var message in messages)
{
    Console.WriteLine(message.Body);
}

Службы коммуникации Azure

Метод GetChatThreadClient возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д. threadId — это уникальный идентификатор существующей беседы чата.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Перечисление всех потоков чата

Twilio

В беседах Twilio можно получить все беседы, которые пользователь является участником, запрашивая UserConversations ресурс. Этот ресурс предоставляет список бесед для конкретного пользователя.

/ Initialize Twilio Client
string accountSid = "<YOUR_ACCOUNT_SID>";
string authToken = "<YOUR_AUTH_TOKEN>";
TwilioClient.Init(accountSid, authToken);

// The identity of the user you're querying
string userIdentity = "[email protected]";

// Retrieve all conversations the user is part of
var userConversations = UserConversationResource.Read(pathUserSid: userIdentity);

foreach (var userConversation in userConversations)
{
    Console.WriteLine($"Conversation SID: {userConversation.ConversationSid}");
    // You can fetch more details about the conversation if needed
    var conversation = Twilio.Rest.Conversations.V1.ConversationResource.Fetch(pathSid: userConversation.ConversationSid);
    Console.WriteLine($"Conversation Friendly Name: {conversation.FriendlyName}");
}

Службы коммуникации Azure

Чтобы получить все потоки чата, в которых участвует пользователь, используйте GetChatThreads.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Отправка сообщения в поток чата

Twilio

В следующем фрагменте кода показано, как отправить текстовое сообщение.

var message = MessageResource.Create(
    body: "Hello, world!",
    from: "[email protected]",
    pathConversationSid: conversation.Sid
);

В следующем фрагменте кода показано, как отправить файл мультимедиа.

// The SID of the conversation you want to send the media message to
string conversationSid = "<CONVERSATION_SID>";

// The URL of the media file you want to send
var mediaUrl = new List<Uri>
{
    new Uri("https://example.com/path/to/media/file.jpg") // Replace with your actual media URL
};

// Send the media message
var message = MessageResource.Create(
    body: "Here is an image for you!",
    from: "[email protected]", // Sender's identity (optional)
    mediaUrl: mediaUrl,
    pathConversationSid: conversationSid
);

Службы коммуникации Azure

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для отправки текстовых сообщений или мультимедиа.

Для отправки сообщения в поток используйте SendMessage.

• Используйте content, обязательно, чтобы указать содержимое сообщения.
• Используется type для типа контента сообщения, например Text или Html. Если тип не указан, по умолчанию используется вариант Text.
• Используйте senderDisplayName, чтобы указать отображаемое имя отправителя. Если значение не указано, пустая строка по умолчанию.
• Используйте metadata необязательно, чтобы включить другие данные, которые вы хотите отправить вместе с сообщением. Это поле предоставляет механизм для разработчиков для расширения функции сообщения чата и добавления пользовательских сведений для вашего варианта использования. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment:true в метаданные, чтобы приложение получателя могло проанализировать это и отобразить соответствующим образом.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Получение сообщений из потока чата

Twilio

Twilio обычно использует веб-перехватчики для уведомления сервера входящих сообщений:

В следующем фрагменте кода показано, как получить текстовое сообщение.

public IActionResult ReceiveMessage()
{
    var incomingMessage = Request.Form["Body"];
    // Process the incoming message
    return Ok();
}

В следующем фрагменте кода показано, как получить файл мультимедиа.

 for (var i = 0; i < numMedia; i++)
            {
                var mediaUrl = Request.Form[$"MediaUrl{i}"];
                Trace.WriteLine(mediaUrl);
                var contentType = Request.Form[$"MediaContentType{i}"];

                var filePath = GetMediaFileName(mediaUrl, contentType);
                await DownloadUrlToFileAsync(mediaUrl, filePath);
            }

Службы коммуникации Azure

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для получения текстовых сообщений или мультимедиа.

Службы коммуникации Azure чат позволяет подписаться на события непосредственно в приложении.

Вы можете получать сообщения чата, выполняя опрос метода GetMessages на клиенте потока чата через определенные интервалы.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages принимает необязательный параметр DateTimeOffset. Если это смещение указано, вы получаете сообщения, полученные, обновленные или удаленные после него. Сообщения, полученные до времени смещения, но изменены или удалены после возврата.

GetMessages возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью UpdateMessage и DeleteMessage. Для удаленных сообщений chatMessage.DeletedOn возвращает значение даты и времени, указывающее, когда это сообщение было удалено. Для измененных сообщений chatMessage.EditedOn возвращает значение даты и времени, указывающее, когда это сообщение было изменено. Вы можете получить доступ к исходному времени создания сообщения и chatMessage.CreatedOnиспользовать его для упорядочивания сообщений.

GetMessagesвозвращает различные типы сообщений, которые можно определить.chatMessage.Type Это следующие типы:

• Text: регулярное сообщение чата, отправленное членом потока.

• Html: форматированное текстовое сообщение. Обратите внимание, что пользователи служб коммуникации в настоящее время не могут отправлять RichText сообщения. Этот тип сообщений поддерживается в сообщениях, отправленных от пользователей Teams пользователям Служб коммуникации в сценариях взаимодействия с Teams.

• TopicUpdated: системное сообщение, указывающее, что раздел обновлен. (только чтение)

• ParticipantAdded: системное сообщение, указывающее, что один или несколько участников были добавлены в поток чата. (только чтение)

• ParticipantRemoved: системное сообщение, указывающее, что участник был удален из потока чата.

Дополнительные сведения см. в разделе "Типы сообщений".

Добавление пользователя в качестве участника в поток чата

Twilio

var participant = ParticipantResource.Create(
    pathConversationSid: conversation.Sid,
    identity: "[email protected]"
);

Службы коммуникации Azure

В Службы коммуникации Azure вы добавляете участников при создании потока чата или после этого:

После создания потока можно добавить и удалить пользователей. Добавление пользователей предоставляет им доступ к отправке сообщений в поток и добавление и удаление других участников. Перед вызовом AddParticipantsубедитесь, что вы получаете новый маркер доступа и удостоверение для этого пользователя. Пользователю нужен маркер доступа для инициализации клиента чата.

Используйте AddParticipants для добавления одного или нескольких участников в поток чата. Ниже приведены поддерживаемые атрибуты для каждого участника потока:

• communicationUser (обязательно) — это идентификатор участника потока.
• displayName (необязательно) — это отображаемое имя для участника потока.
• shareHistoryTime (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.

var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Получение участников потока

Twilio

В беседах Twilio используется ConversationResource для извлечения участников определенной беседы. Затем вы можете перечислить всех участников, связанных с этой беседой.

// The SID of the conversation you want to retrieve participants from
string conversationSid = "<CONVERSATION_SID>";

// Retrieve all participants in the conversation
var participants = ParticipantResource.Read(pathConversationSid: conversationSid);

// Output details of each participant
foreach (var participant in participants)
{
    Console.WriteLine($"Participant SID: {participant.Sid}");
            
}

Службы коммуникации Azure

Используйте GetParticipants для получения участников потока чата.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Отправка уведомления о прочтении

Twilio

// Find your Account SID and Auth Token at twilio.com/console
        // and set the environment variables. See http://twil.io/secure
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

        TwilioClient.Init(accountSid, authToken);

        var message = await MessageResource.FetchAsync(
            pathConversationSid: "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            pathSid: "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");

        Console.WriteLine(message.Delivery);
    }

Службы коммуникации Azure

Используйте SendReadReceipt для уведомления других участников о том, что пользователь прочитал сообщение.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Необходимые компоненты

• Учетная запись Azure. Убедитесь, что ваша учетная запись Azure активна. Новые пользователи могут создать бесплатную учетную запись в Microsoft Azure.
• Ресурс служб коммуникации. Настройте ресурс служб коммуникации через портал Azure и запишите строка подключения.
• Azure CLI. Следуйте инструкциям по установке Azure CLI в Windows.
• Маркер доступа пользователей: создайте маркер доступа пользователя для создания экземпляра клиента вызова. Вы можете создать его с помощью Azure CLI следующим образом:

az communication identity token issue --scope voip --connection-string "yourConnectionString"

Дополнительные сведения см. в статье "Использование Azure CLI для создания маркеров доступа и управления ими".

Установка

Установка библиотек

Чтобы начать миграцию из чата бесед Twilio, сначала необходимо установить пакет SDK для чата Службы коммуникации Azure для iOS в проект. Эти параметры можно настроить с помощью CocoaPods.

1. Создайте podfile для приложения. Откройте терминал, перейдите в папку проекта и выполните следующую команду:

pod init

2. Добавьте следующий код в Podfile и сохраните (убедитесь, что "target" соответствует имени проекта):

pod 'AzureCommunicationChat', '~> 1.3.5'

3. .xcworkspace Настройте проект:

pod install

4. .xcworkspace Откройте созданный модулем pod с помощью Xcode.

Проверка подлинности в пакете SDK

Чтобы использовать пакет SDK для чата Службы коммуникации Azure, необходимо пройти проверку подлинности с помощью маркера доступа.

Twilio

Следующие фрагменты кода предполагают доступность допустимого маркера доступа для служб Twilio.

static func getTokenUrlFromDefaults(identity: String, password: String) -> URL? {
        // Get token service absolute URL from settings
        guard let tokenServiceUrl = UserDefaults.standard.string(forKey: "ACCESS_TOKEN_SERVICE_URL"), !tokenServiceUrl.isEmpty else {
            return nil
        }
        return constructLoginUrl(tokenServiceUrl, identity: identity, password: password)
    }

Службы коммуникации Azure

Следующие фрагменты кода требуют допустимого маркера доступа для запуска CallClient.

Вам нужен допустимый маркер. Дополнительные сведения см. в разделе "Создание маркеров доступа и управление ими".

// Create an instance of CallClient 
let callClient = CallClient() 
 
// A reference to the call agent, it will be initialized later 
var callAgent: CallAgent? 
 
// Embed the token in a CommunicationTokenCredential object 
let userCredential = try? CommunicationTokenCredential(token: "<USER_TOKEN>") 
 
// Create a CallAgent that will be used later to initiate or receive calls 
callClient.createCallAgent(userCredential: userCredential) { callAgent, error in 
 if error != nil { 
        // Raise the error to the user and return 
 } 
 self.callAgent = callAgent         
} 

Инициализация клиента чата

Twilio

Следующий фрагмент кода инициализирует клиент чата в Twilio.

func fetchAccessTokenAndInitializeClient() {
        let identity = "user_identity" // Replace with actual user identity
        let urlString = "http://localhost:3000/token?identity=\(identity)"
        
        guard let url = URL(string: urlString) else { return }
        
        let task = URLSession.shared.dataTask(with: url) { data, response, error in
            guard let data = data, error == nil else {
                print("Error fetching token: \(String(describing: error))")
                return
            }
            
            do {
                if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
                   let token = json["token"] as? String {
                    self.initializeConversationsClient(withToken: token)
                }
            } catch {
                print("Error parsing token JSON: \(error)")
            }
        }
        
        task.resume()
    }
```m = TwilioVideoSDK.connect(options: connectOptions, delegate: self)

Службы коммуникации Azure

Чтобы создать клиент чата, используйте конечную точку служб коммуникации и маркер доступа, созданный в рамках необходимых действий.

Замените <ACS_RESOURCE_ENDPOINT> значением конечной точки для ресурса Служб коммуникации Azure. Замените <ACCESS_TOKEN> допустимым маркером доступа Служб коммуникации.

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для iOS.

Имя	Описание
ChatClient	Этот класс необходим для функции чата. Его экземпляр можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков, а также для подписки на события чата.
ChatThreadClient	Этот класс необходим для функции потока чата. Вы получаете экземпляр с помощью ChatClientи используете его для отправки, получения, обновления и удаления сообщений. Вы также можете использовать его для добавления, удаления, получения пользователей и отправки уведомлений о вводе и чтения квитанций.

Запуск потока чата

Twilio

Следующий фрагмент кода позволяет создать новый поток чата.

    // the unique name of the conversation you create
    private let uniqueConversationName = "general"

    // For the quickstart, this will be the view controller
    weak var delegate: QuickstartConversationsManagerDelegate?

    // MARK: Conversations variables
    private var client: TwilioConversationsClient?
    private var conversation: TCHConversation?
    private(set) var messages: [TCHMessage] = []
    private var identity: String?

    func conversationsClient(_ client: TwilioConversationsClient, synchronizationStatusUpdated status: TCHClientSynchronizationStatus) {
        guard status == .completed else {
            return
        }

        checkConversationCreation { (_, conversation) in
           if let conversation = conversation {
               self.joinConversation(conversation)
           } else {
               self.createConversation { (success, conversation) in
                   if success, let conversation = conversation {
                       self.joinConversation(conversation)
                   }
               }
           }
        }

Службы коммуникации Azure

Ответ, возвращаемый при создании потока чата, — это CreateChatThreadResult. Он содержит chatThread свойство, которое является ChatThreadProperties объектом. Этот объект содержит threadIdобъект, который можно использовать ChatThreadClient для выполнения операций в созданном потоке: добавление участников, отправка сообщения и т. д.

Замените комментарий <CREATE A CHAT THREAD> следующим фрагментом кода:

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

Замените <USER_ID> допустимым идентификатором пользователя Служб коммуникации.

Здесь нужно настроить семафор, чтобы продолжать работу только после сигнала завершающего обработчика. В последующих шагах используйте threadId ответ, возвращенный обработчику завершения.

Получение клиента потока чата

Twilio

В следующем фрагменте кода показано, как получить клиент потока чата в Twilio.

func conversationsClient(_ client: TwilioConversationsClient, synchronizationStatusUpdated status: TCHClientSynchronizationStatus) {
        guard status == .completed else {
            return
        }

        checkConversationCreation { (_, conversation) in
           if let conversation = conversation {
               self.joinConversation(conversation)
           } else {
               self.createConversation { (success, conversation) in
                   if success, let conversation = conversation {
                       self.joinConversation(conversation)
                   }
               }
           }
        }
    }

Службы коммуникации Azure

Метод createClient возвращает ChatThreadClient для потока, который уже существует. Его можно использовать для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д.

Это threadId уникальный идентификатор существующего потока чата.

Замените комментарий <GET A CHAT THREAD CLIENT> следующим фрагментом кода:

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

Отправка сообщения в поток чата

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для отправки текстового сообщения или носителя.

Twilio

Отправка обычного текстового сообщения в Twilio.

    func sendMessage(_ messageText: String,
                     completion: @escaping (TCHResult, TCHMessage?) -> Void) {

        let messageOptions = TCHMessageOptions().withBody(messageText)
        conversation?.sendMessage(with: messageOptions, completion: { (result, message) in
            completion(result, message)
        })

    }

Отправка мультимедиа в Twilio:

/ The data for the image you would like to send
let data = Data()

// Prepare the message and send it
self.conversation.prepareMessage
    .addMedia(data: data, contentType: "image/jpeg", filename: "image.jpg", listener: .init(onStarted: {
        // Called when upload of media begins.
        print("Media upload started")
    }, onProgress: { bytes in
        // Called as upload progresses, with the current byte count.
        print("Media upload progress: \(bytes)")
    }, onCompleted: { sid in
        // Called when upload is completed, with the new mediaSid if successful.
        // Full failure details will be provided through sendMessage's completion.
        print("Media upload completed")
    }, onFailed: { error in
        // Called when upload is completed, with the new mediaSid if successful.
        // Full failure details will be provided through sendMessage's completion.
        print("Media upload failed with error: \(error)")
    }))
    .buildAndSend { result, message in
        if !result.isSuccessful {
            print("Creation failed: \(String(describing: result.error))")
        } else {
            print("Creation successful")
        }
    }

Службы коммуникации Azure

send Используйте метод для отправки сообщения в поток, определенный с помощью threadIdметода.

Используется SendChatMessageRequest для описания запроса на сообщение:

• Используйте content, чтобы указать содержимое сообщения в чате.
• Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
• Используется type для указания типа сообщения, например text или html.
• Используйте metadata необязательно, чтобы включить любые сведения, которые вы хотите отправить вместе с сообщением. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment:true в метаданные, чтобы приложение получателя могло проанализировать их и отобразить соответствующим образом.

Ответ, возвращаемый от отправки сообщения, имеет значениеSendChatMessageResult. Он содержит уникальный идентификатор сообщения.

Замените комментарий <SEND A MESSAGE> следующим фрагментом кода:

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

Получение сообщений из потока чата

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для получения текстового сообщения или носителя.

Twilio

В следующем фрагменте кода показано, как получить текстовое сообщение в Twilio.

// Called whenever a conversation we've joined receives a new message
    func conversationsClient(_ client: TwilioConversationsClient, conversation: TCHConversation,
                    messageAdded message: TCHMessage) {
        messages.append(message)

        // Changes to the delegate should occur on the UI thread
        DispatchQueue.main.async {
            if let delegate = self.delegate {
                delegate.reloadMessages()
                delegate.receivedNewMessage()
            }
        }
    }

Получение мультимедиа в Twilio:

conversationsClient.getTemporaryContentUrlsForMedia(message.attachedMedia) { result, mediaSidToUrlMap in
    guard result.isSuccessful else {
        print("Couldn't get temporary urls with error: \(String(describing: result.error))")
        return
    }

    for (sid, url) in sidToUrlMap {
        print("\(sid) -> \(url)")
    }
}

Службы коммуникации Azure

С помощью оповещений в реальном времени можно подписываться на прослушивание новых входящих сообщений и обновлять текущие сообщения в памяти соответствующим образом. Службы коммуникации Azure поддерживают список событий, на которые можно подписываться.

Замените комментарий <RECEIVE MESSAGES> следующим кодом. После включения уведомлений попробуйте отправить новые сообщения для просмотра ChatMessageReceivedEvents.

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

Кроме того, можно получать сообщения чата, выполняя опрос метода listMessages через определенные интервалы. Дополнительные сведения см. в следующем фрагменте listMessagesкода.

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

Push-уведомления

Аналогично Twilio, Службы коммуникации Azure поддерживают push-уведомления. Push-уведомления уведомляют клиентов о входящих сообщениях в потоке чата, если мобильное приложение не работает на переднем плане.

В настоящее время отправка push-уведомлений чата с помощью Центра уведомлений поддерживается для пакета SDK для iOS версии 1.3.0.

Дополнительные сведения см. в разделе "Включить push-уведомление" в приложении чата.

Необходимые компоненты

• Создайте учетную запись Azure с активной подпиской. Дополнительные сведения см. на странице Создайте бесплатную учетную запись Azure уже сегодня.

• Установить Visual Studio.

• Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в кратком руководстве по созданию ресурсов Служб коммуникации и управлению ими. Запишите конечную точку ресурса и строка подключения.

• Маркер доступа пользователя. Не забудьте задать область чата и запишите строку токена и user_id строку. Вы также можете использовать Azure CLI и выполнить следующую команду с строка подключения для создания пользователя и маркера доступа.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Дополнительные сведения см. в статье "Использование Azure CLI для создания маркеров доступа и управления ими".

Концептуальное различие

Беседы Twilio и Службы коммуникации Azure Чат предлагают аналогичные функции, но их реализация отличается из-за окружающих экосистем и базовых философий платформы. Беседы Twilio предоставляют API обмена данными с несколькими каналами. Службы коммуникации Azure чат ориентирован в основном на чат в экосистеме Azure. Это руководство по миграции предоставляет базовое сопоставление общих операций в Twilio и их эквивалентов в Службы коммуникации Azure чате, помогая вам перенести код .NET.

Удостоверения

Twilio

Беседы Twilio используют строки удостоверений напрямую.

Службы коммуникации Azure

Службы коммуникации Azure требует создания пользователей CommunicationIdentityClientс помощью .

Установка

Установка пакета

Чтобы начать миграцию из чата Twilio Conversations, сначала необходимо установить пакет SDK для чата Службы коммуникации Azure для .NET в проект.

dotnet add package Azure.Communication.Chat

Объектная модель

Указанные ниже классы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для C#.

Имя	Описание
ChatClient	Этот класс требуется для реализации всех функций чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatThreadClient	Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения участников, а также для отправки уведомлений о вводе и уведомления о прочтении.

Создание клиента чата

Twilio

Twilio требует настройки клиента Twilio с помощью учетных данных учетной записи:

var twilio = new TwilioRestClient(accountSid, authToken);

Службы коммуникации Azure

Чтобы создать клиент чата в Службы коммуникации Azure, используйте конечную точку Служб коммуникации и маркер доступа, созданный в рамках необходимых действий. Чтобы создать пользователя и выдать маркер для передачи клиенту чата, необходимо использовать класс CommunicationIdentityClient из пакета SDK для удостоверений.

Дополнительные сведения о маркерах доступа пользователей см. здесь.

// Your unique Azure Communication service endpoint
Uri endpoint = new Uri("<replace with your resource endpoint>");
CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);

Запуск потока чата

Беседы Twilio

var conversation = ConversationResource.Create(
    friendlyName: "My Conversation",
    messagingServiceSid: "<MessagingServiceSid>"
);

Службы коммуникации Azure

В Службы коммуникации Azure создается поток, эквивалентный беседе в Twilio.

Чтобы создать поток чата, используйте метод в createChatThread следующих параметрах chatClient:

• Используйте topic для предоставления раздела этому чату; вы можете обновить topic после создания потока чата UpdateTopic с помощью функции.
• Используйте свойство participants для передачи списка объектов ChatParticipant, добавляемых в поток чата. Инициализация ChatParticipantCommunicationIdentifier объекта с помощью объекта. CommunicationIdentifier может быть типом CommunicationUserIdentifier, MicrosoftTeamsUserIdentifierили PhoneNumberIdentifier. Например, чтобы получить CommunicationIdentifier объект, необходимо передать идентификатор доступа, созданный после инструкций по созданию пользователя.

Объект ответа из метода createChatThread содержит подробные сведения о chatThread. Чтобы взаимодействовать с операциями потока чата, такими как добавление участников, отправка сообщения, удаление сообщения и т. д., создание chatThreadClient экземпляра клиента с помощью GetChatThreadClient метода на клиенте ChatClient .

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Получение клиента потока чата

Twilio

В беседах Twilio вы взаимодействуете непосредственно с беседой с помощью идентификатора безопасности беседы (уникальный идентификатор). Вот как обычно получить беседу и взаимодействовать с ней:

var conversationSid = "<CONVERSATION_SID>";
var conversation = ConversationResource.Fetch(pathSid: conversationSid);

// Example: Fetching all messages in the conversation
var messages = MessageResource.Read(pathConversationSid: conversationSid);
foreach (var message in messages)
{
    Console.WriteLine(message.Body);
}

Службы коммуникации Azure

Метод GetChatThreadClient возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д. threadId — это уникальный идентификатор существующей беседы чата.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Перечисление всех потоков чата

Twilio

В беседах Twilio можно получить все беседы, которые пользователь является участником, запрашивая UserConversations ресурс. Этот ресурс предоставляет список бесед для конкретного пользователя.

/ Initialize Twilio Client
string accountSid = "<YOUR_ACCOUNT_SID>";
string authToken = "<YOUR_AUTH_TOKEN>";
TwilioClient.Init(accountSid, authToken);

// The identity of the user you're querying
string userIdentity = "[email protected]";

// Retrieve all conversations the user is part of
var userConversations = UserConversationResource.Read(pathUserSid: userIdentity);

foreach (var userConversation in userConversations)
{
    Console.WriteLine($"Conversation SID: {userConversation.ConversationSid}");
    // You can fetch more details about the conversation if needed
    var conversation = Twilio.Rest.Conversations.V1.ConversationResource.Fetch(pathSid: userConversation.ConversationSid);
    Console.WriteLine($"Conversation Friendly Name: {conversation.FriendlyName}");
}

Службы коммуникации Azure

Чтобы получить все потоки чата, в которых участвует пользователь, используйте GetChatThreads.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Отправка сообщения в поток чата

Twilio

В следующем фрагменте кода показано, как отправить текстовое сообщение.

var message = MessageResource.Create(
    body: "Hello, world!",
    from: "[email protected]",
    pathConversationSid: conversation.Sid
);

В следующем фрагменте кода показано, как отправить файл мультимедиа.

// The SID of the conversation you want to send the media message to
string conversationSid = "<CONVERSATION_SID>";

// The URL of the media file you want to send
var mediaUrl = new List<Uri>
{
    new Uri("https://example.com/path/to/media/file.jpg") // Replace with your actual media URL
};

// Send the media message
var message = MessageResource.Create(
    body: "Here is an image for you!",
    from: "[email protected]", // Sender's identity (optional)
    mediaUrl: mediaUrl,
    pathConversationSid: conversationSid
);

Службы коммуникации Azure

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для отправки текстовых сообщений или мультимедиа.

Для отправки сообщения в поток используйте SendMessage.

• Используется content для предоставления содержимого сообщения.
• Используется type для типа контента сообщения, например Text или Html. Если тип не указан, по умолчанию используется вариант Text.
• Используйте senderDisplayName, чтобы указать отображаемое имя отправителя. Если значение не указано, пустая строка по умолчанию.
• Используйте metadata необязательно, чтобы включить любые другие данные, которые вы хотите отправить вместе с сообщением. Это поле предоставляет механизм для разработчиков для расширения функции сообщения чата и добавления пользовательских сведений для вашего варианта использования. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment:true в метаданные, чтобы приложение получателя могло проанализировать это и отобразить соответствующим образом.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Получение сообщений из потока чата

Twilio

Twilio обычно использует веб-перехватчики для уведомления сервера входящих сообщений:

В следующем фрагменте кода показано, как получить текстовое сообщение.

public IActionResult ReceiveMessage()
{
    var incomingMessage = Request.Form["Body"];
    // Process the incoming message
    return Ok();
}

В следующем фрагменте кода показано, как получить файл мультимедиа.

 for (var i = 0; i < numMedia; i++)
            {
                var mediaUrl = Request.Form[$"MediaUrl{i}"];
                Trace.WriteLine(mediaUrl);
                var contentType = Request.Form[$"MediaContentType{i}"];

                var filePath = GetMediaFileName(mediaUrl, contentType);
                await DownloadUrlToFileAsync(mediaUrl, filePath);
            }

Службы коммуникации Azure

В отличие от Twilio, Службы коммуникации Azure не имеет отдельной функции для получения текстовых сообщений или мультимедиа.

Службы коммуникации Azure чат позволяет подписаться на события непосредственно в приложении.

Вы можете получать сообщения чата, выполняя опрос метода GetMessages на клиенте потока чата через определенные интервалы.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages принимает необязательный параметр DateTimeOffset. Если это смещение указано, вы получаете сообщения, полученные, обновленные или удаленные после него. Сообщения, полученные до времени смещения, но изменены или удалены после возврата.

GetMessages возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью UpdateMessage и DeleteMessage. Для удаленных сообщений chatMessage.DeletedOn возвращает значение даты и времени, указывающее, когда это сообщение было удалено. Для измененных сообщений chatMessage.EditedOn возвращает значение даты и времени, указывающее, когда это сообщение было изменено. Вы можете получить доступ к исходному времени создания сообщения и chatMessage.CreatedOnиспользовать его для упорядочивания сообщений.

GetMessages возвращает различные типы сообщений, которые могут быть идентифицированы с помощью chatMessage.Type. Это следующие типы:

• Text: регулярное сообщение чата, отправленное членом потока.

• Html: форматированное текстовое сообщение. Пользователи служб коммуникации в настоящее время не могут отправлять RichText сообщения. Этот тип сообщений поддерживается в сообщениях, отправленных от пользователей Teams пользователям Служб коммуникации в сценариях взаимодействия с Teams.

• TopicUpdated: системное сообщение, указывающее, что раздел обновлен. (только чтение)

• ParticipantAdded: системное сообщение, указывающее, что один или несколько участников были добавлены в поток чата. (только чтение)

• ParticipantRemoved: системное сообщение, указывающее, что участник был удален из потока чата.

Дополнительные сведения см. в разделе "Типы сообщений".

Добавление пользователя в качестве участника в поток чата

Twilio

var participant = ParticipantResource.Create(
    pathConversationSid: conversation.Sid,
    identity: "[email protected]"
);

Службы коммуникации Azure

В Службы коммуникации Azure вы добавляете участников при создании потока чата или после этого:

После создания потока можно добавить и удалить пользователей. Добавление пользователей предоставляет им доступ к отправке сообщений в поток и добавление и удаление других участников. Перед вызовом AddParticipantsубедитесь, что вы получаете новый маркер доступа и удостоверение для этого пользователя. Пользователю нужен маркер доступа для инициализации клиента чата.

Используйте AddParticipants для добавления одного или нескольких участников в поток чата. Ниже приведены поддерживаемые атрибуты для каждого участника потока:

• communicationUser (обязательно) — это идентификатор участника потока.
• displayName (необязательно) — это отображаемое имя для участника потока.
• shareHistoryTime (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.

var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Получение участников потока

Twilio

В беседах Twilio используется ConversationResource для извлечения участников определенной беседы. Затем вы можете перечислить всех участников, связанных с этой беседой.

// The SID of the conversation you want to retrieve participants from
string conversationSid = "<CONVERSATION_SID>";

// Retrieve all participants in the conversation
var participants = ParticipantResource.Read(pathConversationSid: conversationSid);

// Output details of each participant
foreach (var participant in participants)
{
    Console.WriteLine($"Participant SID: {participant.Sid}");
            
}

Службы коммуникации Azure

Используйте GetParticipants для получения участников потока чата.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Отправка уведомления о прочтении

Twilio

// Find your Account SID and Auth Token at twilio.com/console
        // and set the environment variables. See http://twil.io/secure
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

        TwilioClient.Init(accountSid, authToken);

        var message = await MessageResource.FetchAsync(
            pathConversationSid: "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            pathSid: "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");

        Console.WriteLine(message.Delivery);
    }

Службы коммуникации Azure

Используйте SendReadReceipt для уведомления других участников о том, что пользователь прочитал сообщение.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Необходимые компоненты

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .

• комплект SDK для Java (JDK) версии 8 или более поздней версии.

• Apache Maven.

• Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в кратком руководстве по созданию ресурсов Служб коммуникации и управлению ими. Необходимо записать конечную точку ресурса и строка подключения.

• Маркер доступа пользователя. Не забудьте задать область чата и запишите строку токена и строку user_id. Вы также можете использовать Azure CLI и выполнить следующую команду с строка подключения для создания пользователя и маркера доступа.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Дополнительные сведения см. в статье "Создание маркеров доступа и управление ими" с помощью Azure CLI.

Установка

Добавление ссылок на пакет для пакета SDK для чата

Twilio

Чтобы использовать API чатов Twilio в приложении Java, добавьте следующую зависимость в pom.xml:

<dependencies>
    <!-- Twilio Java SDK -->
    <dependency>
        <groupId>com.twilio.sdk</groupId>
        <artifactId>twilio</artifactId>
        <version>8.31.1</version>
    </dependency>
</dependencies>

Службы коммуникации Azure

В файле POM добавьте ссылку на пакет azure-communication-chat с помощью API-интерфейсов для чатов:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

Для проверки подлинности клиент должен добавить ссылку на пакет azure-communication-common:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для Java.

Имя	Описание
ChatClient	Этот класс необходим для функции Чата. Создайте экземпляр с информацией о подписке и используйте ее для создания, получения и удаления потоков.
ChatAsyncClient	Этот класс необходим для асинхронной функции чата. Создайте экземпляр с информацией о подписке и используйте ее для создания, получения и удаления потоков.
ChatThreadClient	Этот класс необходим для функции "Поток чата". Вы получаете экземпляр с помощью приложения ChatClientи используете его для отправки и получения и обновления, удаления и удаления сообщений, добавления и удаления пользователей, отправки уведомлений о вводе и получения квитанций о чтении.
ChatThreadAsyncClient	Этот класс необходим для асинхронной функции потока чата. Вы получаете экземпляр с помощью приложения ChatAsyncClientи используете его для отправки и получения и обновления, удаления и удаления сообщений, добавления и удаления пользователей, отправки уведомлений о вводе и получения квитанций о чтении.

Import

Twilio

import com.twilio.Twilio;
import com.twilio.rest.conversations.v1.Conversation;

Службы коммуникации Azure

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

Создание клиента чата

Twilio

В Twilio вы инициализируете клиент с помощью идентификатора безопасности учетной записи и маркера проверки подлинности. Вот как обычно инициализируется клиент.

String accountSid = "<YOUR_ACCOUNT_SID>";
String authToken = "<YOUR_AUTH_TOKEN>";
        
// Initialize Twilio client
Twilio.init(accountSid, authToken);

Службы коммуникации Azure

Чтобы создать клиент чата, используйте конечную точку службы коммуникации и маркер доступа, созданный в рамках необходимых действий. Маркеры доступа пользователей позволяют создавать клиентские приложения, которые напрямую проходят проверку подлинности в Службах коммуникации Azure. После создания этих маркеров на сервере передайте их обратно клиентскому устройству. Для передачи маркера клиенту чата необходимо использовать CommunicationTokenCredential класс из common SDK.

Дополнительные сведения об архитектуре чатов

При добавлении инструкций импорта не забудьте добавить только импорт из com.azure.communication.chat пространств имен и com.azure.communication.chat.models не из com.azure.communication.chat.implementation пространства имен. В файле, созданном App.java с помощью Maven, можно запустить следующий код:

// Your unique Azure Communication service endpoint
String endpoint = "<replace with your resource endpoint>";

// User access token fetched from your trusted service
String userAccessToken = "<USER_ACCESS_TOKEN>";

// Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

// Initialize the chat client
final ChatClientBuilder builder = new ChatClientBuilder();
    builder.endpoint(endpoint)
        .credential(userCredential);
    ChatClient chatClient = builder.buildClient();

Запуск потока чата

Twilio

Создание беседы в Twilio просто с помощью Conversation.creator() метода.

setFriendlyName Используйте эту статью для этого чата.

// Create a new conversation
        Conversation conversation = Conversation.creator().setFriendlyName("New Conversation").create();
        System.out.println(conversation.getSid());

Службы коммуникации Azure

Для создания потока чата используйте метод createChatThread.

• ИспользуетсяcreateChatThreadOptions для описания запроса потока.
• topic Используйте параметр конструктора, чтобы предоставить раздел этому чату; обновите "раздел" после создания потока чата UpdateThread с помощью функции.
• Используйте participants, чтобы получить список участников потока, добавляемых в поток. ChatParticipant принимает пользователя, которого вы создали при изучении краткого руководства о маркере доступа пользователя.

CreateChatThreadResult — это ответ, возвращаемый при создании потока чата. Он содержит getChatThread() метод, который возвращает ChatThread объект, который можно использовать для получения клиента потока, из которого можно получить ChatThreadClient выполнение операций в созданном потоке: добавление участников, отправка сообщения и т. д.

Объект ChatThread также содержит getId() метод, который получает уникальный идентификатор потока.

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

Перечисление потоков чата

Twilio

Список всех бесед в Twilio с помощью Java:

public static void main(String[] args) {
        // List all conversations
        ResourceSet<Conversation> conversations = Conversation.reader().read();

        for (Conversation conversation : conversations) {
            System.out.println("Conversation SID: " + conversation.getSid());
            System.out.println("Friendly Name: " + conversation.getFriendlyName());
            System.out.println("Date Created: " + conversation.getDateCreated());
        }
    }

Службы коммуникации Azure

Для получения списка существующих потоков чата используйте метод listChatThreads.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

Получение клиента потока чата

Twilio

Вот как можно получить и взаимодействовать с определенной беседой в Twilio с помощью Java:

// Retrieve a specific conversation by its SID
Conversation conversation = Conversation.fetcher(conversationSid).fetch();
System.out.println("Retrieved Conversation SID: " + conversation.getSid());
System.out.println("Friendly Name: " + conversation.getFriendlyName())

Службы коммуникации Azure

Метод getChatThreadClient возвращает клиент потока для имеющегося потока. Используйте его для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д. chatThreadId — это уникальный идентификатор существующей беседы чата.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Отправка сообщения в поток чата

Twilio

При отправке сообщения в Twilio используется Message.creator() метод.

import com.twilio.rest.conversations.v1.conversation.Message;

Message message = Message.creator(conversationSid)
    .setBody("Hello, World!")
    .create();
System.out.println("Message SID: " + message.getSid());

Twilio позволяет отправлять файлы мультимедиа, предоставляя URL-адрес мультимедиа при отправке сообщения.

List<URI> mediaUrls = Arrays.asList(URI.create("https://example.com/image.jpg"));
Message message = Message.creator(conversationSid)
    .setBody("Check out this image!")
    .setMediaUrl(mediaUrls)
    .create();
System.out.println("Message SID: " + message.getSid());

Службы коммуникации Azure

В отличие от Twilio, Службы коммуникации Azure не имеет отдельных функций для отправки мультимедиа. sendMessage Используйте метод для отправки сообщения созданному потоку.chatThreadId

Используется sendChatMessageOptions для описания запроса на сообщение чата.

• Используйте content, чтобы указать содержимое сообщения в чате.
• Используется type для указания типа контента сообщения чата: TEXT или HTML.
• Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
• Используйте metadata необязательно, чтобы включить любые данные, которые вы хотите отправить с сообщением. Это поле позволяет разработчикам расширить функцию сообщения чата и добавить пользовательские сведения для вашего варианта использования. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment:true в метаданные, чтобы приложение получателя могло проанализировать их и отобразить соответствующим образом.

sendChatMessageResult ответа содержит id, который является уникальным идентификатором сообщения.

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

Получение сообщений из потока чата

Twilio

Беседы Twilio используют веб-перехватчики для получения сообщений. Обычно вы настраиваете URL-адрес веб-перехватчика в консоли Twilio.

// This would be handled by a servlet or similar in a Java web application
public void handleIncomingMessage(HttpServletRequest request, HttpServletResponse response) {
    String body = request.getParameter("Body");
    System.out.println("Received message: " + body);
}

Получение файла мультимедиа в Twilio.

private static final Logger logger = Logger.getLogger(TwilioWebhookServlet.class.getName());

    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        // Get the number of media items attached to the message
        String numMedia = request.getParameter("NumMedia");

        int mediaCount = Integer.parseInt(numMedia);

        if (mediaCount > 0) {
            // Loop through each media file received
            for (int i = 0; i < mediaCount; i++) {
                // Get the media URL from the request
                String mediaUrl = request.getParameter("MediaUrl" + i);
                String mediaContentType = request.getParameter("MediaContentType" + i);

                logger.info("Received media file: " + mediaUrl + " with content type: " + mediaContentType);

                // Process the media file (e.g., download, store, etc.)
                // Example: Download and save the file, or send it to another service
            }
        } else {
            // Handle a message with no media
            String messageBody = request.getParameter("Body");
            logger.info("Received text message: " + messageBody);
        }

Службы коммуникации Azure

Вы можете получать сообщения чата, выполняя опрос метода listMessages на клиенте потока чата через определенные интервалы.

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью .editMessage() и .deleteMessage(). Для удаленных сообщений chatMessage.getDeletedOn() возвращает значение datetime, указывающее, когда это сообщение было удалено. Для измененных сообщений chatMessage.getEditedOn() возвращает значение даты и времени, указывающее, когда это сообщение было изменено. Доступ к исходному времени создания сообщения можно получить с помощью chatMessage.getCreatedOn(), который также можно использовать для упорядочения сообщений.

Дополнительные сведения о типах сообщений см. в разделе Типы сообщений.

Отправка уведомления о прочтении

Twilio

В Twilio Conversations нет прямого API для отправки квитанций о чтении. Беседы Twilio автоматически управляют получением считывания.

Службы коммуникации Azure

Для публикации события уведомления о прочтении в потоке от имени пользователя используйте метод sendReadReceipt.

chatMessageId — это уникальный идентификатор считанного сообщения в чате.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

Перечисление участников чата

Twilio

Чтобы получить участников беседы Twilio, выполните приведенные действия.

ResourceSet<Participant> participants = Participant.reader(conversationSid).read();

for (Participant participant : participants) {
    System.out.println("Participant SID: " + participant.getSid());
}

Службы коммуникации Azure

Для получения страничной коллекции, содержащей участников потока чата, идентифицируемого значением chatThreadId, используйте listParticipants.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

Добавление пользователя в качестве участника в поток чата

Twilio

Добавьте участников в беседу с помощью метода Participant.creator().

import com.twilio.rest.conversations.v1.conversation.Participant;

Participant participant = Participant.creator(conversationSid)
    .setIdentity("[email protected]")
    .create();
System.out.println("Participant SID: " + participant.getSid());

Службы коммуникации Azure

После создания потока чата можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им доступ для отправки сообщений в поток чата, а также добавления или удаления других участников. Начните с получения нового маркера доступа и удостоверения для этого пользователя. Перед вызовом addParticipants метода убедитесь, что вы приобрели новый маркер доступа и удостоверение для этого пользователя. Пользователю требуется маркер доступа для инициализации клиента чата.

Для добавления участников в поток используйте метод addParticipants.

• communicationIdentifier( обязательно) — это CommunicationIdentifier созданный CommunicationIdentityClient в кратком руководстве по маркеру доступа пользователей.
• displayName (необязательно) — это отображаемое имя для участника потока.
• shareHistoryTime (необязательно) — это время, в течение которого участнику предоставляется доступ к журналу чата. Чтобы предоставить общий доступ к журналу с момента запуска потока чата, установите для этого свойства любую дату, равную или меньше времени создания потока. Чтобы в журнале отображались только записи с момента добавления участника, задайте для свойства текущую дату. Чтобы предоставить общий доступ к части журнала, задайте для него требуемую дату.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);