Messaggistica proattiva per i bot

Un messaggio proattivo è un messaggio inviato da un bot per avviare una conversazione. Potresti volere che il tuo bot avvii una conversazione per molti motivi, tra cui:

• Messaggi di benvenuto per le conversazioni bot personali.
• Risposte ai sondaggi.
• Notifiche di eventi esterni.

L'invio di un messaggio per avviare un nuovo thread di conversazione è diverso dall'invio di un messaggio in risposta a una conversazione esistente. Quando il bot avvia una nuova conversazione, non c'è alcuna conversazione preesistente in cui pubblicare il messaggio. Per inviare un messaggio proattivo, è necessario:

1. Decidere cosa dire
2. Ottenere l'ID univoco dell'utente e l'ID tenant
3. Inviare il messaggio

Quando si creano messaggi proattivi, è necessario chiamare MicrosoftAppCredentials.TrustServiceUrle passare l'URL del servizio prima di creare l'utilizzato ConnectorClient per inviare il messaggio. In caso contrario, l'app riceve una 401: Unauthorized risposta. Per altre informazioni, vedere gli esempi.

Procedure consigliate per la messaggistica proattiva

L'invio di messaggi proattivi è un modo efficace per comunicare con gli utenti. Tuttavia, dal punto di vista dell'utente, il messaggio appare non richiesto. Se c'è un messaggio di benvenuto, è la prima volta che interagiscono con la tua app. È importante usare questa funzionalità e fornire le informazioni complete all'utente per comprendere lo scopo di questo messaggio.

I messaggi proattivi in genere rientrano in una delle due categorie seguenti: messaggi di benvenuto o notifiche.

Messaggi di benvenuto

Quando si usa la messaggistica proattiva per inviare un messaggio di benvenuto a un utente, assicurarsi che dal punto di vista dell'utente il messaggio non venga richiesto. Se c'è un messaggio di benvenuto, è la prima volta che interagiscono con la tua app. I messaggi di benvenuto migliori includono:

• Perché ricevono questo messaggio: Dovrebbe essere chiaro all'utente il motivo per cui sta ricevendo questo messaggio. Se il bot è stato installato in un canale e hai inviato un messaggio di benvenuto a tutti gli utenti, informali in quale canale è stato installato e potenzialmente chi lo ha installato.
• Cosa offrite: cosa possono fare con la tua app? Che valore puoi apportare loro?
• Cosa dovrebbero fare dopo: invitali a provare un comando o interagire con la tua app in qualche modo.

Messaggi di notifica

Quando si usa la messaggistica proattiva per inviare notifiche, è necessario assicurarsi che gli utenti abbiano un percorso chiaro per intraprendere azioni comuni in base alla notifica e una chiara comprensione del motivo per cui è stata effettuata la notifica. I messaggi di notifica validi in genere includono:

• Cosa è successo: una chiara indicazione di ciò che è successo per causare la notifica.
• Che cosa è successo a: Dovrebbe essere chiaro quale elemento/oggetto è stato aggiornato per causare la notifica.
• Chi è stato: chi ha eseguito l'azione che ha causato l'invio della notifica?
• Cosa possono fare: rendi più facile per i tuoi utenti intraprendere azioni in base alle tue notifiche.
• Come possono rifiutare esplicitamente: fornire agli utenti un percorso per rifiutare esplicitamente le notifiche aggiuntive.

Ottenere le informazioni utente necessarie

I bot possono creare nuove conversazioni con un singolo utente di Microsoft Teams ottenendo l'ID univoco e l'ID tenant dell'utente. È possibile ottenere questi valori utilizzando uno dei metodi seguenti:

• Recuperando l'elenco dei partecipanti da un canale in cui viene installata l'app.
• Memorizzandole nella cache quando un utente interagisce con il bot in un canale.
• Quando un utente viene @mentioned in una conversazione del canale di cui fa parte il bot.
• Memorizzandoli nella cache quando si riceve l'evento conversationUpdate quando l'app viene installata in un ambito personale o quando vengono aggiunti nuovi membri a un canale o a una chat di gruppo.

Installare in modo proattivo l'app usando Graph

Occasionalmente potrebbe essere necessario inviare messaggi proattivi agli utenti che non hanno installato o interagito con l'app in precedenza. Ad esempio, si vuole usare il comunicatore aziendale per inviare messaggi all'intera organizzazione. Per questo scenario, è possibile usare l'API Graph per installare in modo proattivo l'app per gli utenti, quindi memorizzare nella cache i valori necessari dall'evento che l'app riceverà al momento dell'installazioneconversationUpdate.

È possibile installare solo le app presenti nel catalogo delle app dell'organizzazione o nello store di Microsoft Teams.

Per informazioni dettagliate, vedere Installare app per gli utenti nella documentazione di Graph. È disponibile anche un esempio in .NET.

Esempi

Assicurarsi di eseguire l'autenticazione e di avere un token di connessione prima di creare una nuova conversazione con l'API REST.

POST {Service URL of your bot}/v3/conversations

{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Specificare id l'ID dell'app bot e name il nome del bot. Puoi ottenere l'oggetto membersid dai tuoi bot TurnContext come turnContext.Activity.From.Id. Analogamente, id del tenant, dall'oggetto TurnContext bot come turnContext.Activity.ChannelData.Tenant.Id.

È necessario specificare l'ID utente e l'ID tenant. Se la chiamata ha esito positivo, l'API restituisce l'oggetto risposta seguente.

{
    "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"

}

Questo ID è l'ID di conversazione univoco della chat personale. Archiviare questo valore e riutilizzarlo per interazioni future con l'utente.

Uso di .NET

In questo esempio viene usato il pacchetto NuGet Microsoft.Bot.Connector.Teams .

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

Utilizzo di Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

Creazione di una conversazione sul canale

Il bot aggiunto al team può pubblicare post in un canale per creare una nuova catena di risposte. Se si usa l'SDK di Node.js Teams, usare startReplyChain(), che fornisce un indirizzo completamente popolato con l'ID attività e l'ID conversazione corretti. Se usi C#, vedi l'esempio seguente.

In alternativa, è possibile usare l'API REST ed eseguire una richiesta POST alla /conversations risorsa.

Esempi per la creazione di una conversazione sul canale

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

POST {Service URL of your bot}/v3/conversations

{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

from microsoft_teams.apps import App
from microsoft_teams.api import MessageActivityInput
import asyncio

# Bot credentials
app_id = "YOUR_BOT_APP_ID"
app_password = "YOUR_BOT_APP_SECRET"

# Conversation details (obtained from bot installation event)
conversation_id = "19:channelId@thread.tacv2"

# Initialize the Teams app
app = App(
    storage={},
    client_id=app_id,
    client_secret=app_password
)

# Create the message activity
activity = MessageActivityInput(text="Hello from proactive message!")

# Send proactive message using Teams SDK
# The SDK handles authentication, activity construction, and API calls
result = await app.send(
    conversation_id=conversation_id,
    activity=activity
)

Vedere anche

Esempi di Bot Framework.