Obtener contexto para el bot de Microsoft Teams

  • Artículo

Importante

Este artículo se basa en el SDK de Bot Framework v3. Si busca la versión 4.6 o posterior de la documentación actual del SDK, consulte la sección bots conversacionales .

El bot puede acceder a contextos adicionales sobre el equipo o el chat, como el perfil de usuario. Esta información se puede usar para enriquecer la funcionalidad del bot y proporcionar una experiencia más personalizada.

Nota:

  • Se obtiene mejor acceso a las API de bot específicas de Microsoft Teams a través de nuestras extensiones del SDK de Bot Builder.
  • Para C# o .NET, descargue nuestro paquete NuGet Microsoft.Bot.Connector.Teams .
  • Para Node.js desarrollo, la funcionalidad Bot Builder para Teams se incorpora al SDK de Bot Framework v4.6.

Captura de la lista de equipos

El bot puede consultar la lista de miembros del equipo y sus perfiles básicos. Los perfiles básicos incluyen identificadores de usuario de Teams e información de Microsoft Entra, como el nombre y el identificador de objeto. Puede usar esta información para correlacionar las identidades de usuario. Por ejemplo, compruebe si un usuario ha iniciado sesión en una pestaña a través de Microsoft Entra credenciales es miembro del equipo.

Ejemplo de API REST

Emita directamente una solicitud GET en /conversations/{teamId}/members/, utilizando el serviceUrl valor como punto de conexión.

teamId Se puede encontrar en el channeldata objeto de la carga de actividad que recibe el bot en los siguientes escenarios:

Nota:

  • Use siempre el identificador de equipo al llamar a la API.
  • El serviceUrl valor tiende a ser estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado serviceUrl .
GET /v3/conversations/19:ja0cu120i1jod12j@skype.net/members

Response body
[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "objectId": "9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c",
    "givenName": "Larry",
    "surname": "Brown",
    "email": "Larry.Brown@fabrikam.com",
    "userPrincipalName": "labrown@fabrikam.com"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com"
}, {
    "id": "29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs",
    "objectId": "6b7b3b2a-2c4b-4175-8582-41c9e685c1b5",
    "givenName": "Rick",
    "surname": "Stevens",
    "email": "Rick.Stevens@fabrikam.com",
    "userPrincipalName": "rstevens@fabrikam.com"
}]

Ejemplo de .NET

Llame a GetConversationMembersAsync using Team.Id para devolver una lista de identificadores de usuario. La llamada GetConversationMembersAsync a para obtener userRole la propiedad devuelve el valor como usuario.

// Fetch the members in the current conversation
var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));
var teamId = context.Activity.GetChannelData<TeamsChannelData>().Team.Id;
var members = await connector.Conversations.GetConversationMembersAsync(teamId);

// Concatenate information about all members into a string
var sb = new StringBuilder();
foreach (var member in members.AsTeamsChannelAccounts())
{
    sb.AppendFormat(
        "GivenName = {0}, TeamsMemberId = {1}",
        member.Name, member.Id);

    sb.AppendLine();
}

// Post the member info back into the conversation
await context.PostAsync($"People in this conversation: {sb.ToString()}");

ejemplo de Node.js o TypeScript


[...]
import * as builder from "botbuilder";
[...]

var teamId = session.message.sourceEvent.team.id;
connector.fetchMembers(
  (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is some error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Capturar perfil de usuario o lista en chat personal o grupal

Puede realizar la llamada a la API para cualquier chat personal para obtener la información de perfil del usuario que chatea con el bot.

La llamada API, los métodos del SDK y el objeto de respuesta son idénticos a la captura de la lista de equipos. La única diferencia es que pasa en conversationId lugar de .teamId

Captura de la lista de canales de un equipo

El bot puede consultar la lista de canales de un equipo.

Nota:

  • El nombre del canal predeterminado General se devuelve como null para permitir la localización.
  • El identificador de canal General siempre coincide con el identificador de equipo.

Ejemplo de API REST

Emita directamente una solicitud GET en /teams/{teamId}/conversations/, utilizando el serviceUrl valor como punto de conexión.

El único origen de teamId es un mensaje del contexto del equipo. El mensaje es un mensaje de un usuario o el mensaje que recibe el bot cuando se agrega a un equipo. Para obtener más información, consulte Bot o usuario agregado a un equipo.

Nota:

El serviceUrl valor tiende a ser estable, pero puede cambiar. Cuando llega un nuevo mensaje, el bot debe comprobar su valor almacenado serviceUrl .

GET /v3/teams/19%3A033451497ea84fcc83d17ed7fb08a1b6%40thread.skype/conversations

Response body
{
    "conversations": [{
        "id": "19:033451497ea84fcc83d17ed7fb08a1b6@thread.skype",
        "name": null
    }, {
        "id": "19:cc25e4aae50746ecbb11473bba24c70a@thread.skype",
        "name": "Materials"
    }, {
        "id": "19:b7b84cba410c406ba671dbbf5e0a3519@thread.skype",
        "name": "Design"
    }, {
        "id": "19:fc5db2aed489454e8f8c06829ed6c986@thread.skype",
        "name": "Marketing"
    }]
}

Ejemplo de .NET

En el ejemplo siguiente se usa la FetchChannelList llamada desde las extensiones de Teams para bot Builder SDK para .NET:

ConversationList channels = client.GetTeamsConnectorClient().Teams.FetchChannelList(activity.GetChannelData<TeamsChannelData>().Team.Id);

Ejemplo de Node.js

En el ejemplo siguiente se usa fetchChannelList la llamada desde las extensiones de Teams para el SDK de Bot Builder para Node.js:

var teamId = session.message.sourceEvent.team.id;
connector.fetchChannelList(
  (session.message.address).serviceUrl,
  teamId,
  (err, result) => {
    if (err) {
      session.endDialog('There is an error');
    }
    else {
      session.endDialog('%s', JSON.stringify(result));
    }
  }
);

Obtener clientInfo en el contexto del bot

Puede capturar clientInfo dentro de la actividad del bot. ClientInfo contiene las siguientes propiedades:

  • Locale
  • País
  • Plataforma
  • Timezone

Ejemplo de JSON

[
    {
        "type": "clientInfo",
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "Asia/Calcutta"
    }
]

Ejemplo de C#

var connector = new ConnectorClient(new Uri(context.Activity.ServiceUrl));

{
    var clientinfo = context.Activity.Entities[0];
    await context.PostAsync($"ClientInfo: clientinfo ");
}

Consulte también

Ejemplos de Bot Framework.