Implementar a funcionalidade específica do canal
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 |
---|---|
Envie e receba um email que contém metadados de corpo, assunto e importância. | |
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).
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",
}
}
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",
//...
}
}
}
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"
}
]
}
}
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"
}
]
}
]
}
]
}
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.
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.
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 especificarchat_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
}
}
}