Share via

Implementar funcionalidade específica do canal com a API do Bot Connector

  • Artigo

Alguns canais fornecem recursos que não podem ser implementados usando apenas texto de mensagem e anexos. Para implementar a funcionalidade específica do canal, você pode passar metadados nativos para um canal na propriedade do channelData objeto Activity. Por exemplo, o bot pode usar a propriedade channelData 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 channelData de uma atividade de mensagem para implementar esta funcionalidade específica do canal:

Canal Funcionalidade
Email Enviar e receber um email que contém metadados de corpo, assunto e prioridade
Margem de atraso Enviar mensagens do Slack com fidelidade total
Facebook Enviar notificações do Facebook nativamente
Telegram Executar ações específicas do Telegram, como compartilhar um memorando de voz ou um adesivo

Observação

O valor da propriedade de um Activity objeto channelData é um objeto JSON. A estrutura do objeto JSON varia de acordo com o canal e a funcionalidade que está sendo implementada, conforme descrito abaixo.

Criar uma mensagem de email personalizada

Para criar uma mensagem de email, defina a propriedade do Activity objeto channelData como um objeto JSON que contém essas propriedades:

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

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

"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 mensagem do Slack com fidelidade total

Para criar uma mensagem do Slack com fidelidade total, defina a propriedade Activity do objeto channelData como um objeto JSON que especifica mensagens do Slack, anexos do Slack e/ou botões do Slack.

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 channelData é 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 response_url. Para obter informações sobre quando e como publicar uma resposta para a response_url, confira Botões do Slack.

Criar uma notificação do Facebook

Para criar uma notificação do Facebook, defina a propriedade Activity do objeto channelData 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 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 Activity do objeto channelData 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 propriedade channelData que especifica um único método do Telegram.

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

Este snippet mostra um exemplo de uma propriedade channelData 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"
        }
    }
]

Recursos adicionais