Crear y enviar mensajes

  • Artículo

Para crear y enviar mensajes accionables, use un webhook entrante o un conector de Microsoft 365. Sin embargo, los mensajes accionables solo son accesibles para los usuarios con una licencia de Exchange Online.

Crear mensajes que requieren acción

Los mensajes que requieren acción incluyen seis botones visibles en la tarjeta. Cada botón se define en la potentialAction propiedad del mensaje mediante ActionCard acciones, cada una con un tipo de entrada, un campo de texto, un selector de fechas o una lista de opciones múltiples. Cada ActionCard tiene asociada una acción, por ejemplo HttpPOST.

Las tarjetas de conector admiten las siguientes acciones:

  • ActionCard: presenta uno o varios tipos de entrada y acciones asociadas.
  • HttpPOST: envía la solicitud POST a una dirección URL.
  • OpenUri: abre el URI en un explorador o aplicación independiente. Opcionalmente, tiene como destino diferentes URI basados en sistemas operativos.

La acción ActionCard admite tres tipos de entrada:

  • TextInput: campo de texto de una o varias líneas con un límite de longitud opcional.
  • DateInput: selector de fecha con un selector de hora opcional.
  • MultichoiceInput: una lista enumerada de opciones que ofrecen una sola selección o varias selecciones.

MultichoiceInput admite una propiedad style que controla si inicialmente la lista se muestra totalmente expandida. El valor predeterminado de style depende del valor de isMultiSelect, como se indica a continuación:

isMultiSelect Predeterminado style
false o no especificado compact
true expanded

Para mostrar la lista de selección múltiple en el estilo compacto, debe especificar "isMultiSelect": true y "style": true.

Para más información sobre las acciones de tarjeta de conector, vea Acciones.

Nota:

  • Especificar compact para la propiedad style en Microsoft Teams es igual que especificar normal para la propiedad style en Microsoft Outlook.
  • Para la acción HttpPOST, el token de usuario se incluye con las solicitudes. Este token incluye la identidad Microsoft Entra del usuario de Microsoft 365 que realizó la acción.

Enviar un mensaje a través del webhook o conector entrante para Grupos de Microsoft 365

Para enviar un mensaje a través del webhook o conector entrante para Grupos de Microsoft 365, publique una carga JSON en la dirección URL del webhook. Esta carga debe tener el formato de una tarjeta de conector para Grupos de Microsoft 365.

También puede usar este JSON para crear tarjetas que contengan entradas enriquecidas, como entrada de texto, selección múltiple o selección de una fecha y hora. El código que genera la tarjeta y publica en la dirección URL de webhook se puede ejecutar en cualquier servicio hospedado. Estas tarjetas se definen como parte de mensajes accionables y también se admiten en tarjetas usadas en bots y extensiones de mensajes de Teams.

Ejemplo de mensaje de conector

Un ejemplo de mensaje de conector es el siguiente:

{
    "@type": "MessageCard",
    "@context": "http://schema.org/extensions",
    "themeColor": "0076D7",
    "summary": "Larry Bryant created a new task",
    "sections": [{
        "activityTitle": "Larry Bryant created a new task",
        "activitySubtitle": "On Project Tango",
        "activityImage": "https://adaptivecards.io/content/cats/3.png",
        "facts": [{
            "name": "Assigned to",
            "value": "Unassigned"
        }, {
            "name": "Due date",
            "value": "Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)"
        }, {
            "name": "Status",
            "value": "Not started"
        }],
        "markdown": true
    }],
    "potentialAction": [{
        "@type": "ActionCard",
        "name": "Add a comment",
        "inputs": [{
            "@type": "TextInput",
            "id": "comment",
            "isMultiline": false,
            "title": "Add a comment here for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Add comment",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "ActionCard",
        "name": "Set due date",
        "inputs": [{
            "@type": "DateInput",
            "id": "dueDate",
            "title": "Enter a due date for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "OpenUri",
        "name": "Learn More",
        "targets": [{
            "os": "default",
            "uri": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "ActionCard",
        "name": "Change status",
        "inputs": [{
            "@type": "MultichoiceInput",
            "id": "list",
            "title": "Select a status",
            "isMultiSelect": "false",
            "choices": [{
                "display": "In Progress",
                "value": "1"
            }, {
                "display": "Active",
                "value": "2"
            }, {
                "display": "Closed",
                "value": "3"
            }]
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }]
}

La siguiente imagen es un ejemplo de la tarjeta de mensaje del conector en un canal:

Captura de pantalla que muestra un ejemplo de una tarjeta del conector en un canal.

Envío de mensajes mediante cURL y PowerShell

Para publicar un mensaje en el webhook con cURL, siga estos pasos:

  1. Instale cURL desde el sitio web de cURL.

  2. Desde la línea de comandos, escriba el siguiente comando cURL:

    // on macOS or Linux
curl -H 'Content-Type: application/json' -d '{"text": "Hello World"}' <YOUR WEBHOOK URL>

    // on Windows
curl.exe -H "Content-Type:application/json" -d "{'text':'Hello World'}" <YOUR WEBHOOK URL>

    Nota:

    Si el envío se realiza correctamente, debería ver un resultado de salida 1 por curl.

  3. Compruebe la nueva tarjeta publicada en el cliente de Teams.

Enviar tarjetas adaptables con un webhook entrante

Nota:

Para enviar tarjetas adaptables con texto o una imagen codificada en Base64 a través de un webhook entrante, siga estos pasos:

  1. Configurar un webhook personalizado en Teams.
  2. Cree un archivo JSON de tarjeta adaptable con el código siguiente:
    {
       "type":"message",
       "attachments":[
          {
             "contentType":"application/vnd.microsoft.card.adaptive",
             "contentUrl":null,
             "content":{
                "$schema":"http://adaptivecards.io/schemas/adaptive-card.json",
                "type":"AdaptiveCard",
                "version":"1.2",
                "body":[
                    {
                    "type": "TextBlock",
                    "text": "For Samples and Templates, see [https://adaptivecards.io/samples](https://adaptivecards.io/samples)"
                    }
                ]
             }
          }
       ]
    }

Las propiedades del archivo JSON de tarjeta adaptable son las siguientes:

  • El campo "type" debe ser "message".
  • La matriz "attachments" contiene un conjunto de objetos de tarjeta.
  • El campo "contentType" debe establecerse en tipo de tarjeta adaptable.
  • El objeto "content" es la tarjeta con formato JSON.

  1. Pruebe la tarjeta adaptable con Postman:

    1. Pruebe la tarjeta adaptable con Postman para enviar una solicitud POST a la dirección URL, creada para configurar el webhook entrante.
    2. Pegue el archivo JSON en el cuerpo de la solicitud y vea el mensaje de la tarjeta adaptable en Teams.

Sugerencia

Use plantillas y ejemplos de código de tarjeta adaptable para probar el cuerpo de la solicitud POST.

Limitación de velocidad para conectores

Los límites de velocidad de la aplicación controlan el tráfico que puede generar un conector o un webhook entrante en un canal. Teams realiza un seguimiento de las solicitudes mediante una ventana de velocidad fija y un contador incremental medido en segundos. Si se realizan más de cuatro solicitudes en un segundo, la conexión de cliente se limita hasta que la ventana se actualiza mientras dure la tasa fija.

Umbrales de transacciones por segundo

En la tabla siguiente se proporcionan los detalles de la transacción basada en el tiempo:

Tiempo en segundos Número máximo de solicitudes permitidas
1 4
30 60
3600 100
7200 150
86400 1800

Nota:

Una lógica de reintento con interrupción exponencial puede mitigar la restricción de velocidad en casos en que las solicitudes superen los límites en un segundo. Consulte las respuestas HTTP 429 para evitar superar los límites de velocidad.

// Please note that response body needs to be extracted and read 
// as Connectors do not throw 429s
try
{
    // Perform Connector POST operation     
    var httpResponseMessage = await _client.PostAsync(IncomingWebhookUrl, new StringContent(content));
    // Read response content
    var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();
    if (responseContent.Contains("Microsoft Teams endpoint returned HTTP error 429")) 
    {
        // initiate retry logic
    }
}

Estos límites tienen el propósito de reducir el correo no deseado en un canal con un conector y garantizan una experiencia óptima para los usuarios.

Vea también