Avvia una conversazione con un bot di Microsoft Teams

Una conversazione è una serie di messaggi inviati tra il bot e uno o più utenti. Esistono tre tipi di conversazione (detti anche ambiti) in Teams:

• teams Dette anche conversazioni di canale, visibili a tutti i membri del canale.
• personal Conversazioni tra bot e un singolo utente.
• groupChatChat tra un bot e due o più utenti.

Un bot si comporta in modo leggermente diverso a seconda del tipo di conversazione in cui è coinvolto:

• I bot nelle conversazioni nel canale e nelle chat di gruppo richiedono che l'utente richiami il bot in @mention un canale.
• I bot nelle conversazioni con un singolo utente non richiedono un @mention : l'utente può semplicemente digitare.

Affinché il bot funzioni in un particolare ambito, dovrebbe essere elencato come supporto di tale ambito nel manifesto. Gli ambiti sono definiti e discussi ulteriormente nella Guida di riferimento al manifesto.

Messaggi proattivi

I bot possono partecipare a una conversazione o avviarne una. La maggior parte delle comunicazioni avviene in risposta a un altro messaggio. Se un bot avvia una conversazione, si parla di messaggio proattivo. Ecco alcuni esempi:

• Messaggi di benvenuto
• Notifiche degli eventi
• Messaggi di polling

Nozioni di base sulla conversazione

Ogni messaggio è un Activity oggetto di tipo messageType: message. Quando un utente invia un messaggio, Teams lo pubblica nel bot. In particolare, invia un oggetto JSON all'endpoint di messaggistica del bot. Il bot esamina il messaggio per determinarne il tipo e risponde di conseguenza.

I bot supportano anche i messaggi di tipo evento. Per altre informazioni, vedere Gestire gli eventi bot in Microsoft Teams. I comandi vocali non sono supportati.

I messaggi sono in genere uguali in tutti gli ambiti, ma ci sono differenze nel modo in cui si accede al bot nell'interfaccia utente e differenze dietro le quinte, che è necessario conoscere.

La conversazione di base viene gestita tramite Bot Framework Connector, una singola API REST per consentire al bot di comunicare con Teams e altri canali. Bot Builder SDK offre un facile accesso a questa API, funzionalità aggiuntive per gestire il flusso e lo stato delle conversazioni e modi semplici per incorporare servizi cognitivi come l'elaborazione del linguaggio naturale (NLP).

Contenuto del messaggio

Il bot può inviare testo RTF, immagini e schede. Gli utenti possono inviare testo RTF e immagini al bot. È possibile specificare il tipo di contenuto che il bot può gestire nella pagina delle impostazioni di Microsoft Teams per il bot.

Per altre informazioni sui tipi di interazione con i bot supportati da Bot Framework, su cui si basano i bot nei team, vedere la documentazione di Bot Framework sul flusso di conversazione e i concetti correlati nella documentazione per Bot Builder SDK per .NET e Bot Builder SDK per Node.js.

Formattazione dei messaggi

È possibile impostare la proprietà facoltativa TextFormat di a message per controllare come viene eseguito il rendering del contenuto testuale del messaggio. Per una descrizione dettagliata della formattazione supportata nei messaggi bot, vedere Formattazione dei messaggi . È possibile impostare la proprietà facoltativa TextFormat per controllare come viene eseguito il rendering del contenuto testuale del messaggio.

Per informazioni dettagliate su come Teams supporta la formattazione del testo nei team, vedere Formattazione del testo nei messaggi bot.

Per altre informazioni sulla formattazione delle schede nei messaggi, vedere Formattazione delle schede.

Messaggi con immagine

Le immagini vengono inviate aggiungendo allegati a un messaggio. Per altre informazioni sugli allegati, vedere la documentazione di Bot Framework.

Le immagini possono essere al massimo 1024×1024 MB e 1 MB in formato PNG, JPEG o GIF; Le GIF animate non sono supportate.

È consigliabile specificare l'altezza e la larghezza di ogni immagine utilizzando il linguaggio XML. Se usi Markdown, la dimensione predefinita dell'immagine è 256×256. Ad esempio:

• Utilizzo <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
• Non usare ![Duck on a rock](http://aka.ms/Fo983c)

Ricezione di messaggi

A seconda degli ambiti dichiarati, il bot può ricevere messaggi nei contesti seguenti:

• Chat personale Gli utenti possono interagire in una conversazione privata con un bot selezionando il bot aggiunto nella cronologia della chat o digitandone il nome o l'ID app nella casella A: in una nuova chat.
• Canali Un bot può essere menzionato ("@botname") in un canale se è stato aggiunto al team. Si noti che per risposte aggiuntive a un bot in un canale è necessario menzionare il bot. Non risponderà alle risposte in cui non è menzionato.

Per i messaggi in arrivo, il tuo bot riceve un oggetto Activity di tipo messageType: message. Anche se l'oggetto Activity può contenere altri tipi di informazioni, ad esempio gli aggiornamenti dei canali inviati al bot, il tipo rappresenta la comunicazione tra il bot e l'utente message .

Il bot riceve un payload contenente il messaggio Text dell'utente e altre informazioni sull'utente, l'origine del messaggio e le informazioni di Teams. Da notare:

• timestamp La data e l'ora del messaggio in formato UTC (Coordinated Universal Time).
• localTimestamp Data e ora del messaggio nel fuso orario del mittente.
• channelId Sempre "msteams". Questo fa riferimento a un canale del framework bot, non a un canale di Teams.
• from.id ID univoco e crittografato per tale utente per il bot. Adatto come chiave se la tua app deve archiviare i dati degli utenti. È univoco per il bot e non può essere usato direttamente all'esterno dell'istanza del bot in modo significativo per identificare l'utente.
• channelData.tenant.id ID tenant per l'utente.

Combinazione di interazioni di canale e private con il bot

Quando interagisce in un canale, il bot deve essere intelligente nel portare determinate conversazioni offline con un utente. Si supponga, ad esempio, che un utente stia cercando di coordinare un'attività complessa, ad esempio la pianificazione con un set di membri del team. Anziché lasciare visibile l'intera sequenza di interazioni al canale, valuta la possibilità di inviare un messaggio di chat personale all'utente. Il bot dovrebbe essere in grado di passare facilmente l'utente dalle conversazioni personali a quelle del canale senza perdere lo stato.

Esempio di schema in entrata completo

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot",
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Dati del canale di Teams

L'oggetto channelData contiene informazioni specifiche di Teams ed è l'origine definitiva per gli ID di team e canali. È consigliabile memorizzare nella cache e utilizzare questi ID come chiavi per l'archiviazione locale.

Un tipico oggetto channelData in un'attività inviata al bot contiene le informazioni seguenti:

• eventType Tipo di evento di Teams; Superato solo in caso di eventi di modifica del canale.
• tenant.idID tenant di Microsoft Entra; passato in tutti i contesti.
• team Passato solo nei contesti del canale, non nella chat personale.
  • id GUID per il canale.
  • name Nome del team; Superato solo in caso di eventi di ridenominazione del team.
• channel Passato solo nei contesti di canale quando il bot viene menzionato o per eventi nei canali di Teams in cui è stato aggiunto il bot.
  • id GUID per il canale.
  • name Nome del canale; Superato solo in caso di eventi di modifica del canale.
• channelData.teamsTeamId Deprecato. Questa proprietà è inclusa solo per la compatibilità con le versioni precedenti.
• channelData.teamsChannelId Deprecato. Questa proprietà è inclusa solo per la compatibilità con le versioni precedenti.

Esempio di oggetto channelData (evento channelCreated)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Esempio di .NET

Il pacchetto NuGet Microsoft.Bot.Connector.Teams fornisce un oggetto specializzato TeamsChannelData , che espone le proprietà per accedere alle informazioni specifiche di Teams.

TeamsChannelData channelData = activity.GetChannelData<TeamsChannelData>();
string tenantId = channelData.Tenant.Id;

Inviare risposte ai messaggi

Per rispondere a un messaggio esistente, chiamare ReplyToActivity in .NET o session.send in Node.js. L'SDK di Bot Builder gestisce tutti i dettagli.

Se scegli di usare l'API REST, puoi anche chiamare l'endpoint /v3/conversations/{conversationId}/activities/{activityId} .

Il contenuto del messaggio stesso può contenere testo semplice o alcune delle schede e delle azioni della scheda fornite da Bot Framework.

Si tenga presente che nello schema in uscita è consigliabile usare sempre lo stesso serviceUrl di quello ricevuto. Tieni presente che il valore di serviceUrl tende ad essere stabile, ma può cambiare. Quando arriva un nuovo messaggio, il bot deve verificare il valore memorizzato di serviceUrl.

Aggiornamento dei messaggi

Invece di fare in modo che i messaggi siano snapshot statici dei dati, il bot può aggiornare dinamicamente i messaggi inline dopo averli inviati. È possibile usare gli aggiornamenti dinamici dei messaggi per scenari come gli aggiornamenti dei sondaggi, la modifica delle azioni disponibili dopo la pressione di un pulsante o qualsiasi altro cambiamento di stato asincrono.

Non è necessario che il nuovo messaggio corrisponda al tipo originale. Ad esempio, se il messaggio originale conteneva un allegato, il nuovo messaggio può essere un messaggio di testo.

REST API

Per rilasciare un aggiornamento del messaggio, eseguire una richiesta PUT sull'endpoint /v3/conversations/<conversationId>/activities/<activityId>/ usando un ID attività specificato. Per completare questo scenario, è necessario memorizzare nella cache l'ID attività restituito dalla chiamata POST originale.

PUT /v3/conversations/19%3Aja0cu120i1jod12j%40skype.net/activities/012ujdo0128
{
    "type": "message",
    "text": "This message has been updated"
}

Esempio di .NET

È possibile usare il UpdateActivityAsync metodo nell'SDK di Bot Builder per aggiornare un messaggio esistente.

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
  if (activity.Type == ActivityTypes.Message)
  {
    ConnectorClient connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    Activity reply = activity.CreateReply($"You sent {activity.Text} which was {activity.Text.Length} characters");
    var msgToUpdate = await connector.Conversations.ReplyToActivityAsync(reply);
    Activity updatedReply = activity.CreateReply($"This is an updated message");
    await connector.Conversations.UpdateActivityAsync(reply.Conversation.Id, msgToUpdate.Id, updatedReply);
  }
}

Node.js esempio

È possibile usare il session.connector.update metodo nell'SDK di Bot Builder per aggiornare un messaggio esistente.

function sendCardUpdate(bot, session, originalMessage, address) {

  var origAttachment = originalMessage.data.attachments[0];
  origAttachment.content.subtitle = 'Assigned to Larry Jin';

  var updatedMsg = new builder.Message()
    .address(address)
    .textFormat(builder.TextFormat.markdown)
    .addAttachment(origAttachment)
    .toMessage();

  session.connector.update(updatedMsg, function(err, addresses) {
    if (err) {
      console.log(`Could not update the message`);
    }
  });
}

Avvio di una conversazione (messaggistica proattiva)

È possibile creare una conversazione personale con un utente o avviare una nuova catena di risposte in un canale per il bot del team. In questo modo è possibile inviare messaggi all'utente o agli utenti senza che debbano prima avviare un contatto con il bot. Per ulteriori informazioni, vedere gli articoli seguenti:

Per altre informazioni sulle conversazioni avviate dai bot, vedere messaggistica proattiva per i bot.

Eliminazione dei messaggi

I messaggi possono essere eliminati usando il connector.delete() metodo nell'SDK di BotBuilder.

bot.dialog('BotDeleteMessage', function (session: builder.Session) {
  var msg = new teams.TeamsMessage(session).text("Bot will delete this message in 5 sec.")
  bot.send(msg, function (err, response) {
    if (err) {
      console.log(err);
      session.endDialog();
    }

    console.log('Proactive message response:');
    console.log(response);
    console.log('---------------------------------------------------')
    setTimeout(function () {
      var activityId: string = null;
      var messageAddress: builder.IChatConnectorAddress = null;
      if (response[0]){
        messageAddress = response[0];
        activityId = messageAddress.id;
      }

      if (activityId == null)
      {
        console.log('Message failed to send.');
        session.endDialog();
        return;
      }

      // Bot delete message
      let address: builder.IChatConnectorAddress  = {
        channelId: 'msteams',
        user: messageAddress.user,
        bot: messageAddress.bot,
        id : activityId,
        serviceUrl : (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
        conversation: {
          id: session.message.address.conversation.id
        }
      };

      connector.delete(address, function (err) {
        if (err)
        {
          console.log(err);
        }
        else
        {
          console.log("Message: " + activityId + " deleted successfully.");
        }

        // Try editing deleted message would fail
        var newMsg = new builder.Message().address(address).text("To edit message.");
        connector.update(newMsg.toMessage(), function (err, address) {
          if (err)
          {
            console.log(err);
            console.log('Deleted message can not be edited.');
          }
          else
          {
            console.log("There is something wrong. Message: " + activityId + " edited successfully.");
            console.log(address);
          }

          session.endDialog();
        });
      });
    }, 5000);
  });
})