Implement channel-specific functionality (Implementar funcionalidades específicas de um canal)

  • Artigo

APLICA-SE A: SDK v4

Alguns canais fornecem funcionalidades que não podem ser implementadas apenas com texto de mensagem e anexos. Para implementar uma funcionalidade específica de canais, pode passar metadados nativos para um canal na propriedade de dados de canal do objeto de atividade. Por exemplo, o seu bot pode usar a propriedade de dados do canal para instruir o Telegram a enviar um autocolante ou a instruir o Office365 a enviar um e-mail.

Este artigo descreve como usar a propriedade de dados de canal de uma mensagem para implementar esta funcionalidade específica do canal:

Canal Funcionalidade
E-mail Envie e receba um e-mail que contenha metadados de corpo, sujeito e importância.
Facebook Envie notificações do Facebook de forma nativa.
LINHA Envie uma mensagem que implementa tipos de mensagens específicas da LINE.
Slack Envie mensagens de fidelidade completa.
Teams Handle @-mentions em mensagens Microsoft Teams.
Telegram Execute ações específicas do Telegram, tais como partilhar um memorando de voz ou um autocolante.

Nota

O valor da propriedade de dados de canal de um objeto de atividade é um objeto JSON. Assim, os exemplos deste artigo mostram o formato esperado da channelData propriedade JSON em vários cenários. Para criar um objeto JSON utilizando .NET, utilize a JObject classe (.NET).

Crie uma mensagem de e-mail personalizada

Para criar uma mensagem de e-mail personalizada, desajei a propriedade da atividade channelData a um objeto JSON que contenha as seguintes propriedades:

Propriedade Descrição
bccRecipients Um ponto e vírgula (;) cadeia delimitada de endereços de e-mail para adicionar ao campo Bcc (cópia cega de carbono) da mensagem.
ccRecipients Um ponto e vírgula (;) cadeia delimitada de endereços de e-mail para adicionar ao campo Cc (cópia de carbono) da mensagem.
htmlCorpo Um documento HTML que especifica o corpo da mensagem de e-mail. Consulte a documentação do canal para obter informações sobre elementos e atributos HTML suportados.
importância O nível de importância do e-mail. Valores válidos são altos, normais e baixos. O valor predefinido é normal.
toRecipients Um ponto e vírgula (;) cadeia delimitada de endereços de e-mail para adicionar ao campo De mensagem.

As mensagens de saída e de entrada entre o utilizador e o bot podem ter uma channelData atividade que contenha um objeto JSON cujas propriedades estão especificadas na tabela anterior. O snippet abaixo mostra um exemplo da channelData propriedade para uma mensagem de e-mail personalizada, do bot ao utilizador.

{
    "type": "ActivityTypes.Message",
    "locale": "en-Us",
    "channelID": "email",
    "fromName": { "id": "mybot@mydomain.com", "name": "My bot"},
    "recipientName": { "id": "joe@otherdomain.com", "name": "Joe Doe"},
    "conversation": { "id": "123123123123", "topic": "awesome chat" },
    "channelData":
    {
        "htmlBody": "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome.</body></html>",
        "importance": "high",
        "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com",
    }
}

Criar uma notificação do Facebook

Para criar uma notificação do Facebook, desajei a propriedade de dados de canal do objeto de atividade a um objeto JSON que especifica estas propriedades:

Propriedade Descrição
notification_type O tipo de notificação, como REGULAR, SILENT_PUSH ou NO_PUSH.
anexo Um anexo que especifica uma imagem, vídeo ou outro tipo multimédia, ou um anexo de modelo, como um recibo.

Nota

Para mais detalhes sobre o notification_type formato e conteúdo do imóvel e attachment propriedade, consulte a documentação da API do Facebook.

Este snippet mostra um exemplo da channelData propriedade para um anexo de recibo do Facebook.

"channelData": {
    "notification_type": "NO_PUSH",
    "attachment": {
        "type": "template"
        "payload": {
            "template_type": "receipt",
            //...
        }
    }
}

Criar uma mensagem LINE

Para criar uma mensagem que implemente tipos de mensagens específicas da LINE (tais como adesivos, modelos ou tipos de ação específicos da LINHA, como abrir a câmara telefónica), desajei a propriedade de dados do objeto de atividade a um objeto JSON que especifica tipos de mensagens LINE e tipos de ação.

Propriedade Descrição
tipo O nome do tipo de ação/mensagem LINE

Estes tipos de mensagens LINE são suportados:

  • Adesivo
  • Imagemap
  • Modelo (Botão, confirmar, carrossel)
  • Flex

Estas ações LINE podem ser especificadas no campo de ação do objeto JSON do tipo de mensagem:

  • Pós-volta
  • Mensagem
  • URI
  • Datetimerpicker
  • Câmara
  • Imagens da câmara
  • Localização

Para obter mais informações sobre estes métodos LINE e seus parâmetros, consulte a documentação da API da API da LINHA Bot.

Este snippet mostra um exemplo de uma channelData propriedade que especifica um tipo ButtonTemplate de mensagem de canal e três tipos de ação: "camera", "cameraRoll" e "datetimepicker".

"channelData": {
    "type": "template",
    "altText": "This is a buttons template",
    "template": {
        "type": "buttons",
        "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
        "imageAspectRatio": "rectangle",
        "imageSize": "cover",
        "imageBackgroundColor": "#FFFFFF",
        "title": "Menu",
        "text": "Please select",
        "defaultAction": {
            "type": "uri",
            "label": "View detail",
            "uri": "http://example.com/page/123"
        },
        "actions": [{
                "type": "cameraRoll",
                "label": "Camera roll"
            },
            {
                "type": "camera",
                "label": "Camera"
            },
            {
                "type": "datetimepicker",
                "label": "Select date",
                "data": "storeId=12345",
                "mode": "datetime",
                "initial": "2017-12-25t00:00",
                "max": "2018-01-24t23:59",
                "min": "2017-12-25t00:00"
            }
        ]
    }
}

Crie uma mensagem slack de fidelidade completa

Para criar uma mensagem slack de fidelidade completa, desajei a propriedade de dados do objeto de atividade a um objeto JSON que especifica:

Nota

Para suportar botões em mensagens Slack, tem de ativar mensagens interativas quando ligar o bot ao canal Slack.

Este snippet mostra um exemplo da channelData propriedade para uma mensagem slack personalizada.

"channelData": {
   "text": "Now back in stock! :tada:",
   "attachments": [
        {
            "title": "The Further Adventures of Slackbot",
            "author_name": "Stanford S. Strickland",
            "author_icon": "https://api.slack.com/img/api/homepage_custom_integrations-2x.png",
            "image_url": "http://i.imgur.com/OJkaVOI.jpg?1"
        },
        {
            "fields": [
                {
                    "title": "Volume",
                    "value": "1",
                    "short": true
                },
                {
                    "title": "Issue",
                    "value": "3",
                    "short": true
                }
            ]
        },
        {
            "title": "Synopsis",
            "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy..."
        },
        {
            "fallback": "Would you recommend it to customers?",
            "title": "Would you recommend it to customers?",
            "callback_id": "comic_1234_xyz",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "recommend",
                    "text": "Recommend",
                    "type": "button",
                    "value": "recommend"
                },
                {
                    "name": "no",
                    "text": "No",
                    "type": "button",
                    "value": "bad"
                }
            ]
        }
    ]
}

Quando um utilizador clica num botão dentro de uma mensagem Slack, o seu bot receberá uma mensagem de resposta na qual a propriedade de dados do canal é povoada com um payload objeto JSON. O payload objeto especifica o conteúdo da mensagem original, identifica o botão que foi clicado e identifica o utilizador que clicou no botão.

Este snippet mostra um exemplo da channelData propriedade na mensagem que um bot recebe quando um utilizador clica num botão na mensagem Slack.

"channelData": {
    "payload": {
        "actions": [
            {
                "name": "recommend",
                "value": "yes"
            }
        ],
        //...
        "original_message": "{...}",
        "response_url": "https://hooks.slack.com/actions/..."
    }
}

O seu bot pode responder a esta mensagem da forma normal, ou pode publicar a sua resposta diretamente no ponto final especificado pela payload propriedade do response_url objeto. Para obter informações sobre quando e como publicar uma resposta ao response_url, consulte Botões Slack.

Pode criar botões dinâmicos utilizando o seguinte JSON:

{
    "text": "Would you like to play a game ? ",
    "attachments": [
        {
            "text": "Choose a game to play!",
            "fallback": "You are unable to choose a game",
            "callback_id": "wopr_game",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "game",
                    "text": "Chess",
                    "type": "button",
                    "value": "chess"
                },
                {
                    "name": "game",
                    "text": "Falken's Maze",
                    "type": "button",
                    "value": "maze"
                },
                {
                    "name": "game",
                    "text": "Thermonuclear War",
                    "style": "danger",
                    "type": "button",
                    "value": "war",
                    "confirm": {
                        "title": "Are you sure?",
                        "text": "Wouldn't you prefer a good game of chess?",
                        "ok_text": "Yes",
                        "dismiss_text": "No"
                    }
                }
            ]
        }
    ]
}

Para criar menus interativos, utilize o seguinte JSON:

{
    "text": "Would you like to play a game ? ",
    "response_type": "in_channel",
    "attachments": [
        {
            "text": "Choose a game to play",
            "fallback": "If you could read this message, you'd be choosing something fun to do right now.",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "callback_id": "game_selection",
            "actions": [
                {
                    "name": "games_list",
                    "text": "Pick a game...",
                    "type": "select",
                    "options": [
                        {
                            "text": "Hearts",
                            "value": "menu_id_hearts"
                        },
                        {
                            "text": "Bridge",
                            "value": "menu_id_bridge"
                        },
                        {
                            "text": "Checkers",
                            "value": "menu_id_checkers"
                        },
                        {
                            "text": "Chess",
                            "value": "menu_id_chess"
                        },
                        {
                            "text": "Poker",
                            "value": "menu_id_poker"
                        },
                        {
                            "text": "Falken's Maze",
                            "value": "menu_id_maze"
                        },
                        {
                            "text": "Global Thermonuclear War",
                            "value": "menu_id_war"
                        }
                    ]
                }
            ]
        }
    ]
}

Adicione um bot às equipas

Bots adicionados a uma equipa tornam-se outro membro da equipa, que pode fazer @mentioned parte da conversa. Na verdade, os bots só recebem mensagens quando estão @mentioned, por isso outras conversas no canal não são enviadas para o bot. Para obter mais informações, consulte conversas de chat do Channel e do Grupo com um bot da Microsoft Teams.

Como os bots num grupo ou canal só respondem quando são mencionados (@botname) numa mensagem, cada mensagem recebida por um bot num canal de grupo contém o seu próprio nome, e deve garantir que a sua mensagem de análise lida com isso. Além disso, os bots podem analisar outros utilizadores mencionados e mencionar os utilizadores como parte das suas mensagens.

Verificar e despir @bot menção

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

Importante

Não é recomendado adicionar um bot pela GUID, para qualquer outra coisa que não seja fins de teste. Fazê-lo limita severamente a funcionalidade de um bot. Os bots em produção devem ser adicionados às Equipas como parte de uma aplicação. Consulte Criar um bot e teste e depurar o seu bot Microsoft Teams.

Criar uma mensagem telegrama

Para criar uma mensagem que implemente ações específicas do Telegram, como a partilha de um memorando de voz ou de um autocolante, desajei a propriedade de dados do objeto de atividade a um objeto JSON que especifica estas propriedades:

Propriedade Descrição
método O método da API do Telegram Bot para ligar.
parâmetros Os parâmetros do método especificado.

Estes métodos telegrama são apoiados:

  • respostaInlineQuery
  • editMessageCaption
  • editMessageReplyMarkup
  • editMessageText
  • forwardMessage
  • banChatMember
  • sendAudio
  • sendChatAction
  • enviarContact
  • enviarDocumento
  • envioLocalização
  • enviar Mensagens
  • sendPhoto
  • sendSticker
  • sendVenue
  • sendVídeo
  • sendVoice
  • unbanChatMember

Para mais detalhes sobre estes métodos do Telegram e seus parâmetros, consulte a documentação da API do Telegram Bot.

Nota

  • O chat_id parâmetro é comum a todos os métodos do Telegram. Se não especificar chat_id como parâmetro, a estrutura fornecerá o ID para si.
  • Em vez de passar o conteúdo do ficheiro em linha, especifique o ficheiro utilizando um URL e um tipo de mídia como mostrado no exemplo abaixo.
  • Dentro de cada mensagem que o seu bot recebe do canal Telegram, a ChannelData propriedade incluirá a mensagem que o seu bot enviou anteriormente.

Este snippet mostra um exemplo de uma channelData propriedade que especifica um único método Telegram:

"channelData": {
    "method": "sendSticker",
    "parameters": {
        "sticker": {
            "url": "https://domain.com/path/gif",
            "mediaType": "image/gif",
        }
    }
}

Este snippet mostra um exemplo de uma channelData propriedade que especifica uma variedade de métodos telegrama:

"channelData": [
    {
        "method": "sendSticker",
        "parameters": {
            "sticker": {
                "url": "https://domain.com/path/gif",
                "mediaType": "image/gif",
            }
        }
    },
    {
        "method": "sendMessage",
        "parameters": {
            "text": "<b>This message is HTML formatted.</b>",
            "parse_mode": "HTML"
        }
    }
]

Quando um método Telegram é implementado, o seu bot receberá uma mensagem de resposta na qual a propriedade de dados do canal é povoada com um objeto JSON. Este objeto de resposta especifica o conteúdo da mensagem original, incluindo um update_id e, no máximo, um parâmetro opcional. Para obter informações sobre a receção de respostas recebidas, consulte obter atualizações.

Este snippet mostra um exemplo da channelData propriedade na mensagem que um bot recebe quando uma pesquisa é criada:

"channelData": {
    "update_id": 43517575,
    "message": {
        "message_id": 618,
        "from": {
            "id": 803613355,
            "is_bot": false,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "language_code": "en"
        },
        "chat": {
            "id": 803613355,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "type": "private"
        },
        "date": 1582577834,
        "poll": {
        "id": "5089525250643722242",
        "question": "How to win?",
        "options": [
            {
                "text": "Be the best",
                "voter_count": 0
            },
            {
                "text": "Help those in need",
                "voter_count": 0
            },
            {
                "text": "All of the above",
                "voter_count": 0
            }
        ],
        "total_voter_count": 0,
        "is_closed": false,
        "is_anonymous": true,
        "type": "regular",
        "allows_multiple_answers": false
        }
    }
}

Recursos adicionais