Implementar a funcionalidade específica do canal

Artigo
03/08/2023

APLICA-SE A: SDK v4

Alguns canais fornecem recursos que não podem ser implementados apenas com texto de mensagem e anexos. Para implementar funcionalidades específicas do canal, passe metadados nativos para um canal na propriedade dados do canal do objeto da atividade. Por exemplo, o bot pode usar a propriedade dados do canal para instruir o Telegram a enviar um adesivo ou para instruir o Office 365 a enviar um email.

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

Canal	Funcionalidade
Email	Envie e receba um email que contém metadados de corpo, assunto e importância.
Facebook	Enviar notificações do Facebook nativamente.
LINE	Envie uma mensagem que implemente tipos de mensagem específicos de LINHA.
Margem de atraso	Enviar mensagens do Slack com fidelidade total.
Teams	Manipule @menções em mensagens do Microsoft Teams.
Telegram	Execute ações específicas do Telegram, como compartilhar um memorando de voz ou um adesivo.

Observação

O valor da propriedade dados do canal de um objeto de atividade é um objeto JSON. Portanto, os exemplos neste artigo mostram o formato esperado da propriedade JSON channelData em vários cenários. Para criar um objeto JSON usando o .NET, use a classe JObject (.NET).

Criar uma mensagem de email personalizada

Para criar uma mensagem de email personalizada, defina a propriedade de atividade channelData como um objeto JSON que contém as seguintes propriedades:

Propriedade	Descrição
bccRecipients	Uma cadeia de caracteres delimitada por ponto e vírgula (;) de endereços de email a ser adicionada ao campo Cco (cópia oculta) da mensagem.
ccRecipients	Uma cadeia de caracteres delimitada por ponto e vírgula (;) de endereços de email a ser adicionada ao campo Cc (cópia carbono) da mensagem.
htmlBody	Um documento HTML que especifica o corpo da mensagem de email. Consulte a documentação do canal para obter informações sobre atributos e elementos HTML com suporte.
importance	O nível de importância do email. Os valores válidos são alta, normal, e baixa. O valor padrão é normal.
toRecipients	Uma cadeia de caracteres delimitada por ponto e vírgula (;) de endereços de email a ser adicionada ao campo Para da mensagem.

As mensagens de saída e de entrada entre o usuário e o bot podem ter uma channelData atividade que contém um objeto JSON cujas propriedades são especificadas na tabela anterior. O snippet abaixo mostra um exemplo da channelData propriedade para uma mensagem de email personalizada de entrada, do bot para o usuário.

{
    "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, defina a propriedade dados do canal do objeto de atividade em um objeto JSON que especifique estas propriedades:

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

Observação

Para obter detalhes sobre o formato e o conteúdo das propriedades notification_type e attachment, confira a documentação da API do Facebook.

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

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

Criar uma mensagem do LINE

Para criar uma mensagem que implemente tipos de mensagem específicos de LINHA (como adesivo, modelos ou tipos de ação específicos de LINHA, como abrir a câmera do telefone), defina a propriedade de dados de canal do objeto de atividade como um objeto JSON que especifica tipos de mensagem LINE e tipos de ação.

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

Há suporte para esses tipos de mensagem do LINE:

Adesivo
Imagemap
Modelo (botão, confirmar, carrossel)
Flex

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

Postback
Mensagem
URI
Datetimerpicker
Câmera
Rolo da câmera
Location

Para obter detalhes sobre esses métodos do LINE e seus parâmetros, confira a documentação da API do Bot do LINE.

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

Criar uma mensagem do Slack com fidelidade total

Para criar uma mensagem do Slack de fidelidade total, defina a propriedade de dados do canal do objeto de atividade como um objeto JSON que especifica:

Observação

Para dar suporte a botões em mensagens do Slack, habilite a opção Mensagens Interativas ao conectar o bot ao canal do Slack.

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

"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 usuário clicar em um botão em uma mensagem do Slack, o bot receberá uma mensagem de resposta na qual a propriedade dados do canal é populada com um objeto JSON payload. O objeto payload especifica o conteúdo da mensagem original, identifica o botão que recebeu o clique e identifica o usuário que clicou no botão.

Este snippet mostra um exemplo da propriedade channelData na mensagem recebida por um bot quando um usuário clica em um botão na mensagem do Slack.

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

O bot pode responder a essa mensagem da maneira normal ou postar sua resposta diretamente no ponto de extremidade especificado pela propriedade payload do objeto de response_url. Para obter informações sobre quando e como publicar uma resposta para a response_url, confira Botões do Slack.

Você pode criar botões dinâmicos usando 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, use 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Adicionar um bot ao Teams

Os bots adicionados a uma equipe se tornam outro membro da equipe, que pode ser @mentioned como parte da conversa. Na verdade, os bots só recebem mensagens quando são @mentioned, portanto, outras conversas no canal não são enviadas para o bot. Para saber mais, confira Conversas de chat de canal e grupo com um bot do Microsoft Teams.

Como os bots em um grupo ou canal respondem somente quando são mencionados (@botname) em uma mensagem, cada mensagem recebida por um bot em um canal de grupo contém seu próprio nome e você deve garantir que a análise de mensagens manipule isso. Além disso, os bots podem analisar outros usuários mencionados e mencionar os usuários como parte de suas mensagens.

Verificar e remover a menção @bot

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 é recomendável adicionar um bot por GUID para qualquer outra coisa além de fins de teste. Fazer isso limita severamente a funcionalidade de um bot. Os bots em produção devem ser adicionados ao Teams como parte de um aplicativo. Confira Criar um bot e Testar e depurar o bot do Microsoft Teams.

Criar uma mensagem do Telegram

Para criar uma mensagem que implementa ações específicas do Telegram, como compartilhar um memorando de voz ou um adesivo, defina a propriedade dados do canal do objeto de atividade em um objeto JSON que especifique estas propriedades:

Propriedade	Descrição
method	O método de API do Bot do Telegram a ser chamado.
parâmetros	Os parâmetros do método especificado.

Há suporte para estes métodos do Telegram:

answerInlineQuery
editMessageCaption
editMessageReplyMarkup
editMessageText
forwardMessage
banChatMember
sendAudio
sendChatAction
sendContact
sendDocument
sendLocation
sendMessage
sendPhoto
sendSticker
sendVenue
sendVideo
sendVoice
unbanChatMember

Para obter detalhes sobre esses métodos do Telegram e seus parâmetros, confira a documentação da API do Bot do Telegram.

Observação

O parâmetro chat_id é comum a todos os métodos do Telegram. Se você não especificar chat_id como um parâmetro, a estrutura fornecerá a ID para você.
Em vez de passar o conteúdo do arquivo embutido, especifique o arquivo usando uma URL e um tipo de mídia, conforme mostrado no exemplo abaixo.
Em cada mensagem que o bot recebe do canal do Telegram, a propriedade ChannelData incluirá a mensagem que o bot enviou anteriormente.

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

"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 matriz de métodos do Telegram:

"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 do Telegram for implementado, seu bot receberá uma mensagem de resposta na qual a propriedade de dados do canal é populada com um objeto JSON. Esse 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 como receber respostas de entrada, confira Receber atualizações.

Este snippet mostra um exemplo da channelData propriedade na mensagem que um bot recebe quando uma votação é 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
        }
    }
}

Implementar a funcionalidade específica do canal

Criar uma mensagem de email personalizada

Criar uma notificação do Facebook

Criar uma mensagem do LINE

Criar uma mensagem do Slack com fidelidade total

Adicionar um bot ao Teams

Verificar e remover a menção @bot

Criar uma mensagem do Telegram

Recursos adicionais

Recursos adicionais