Condividi tramite

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

  • 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

Introduttiva

Prerequisiti

  • Una sottoscrizione di Azure .
  • Una risorsa di Servizi di comunicazione esistente. Se è necessario creare la risorsa, è possibile usare il portale di Azure , il Azure PowerShello l'interfaccia della riga di comando di Azure .
  • Node.js

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 creazione di bundle . In rollup.config.jsaggiungere le esportazioni dei nomi personalizzate seguenti nel plug-in cjs.


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 1:1 o in una chat di gruppo 1:N. Gli utenti ricevono anche aggiornamenti quasi in tempo reale per quando altri digitano e quando hanno letto i messaggi.

ChatClient

ChatClient è l'interfaccia principale 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.

Esempi

Inizializzare ChatClient

Usare l'URL della risorsa e il token di accesso utente per inizializzare il client di 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 di thread;

createChatThreadOptions viene usato per impostare i parametri 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 che è il thread creato, nonché una proprietà errors che conterrà informazioni sui partecipanti non validi se non sono stati aggiunti 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 consentirà 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 metodo getChatThreadClient di ChatClient con un ID thread esistente:

const chatThreadClient = chatClient.getChatThreadClient(threadId);

Inviare un messaggio al thread

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

sendMessageRequest viene usato per descrivere la richiesta di messaggio:

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

sendMessageOptions viene usato per descrivere i parametri facoltativi dell'operazione:

  • Utilizzare 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 utenti da tale thread. Aggiungendo utenti, è possibile concedere loro l'accesso per poter inviare messaggi al thread. È necessario iniziare ottenendo un nuovo token di accesso e un'identità per tale utente. L'utente dovrà disporre del token di accesso per inizializzare il client di chat. Altre informazioni sui token sono disponibili 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, è necessario tenere traccia degli ID dei partecipanti aggiunti.


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

Sottoscrivere lo stato di connessione delle notifiche in tempo reale

La 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 introduttiva 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

Contribuire

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