Share via

Libreria client di Chat di comunicazione di Azure per JavaScript - versione 1.5.0

  • Articolo

Servizi di comunicazione di Azure per Chat consente agli sviluppatori di aggiungere funzionalità di chat all'app. Usare questa libreria client per gestire i thread di chat e i relativi utenti e inviare e ricevere messaggi di chat.

Altre informazioni su Servizi di comunicazione di Azure qui

Introduzione

Prerequisiti

Installazione

npm install @azure/communication-chat

Supporto browser

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di raggruppamento. In aggiungere le esportazioni di nomi personalizzati seguenti nel plug-inrollup.config.jscjs.


cjs({
  namedExports: {
    events: ["EventEmitter"],
    "@azure/communication-signaling": ["CommunicationSignalingClient", "SignalingClient"],
    "@opentelemetry/api": ["CanonicalCode", "SpanKind", "TraceFlags"]
  }
})

Concetti chiave

Una conversazione di chat è rappresentata da un thread. Ogni utente nel thread viene chiamato partecipante alla chat. I partecipanti alla chat possono chattare tra loro privatamente in una chat di 1:1 o huddle up in una chat di gruppo 1:N. Gli utenti ottengono anche aggiornamenti quasi in tempo reale per quando altri digitano e quando hanno letto i messaggi.

ChatClient

ChatClient è l'interfaccia primaria per gli sviluppatori che usano questa libreria client. Fornisce metodi asincroni per creare ed eliminare un thread.

ChatThreadClient

ChatThreadClient fornisce metodi asincroni per eseguire le operazioni dei partecipanti a messaggi e chat all'interno del thread di chat.

Esempio

Inizializzare ChatClient

Usare l'URL della risorsa e il token di accesso utente per inizializzare il client chat.

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

// Your unique Azure Communication service endpoint
const endpointUrl = '<ENDPOINT>';
const userAccessToken = '<USER_ACCESS_TOKEN>';
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

Creare un thread con due utenti

Usare il metodo createThread per creare un thread di chat.

createChatThreadRequest viene usato per descrivere la richiesta di thread:

  • Usare topic per assegnare un argomento thread;

createChatThreadOptions viene usato per impostare i params facoltativi per creare il thread:

  • Usare participants per elencare i partecipanti alla chat da aggiungere al thread;
  • Usare idempotencyToken per specificare una richiesta ripetibile

createChatThreadResult è il risultato restituito dalla creazione di un thread. Contiene un chatThread thread creato, nonché una errors proprietà che conterrà informazioni sui partecipanti non validi se non è stato possibile aggiungere al thread.

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;

Creare un chatThreadClient

ChatThreadClient consente di eseguire operazioni specifiche di un thread di chat, ad esempio aggiornare l'argomento del thread di chat, inviare un messaggio, aggiungere partecipanti al thread di chat e così via.

È possibile inizializzare un nuovo ChatThreadClient usando il getChatThreadClient metodo di ChatClient con un ID thread esistente:

const chatThreadClient = chatClient.getChatThreadClient(threadId);

Inviare un messaggio al thread

Usare sendMessage il metodo per inviare un messaggio a un thread identificato da threadId.

sendMessageRequest viene usato per descrivere la richiesta del messaggio:

  • Usare content per fornire il contenuto del messaggio di chat.

sendMessageOptions viene usato per descrivere le params facoltative dell'operazione:

  • Usare senderDisplayName per specificare il nome visualizzato del mittente.
  • Usare type per specificare il tipo di messaggio, ad esempio 'text' o 'html';

sendChatMessageResult è il risultato restituito dall'invio di un messaggio, contiene un ID, ovvero l'ID univoco del messaggio.

const sendMessageRequest =
{
  content: 'Hello Geeta! Can you share the deck for the conference?'
};
const sendMessageOptions:SendMessageOptions = {
  senderDisplayName: "Jack",
  type: "text"
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;

Ricevere messaggi da un thread

Con la segnalazione in tempo reale, è possibile sottoscrivere l'ascolto dei nuovi messaggi in arrivo e aggiornare i messaggi correnti in memoria di conseguenza.


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

In alternativa, è possibile recuperare i messaggi di chat eseguendo il polling del metodo listMessages a intervalli specificati.

for await (const chatMessage of chatThreadClient.listMessages()) {
   // your code here
}

Aggiungere utenti a un thread

Dopo aver creato un thread, è possibile aggiungere e rimuovere gli utenti da tale thread. Aggiungendo utenti, si concede loro l'accesso per poter inviare messaggi al thread. Per iniziare, è necessario ottenere un nuovo token di accesso e un'identità per tale utente. L'utente dovrà usare il token di accesso per inizializzare il client di chat. Altre informazioni sui token qui: Eseguire l'autenticazione a Servizi di comunicazione di Azure


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

await chatThreadClient.addParticipants(addParticipantsRequest);

Rimuovere utenti da un thread

Analogamente a quanto sopra, è anche possibile rimuovere gli utenti da un thread. Per rimuovere, sarà necessario tenere traccia degli ID dei partecipanti aggiunti.


await chatThreadClient.removeParticipant({ communicationUserId: '<MEMBER_ID>' });

Sottoscrivere lo stato di connessione delle notifiche in tempo reale

Sottoscrizione agli eventi realTimeNotificationConnected e realTimeNotificationDisconnected consente di sapere quando la connessione al server di chiamata è attiva.


// 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
});

Risoluzione dei problemi

Passaggi successivi

In questa guida di avvio rapido si è appreso come:

  • Creare un client di chat
  • Creare un thread con 2 utenti
  • Inviare un messaggio al thread
  • Ricevere messaggi da un thread
  • Rimuovere utenti da un thread

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.