Mensajes en conversaciones de bot

Cada mensaje de una conversación es un Activity objeto de tipo messageType: message. Cuando un usuario envía un mensaje, Microsoft Teams publica la actividad del mensaje en el bot. Teams envía un objeto JSON al punto de conexión de mensajería del bot y Teams solo permite un punto de conexión para la mensajería. El bot examina el mensaje para determinar su tipo y responder correctamente.

Las conversaciones básicas se controlan a través del conector de Bot Framework, una única API REST. Esta API permite que el bot se comunique con Teams y otros canales. El SDK de Bot Builder proporciona las siguientes características:

• Fácil acceso al conector de Bot Framework.
• Funcionalidad para administrar el flujo y el estado de la conversación.
• Formas sencillas de incorporar servicios cognitivos, como el procesamiento de lenguaje natural (NLP).

El bot recibe mensajes de Teams mediante la Text propiedad y envía una o varias respuestas de mensaje a los usuarios.

Para obtener más información, consulte atribución de usuarios para mensajes de bot.

Recibir un mensaje

Para recibir un mensaje de texto, use la Text propiedad de un Activity objeto . En el controlador de actividades del bot, use convertir Activity del objeto de contexto para leer una solicitud de mensaje única.

En el código siguiente se muestra un ejemplo de recepción de una actividad de mensaje:

C#

• Referencia del SDK

• Referencia de código de ejemplo

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

TypeScript

• Referencia del SDK
• Referencia de código de ejemplo

export class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            // Sends a message activity to the sender of the incoming activity.
            await context.sendActivity(`Echo: '${context.activity.text}'`);
            await next();
        });
    }
}

Python

• Referencia del SDK
• Referencia de código de ejemplo

async def on_message_activity(self, turn_context: TurnContext):
    // Sends a message activity to the sender of the incoming activity.
    return await turn_context.send_activity(MessageFactory.text(f"Echo: {turn_context.activity.text}"))

JSON

{
    "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.Sending bold-italic rich text",
    "attachments": [
      {
            "contentType": "text/html",
            "content": "<div><div>Hello Teams TestBot. Sending <strong>bold</strong>-<em>italic</em> rich text.</div>\n</div>"
      } 
    ],
    "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"
}

Enviar un mensaje

Para enviar un mensaje de texto, especifique la cadena que desea enviar como actividad. En el controlador de actividad del bot, use el método del objeto de contexto turn SendActivityAsync para enviar una única respuesta de mensaje. Use el método del SendActivitiesAsync objeto para enviar varias respuestas.

En el código siguiente se muestra un ejemplo de envío de un mensaje cuando se agrega un usuario a una conversación:

C#

• Referencia del SDK

• Referencia de código de ejemplo

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

TypeScript

• Referencia del SDK
• Referencia de código de ejemplo

    this.onMembersAddedActivity(async (context, next) => {
        await Promise.all((context.activity.membersAdded || []).map(async (member) => {
            if (member.id !== context.activity.recipient.id) {
              
                // Sends an activity to the sender of the incoming activity.
                await context.sendActivity(
                    `Welcome to the team ${member.givenName} ${member.surname}`
                );
            }
        }));

        await next();
    });

Python

• Referencia del SDK
• Referencia de código de ejemplo

async def on_members_added_activity(
    self, members_added: [ChannelAccount], turn_context: TurnContext
):
    for member in teams_members_added:
        // Sends a message activity to the sender of the incoming activity.
        await turn_context.send_activity(f"Welcome your new team member {member.id}")
    return

JSON

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "conversation": {
        "id": "a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
   },
   "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My bot's reply",
    "replyToId": "1632474074231"
}

HTTP

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

{
   "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
  "members": [
    {
      "id": "{{memberID}}"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "{{tenantID}}"
    }
  }
}

Nota:

• La división de mensajes se produce cuando se envían un mensaje de texto y datos adjuntos en la misma carga de actividad. Teams divide esta actividad en dos actividades independientes, una con un mensaje de texto y la otra con datos adjuntos. A medida que se divide la actividad, no recibe el identificador de mensaje en respuesta, que se usa para actualizar o eliminar el mensaje de forma proactiva. Se recomienda enviar actividades independientes en lugar de depender de la división de mensajes.
• Los mensajes enviados se pueden localizar para proporcionar personalización. Para obtener más información, consulte Localización de la aplicación.

Los mensajes enviados entre usuarios y bots incluyen datos de canal internos dentro del mensaje. Estos datos permiten que el bot se comunique correctamente en ese canal. El SDK de Bot Builder permite modificar la estructura del mensaje.

Actualizar mensaje

Al editar o recuperar un mensaje en un chat, el bot recibe una notificación del evento de edición o de recuperación del mensaje.

Para obtener una notificación de eventos de mensaje de edición o recuperación en un bot, puede invalidar los siguientes controladores:

• Para editar: OnTeamsMessageEditAsync
• Para recuperar: OnTeamsMessageUndeleteAsync

A continuación se muestra un ejemplo de una notificación de evento de edición de mensaje cuando se edita un mensaje enviado:

C#

protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is updated"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
} 

JSON

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_PM4mubmQZsYPx7jDyLeLf_YVA9sVPV08KMAFMjJWB_EUGveb9EVDh9TslNp9qjnzEBy3kgw01Jf1Kg",
    "name":"Mike Wilber",
    "aadObjectId":"520e4d1e-2108-43ee-a092-46a9507c6200"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1pweuGJ44RkB90tiJNQ_I6g3vyuP4CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqRPB"
},
"recipient":{
    "id":"28:0d569679-gb4j-479a-b0d8-238b6e6b1149",
    "name":"TestBot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"editMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

JavaScript

Puede usar el registro de función de eventos o el método de invalidación de método para obtener notificaciones de eventos para controlar las actualizaciones de mensajes mediante bot SDK:

Registro de función de eventos:

this.onTeamsMessageEditEvent(async (context, next) => {
  let editedMessage = context.activity.text;
  await context.sendActivity(`The edited message is ${editedMessage}"`);
  next();
})

Invalidación del método:

async onTeamsMessageEdit(context) {
    let editedMessage = context.activity.text;
    await context.sendActivity(`The edited message is ${editedMessage}"`);
}

HTTP

PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

{
    "type": "message",
    "text": "This message has been updated"
}

A continuación se muestra un ejemplo de una notificación de evento de mensaje de recuperación cuando se restaura un mensaje eliminado:

C#

protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{ 
var replyActivity = MessageFactory.Text("message is undeleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
} 

JSON

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1234",
    "name":"Testbot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"undeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

JavaScript

Puede usar el registro de función de eventos o el método de invalidación de método para obtener notificaciones de eventos para controlar las actualizaciones de mensajes mediante bot SDK:

Registro de función de eventos:

this.onTeamsMessageUndeleteEvent(async (context, next) => {
    let undeletedMessage = context.activity.text;
    let messageId = context.activity.id;
        await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
    next();
})

Invalidación del método:

async onTeamsMessageUndelete(context) {
    let undeletedMessage = context.activity.text;
    let messageId = context.activity.id;
    await context.sendActivity(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
}

HTTP

PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

{
    "type": "message",
    "text": "This message has been updated"
}

Mensaje de eliminación temporal

Al eliminar temporalmente un mensaje en un chat, el bot recibe una notificación del evento de mensaje de eliminación temporal.

Para obtener una notificación de eventos de mensaje de eliminación temporal en un bot, puede invalidar el OnTeamsMessageSoftDeleteAsync controlador.

A continuación se muestra un ejemplo de una notificación de eventos de mensaje de eliminación temporal cuando se elimina temporalmente un mensaje:

C#

protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is soft deleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
} 

JSON

{
"type":"messageDelete",
"timestamp":"2022-10-28T17:19:43.1612052Z",
"localTimestamp":"2022-10-28T10:19:43.1612052-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1235",
    "name":"Testbot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"softDeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

JavaScript

Puede usar el registro de función de eventos o el método de invalidación de método para obtener notificaciones de eventos para controlar las actualizaciones de mensajes mediante bot SDK:

Registro de función de eventos:

this.onTeamsMessageSoftDeleteEvent(async (context, next) => {
    let messageId = context.activity.id;
      await context.sendActivity(`The deleted message id is ${messageId}`);
    next();
})

Invalidación del método:

async onTeamsMessageSoftDelete(context) {
    let messageId = context.activity.id;
    await context.sendActivity(`The deleted message id is ${messageId}`);
}

Envío de acciones sugeridas

Las acciones sugeridas permiten al bot presentar botones que el usuario puede seleccionar para proporcionar entrada. Las acciones sugeridas mejoran la experiencia del usuario al permitir que el usuario responda a una pregunta o haga una elección con la selección de un botón, en lugar de escribir una respuesta con un teclado. Cuando el usuario selecciona un botón, permanece visible y accesible en las tarjetas enriquecidas, pero no para las acciones sugeridas. Esto impide que el usuario seleccione botones obsoletos dentro de una conversación.

Para agregar acciones sugeridas a un mensaje, establezca la suggestedActions propiedad de un objeto de actividad para especificar la lista de objetos de acción de tarjeta que representan los botones que se van a presentar al usuario. Para más información, vea sugestedActions.

A continuación se muestra un ejemplo de implementación y experiencia de acciones sugeridas:

"suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Action 1",
        "value": "Action 1"
      },
      {
        "type": "imBack",
        "title": "Action 2",
        "value": "Action 2"
      }
    ],
    "to": [<list of recepientIds>]
  }

A continuación se muestra un ejemplo de acciones sugeridas:

Nota:

• SuggestedActions solo se admiten para bots de chat uno a uno y mensajes basados en texto y no para tarjetas adaptables o datos adjuntos.
• imBack es el único tipo de acción admitido y Teams muestra hasta tres acciones sugeridas.

Datos del canal de Teams

El channelData objeto contiene información específica de Teams y es un origen definitivo para los identificadores de equipo y canal. Opcionalmente, puede almacenar en caché y usar estos identificadores como claves para el almacenamiento local. en TeamsActivityHandler el SDK extrae información importante del channelData objeto para que sea accesible. Sin embargo, siempre puede acceder a los datos originales desde el turnContext objeto .

El channelData objeto no se incluye en los mensajes de las conversaciones personales, ya que tienen lugar fuera de un canal.

Un objeto típico channelData de una actividad enviada al bot contiene la siguiente información:

• eventType: el tipo de evento de Teams solo se pasa en los casos de eventos de modificación del canal.
• tenant.id: Microsoft Azure Active Directory identificador de inquilino (Azure AD) pasado en todos los contextos.
• team: solo se pasa en contextos de canal, no en chat personal.
  • id: GUID para el canal.
  • name: nombre del equipo pasado solo en los casos de eventos de cambio de nombre del equipo.
• channel: solo se pasa en contextos de canal, cuando se menciona el bot o para eventos en canales de teams, donde se ha agregado el bot.
  • id: GUID para el canal.
  • name: el nombre del canal solo se pasa en los casos de eventos de modificación del canal.
• channelData.teamsTeamId:Obsoleto. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.
• channelData.teamsChannelId:Obsoleto. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.

Ejemplo de objeto channelData (evento channelCreated)

En el código siguiente se muestra un ejemplo del objeto channelData:

"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"
    }
}

Contenido del mensaje

Los mensajes recibidos o enviados al bot pueden incluir diferentes tipos de contenido de mensaje.

Formato	De usuario a bot	De bot a usuario	Notas
Texto enriquecido	✔️	✔️	El bot puede enviar texto enriquecido, imágenes y tarjetas. Los usuarios pueden enviar texto enriquecido e imágenes al bot.
Imágenes	✔️	✔️	Máximo 1024 × 1024 píxeles y 1 MB en formato PNG, JPEG o GIF. No admite el GIF animado.
Tarjetas	❌	✔️	Consulte Referencia de tarjetas de Teams para obtener las tarjetas admitidas.
Emojis	✔️	✔️	Teams admite actualmente emojis a través de UTF-16, como U+1F600 para la cara sonriente.

Mensajes de imagen

Para mejorar el mensaje, puede incluir imágenes como datos adjuntos a ese mensaje. Para obtener más información sobre los datos adjuntos, vea Agregar datos adjuntos multimedia a los mensajes.

Las imágenes pueden tener como máximo 1024 × 1024 píxeles y 1 MB en formato PNG, JPEG o GIF. No se admite el uso de un GIF animado.

Especifique el alto y el ancho de cada imagen mediante XML. En Markdown, el tamaño predeterminado de la imagen es 256×256. Por ejemplo:

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

Un bot conversacional puede incluir tarjetas adaptables que simplifican los flujos de trabajo empresariales. Las tarjetas adaptables ofrecen texto personalizable enriquecido, voz, imágenes, botones y campos de entrada.

Tarjetas adaptables

Las tarjetas adaptables se pueden crear en un bot y mostrarse en varias aplicaciones, como Teams, su sitio web, etc. Para obtener más información, vea Tarjetas adaptables.

En el código siguiente se muestra un ejemplo de envío de una tarjeta adaptable simple:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Comentarios de finalización de formularios

Puede generar comentarios de finalización de formularios mediante una tarjeta adaptable. El mensaje de finalización del formulario aparece en Tarjetas adaptables al enviar una respuesta al bot. El mensaje puede ser de dos tipos, error o éxito:

• Error: Cuando se produce un error en una respuesta enviada al bot, se produce un error, aparece el mensaje Volver a intentarlo .

  

• Correcto: cuando una respuesta enviada al bot se realiza correctamente, aparece la respuesta que se envió al mensaje de la aplicación .

  

  Puede seleccionar Cerrar o cambiar el chat para descartar el mensaje.

  Si no desea mostrar el mensaje correcto, establezca el atributo hidetrue en en la msTeamsfeedback propiedad . A continuación se muestra un ejemplo:

     "content": {
         "type": "AdaptiveCard",
         "title": "Card with hidden footer messages",
         "version": "1.0",
         "actions": [
         {
             "type": "Action.Submit",
             "title": "Submit",
             "msTeams": {
                 "feedback": {
                 "hide": true
                 }
             }
         }
         ]
     } 
  

Para obtener más información sobre tarjetas y tarjetas en bots, consulte la documentación de las tarjetas.

Adición de notificaciones al mensaje

Hay dos maneras de enviar una notificación desde la aplicación:

• Al establecer la propiedad en el Notification.Alert mensaje del bot.
• Mediante el envío de una notificación de fuente de actividad mediante el Graph API.

Puede agregar notificaciones al mensaje mediante la Notification.Alert propiedad . Las notificaciones alertan a los usuarios de un evento en la aplicación, como nuevas tareas, menciones o comentarios. Estas alertas están relacionadas con lo que los usuarios están trabajando o con lo que deben examinar insertando un aviso en su fuente de actividad. Para que las notificaciones se desencadenen desde el mensaje del bot, establezca la TeamsChannelData propiedad objects Notification.Alert en true. Si se genera una notificación depende de la configuración de Teams del usuario individual y no puede invalidar esta configuración.

Si desea generar una notificación arbitraria sin enviar un mensaje al usuario, puede usar el Graph API. Para obtener más información, consulte cómo enviar notificaciones de fuente de actividad mediante Graph API junto con los procedimientos recomendados.

Nota:

El campo Resumen muestra cualquier texto del usuario como mensaje de notificación en la fuente.

En el código siguiente se muestra un ejemplo de cómo agregar notificaciones al mensaje:

C#

• Referencia del SDK
• Referencia de código de ejemplo

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Returns a simple text message.
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(message);
}

TypeScript

• Referencia del SDK

• Referencia de código de ejemplo

this.onMessage(async (turnContext, next) => {
    let message = MessageFactory.text("You'll get a notification, if you've turned them on.");
    teamsNotifyUser(message);
    // Sends an activity to the sender of the incoming activity.
    await turnContext.sendActivity(message);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Python

Referencia del SDK

async def on_message_activity(self, turn_context: TurnContext):
    message = MessageFactory.text("You'll get a notification, if you've turned them on.")
    teams_notify_user(message)
    // Sends an activity to the sender of the incoming activity.
    await turn_context.send_activity(message)

JSON

{
  "type": "message",
  "timestamp": "2017-04-24T21:46:00.9663655Z",
  "localTimestamp": "2017-04-24T14:46:00.9663655-07:00",
  "serviceUrl": "https://callback.com",
  "channelId": "msteams",
  "from": {
    "id": "28:e4fda94a-4b80-40eb-9bf0-6314491bc793",
    "name": "The bot"
  },
  "conversation": {
    "id": "a:1pL6i0oY3C0K8oAj8"
  },
  "recipient": {
    "id": "29:1rsVJmSSFMScF0YFyCXpvNWlo",
    "name": "User"
  },
  "text": "John Phillips assigned you a weekly todo",
  "summary": "Don't forget to meet with Marketing next week",
  "channelData": {
    "notification": {
      "alert": true
    }
  },
  "replyToId": "1493070356924"
}

Códigos de estado de las API conversacionales del bot

Asegúrese de controlar estos errores correctamente en la aplicación de Teams. En la tabla siguiente se enumeran los códigos de error y las descripciones con las que se generan los errores:

Código de estado	Código de error y valores de mensaje	Descripción	Solicitud de reintento	Acción del desarrollador
400	Código: Bad Argument Mensaje: *específico del escenario	Carga de solicitud no válida proporcionada por el bot. Consulte el mensaje de error para obtener detalles específicos.	No	Vuelva a evaluar la carga de la solicitud para los errores. Compruebe el mensaje de error devuelto para obtener más información.
401	Código: BotNotRegistered Mensaje: No se encontró ningún registro para este bot.	No se encontró el registro de este bot.	No	Compruebe el identificador y la contraseña del bot. Asegúrese de que el identificador del bot (id. de AAD) está registrado en el Portal para desarrolladores de Teams o mediante el registro del canal de bot de Azure en Azure con el canal "Teams" habilitado.
403	Código: BotDisabledByAdmin Mensaje: El administrador de inquilinos deshabilitó este bot	El administrador de inquilinos ha bloqueado las interacciones entre el usuario y la aplicación del bot. El administrador de inquilinos debe permitir la aplicación para el usuario dentro de las directivas de la aplicación. Para obtener más información, consulte Directivas de aplicación.	No	Deje de publicar en la conversación hasta que un usuario inicie explícitamente la interacción con el bot en la conversación, lo que indica que el bot ya no está bloqueado.
403	Código: BotNotInConversationRoster Mensaje: El bot no forma parte de la lista de conversaciones.	El bot no forma parte de la conversación. La aplicación debe volver a instalarse en la conversación.	No	Antes de intentar enviar otra solicitud de conversación, espere un installationUpdate evento, lo que indica que el bot se ha agregado de nuevo.
403	Código: ConversationBlockedByUser Mensaje: El usuario bloqueó la conversación con el bot.	El usuario ha bloqueado el bot en un chat personal o un canal a través de la configuración de moderación.	No	Elimine la conversación de la memoria caché. Deje de intentar publicar en las conversaciones hasta que un usuario inicie explícitamente la interacción con el bot en la conversación, lo que indica que el bot ya no está bloqueado.
403	Código: InvalidBotApiHost Mensaje: Host de api de bot no válido. Para los inquilinos de GCC, llame a https://smba.infra.gcc.teams.microsoft.com.	El bot llamó al punto de conexión de API público para una conversación que pertenece a un inquilino de GCC.	No	Actualice la dirección URL del servicio de la conversación a y vuelva a https://smba.infra.gcc.teams.microsoft.com intentar la solicitud.
403	Código: NotEnoughPermissions Mensaje: *específico del escenario	El bot no tiene los permisos necesarios para realizar la acción solicitada.	No	Determine la acción necesaria del mensaje de error.
404	Código: ActivityNotFoundInConversation Mensaje: No se encontró la conversación.	No se encontró el identificador de mensaje proporcionado en la conversación. El mensaje no existe o se ha eliminado.	No	Compruebe si el identificador de mensaje enviado es un valor esperado. Quite el identificador si se ha almacenado en caché.
404	Código: ConversationNotFound Mensaje: No se encontró la conversación.	No se encontró la conversación, ya que no existe o se ha eliminado.	No	Compruebe si el identificador de conversación enviado es un valor esperado. Quite el identificador si se ha almacenado en caché.
412	Código: PreconditionFailed Mensaje: Error de condición previa, inténtelo de nuevo.	Error de condición previa en una de nuestras dependencias debido a varias operaciones simultáneas en la misma conversación.	Yes	Vuelva a intentarlo con retroceso exponencial.
413	Código: MessageSizeTooBig Mensaje: tamaño del mensaje demasiado grande.	El tamaño de la solicitud entrante era demasiado grande. Para obtener más información, consulte Dar formato a los mensajes del bot.	No	Reduzca el tamaño de la carga.
429	Código: Throttled Mensaje: Demasiadas solicitudes. También devuelve cuándo volver a intentarlo después.	El bot envió demasiadas solicitudes. Para obtener más información, consulte límite de velocidad.	Yes	Vuelva a intentar usar el Retry-After encabezado para determinar el tiempo de retroceso.
500	Código: ServiceError Mensaje: *varios	Error interno del servidor.	No	Informe del problema en la comunidad de desarrolladores.
502	Código: ServiceError Mensaje: *varios	Problema de dependencia de servicio.	Yes	Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.
503		El servicio no está disponible.	Yes	Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.
504		Tiempo de espera de la puerta de enlace.	Yes	Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.

Guía de reintento de códigos de estado

La guía general de reintentos para cada código de estado se muestra en la tabla siguiente; el bot debe evitar reintentar los códigos de estado que no se especifican:

Código de estado	Estrategia de reintento
403	Vuelva a intentarlo llamando a la API https://smba.infra.gcc.teams.microsoft.com de GCC para InvalidBotApiHost.
412	Vuelva a intentarlo con el retroceso exponencial.
429	Vuelva a intentar usar Retry-After el encabezado para determinar el tiempo de espera en segundos y entre solicitudes, si está disponible. De lo contrario, vuelva a intentar usar el retroceso exponencial con el identificador de subproceso, si es posible.
502	Vuelva a intentarlo con el retroceso exponencial.
503	Vuelva a intentarlo con el retroceso exponencial.
504	Vuelva a intentarlo con el retroceso exponencial.

Ejemplo de código

Ejemplo de nombre	Descripción	Node.js	.NETCore	Python	.NET	Manifiesto
Bot de conversación de Teams	Esta aplicación de ejemplo muestra cómo usar diferentes eventos de conversación de bot disponibles en bot framework v4.	View	View	Ver	ND
Localización de aplicaciones de Teams	En este ejemplo se muestra la localización de aplicaciones de Teams mediante bot y pestaña.	View	ND	ND	Ver
Actualizar y eliminar mensaje	En este ejemplo se muestra cómo capturar eventos para actualizar y eliminar mensajes en el chat mediante el bot.	View	View	ND	ND	View

Paso siguiente

Menús de comandos del bot

Consulte también

• Enviar mensajes proactivos
• Suscribirse a eventos de conversación
• Enviar y recibir archivos a través del bot
• Envío del identificador de inquilino y el identificador de conversación a los encabezados de solicitud del bot
• Localizar la aplicación
• Controladores de actividad de bots