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

  • Artigo

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

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

Canal Funcionalidade
E-mail Enviar e receber um e-mail que contenha metadados de corpo, assunto e importância
Slack Enviar mensagens de fidelidade completa
Facebook Envie notificações do Facebook de forma nativa
Telegram Execute ações específicas do Telegram, tais como partilhar um memorando de voz ou um autocolante

Nota

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

Crie uma mensagem de e-mail personalizada

Para criar uma mensagem de e-mail, desajei a Activity propriedade do channelData objeto a um objeto JSON que contenha estas 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 channelData propriedade para uma mensagem de e-mail 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"
}

Crie uma mensagem slack de fidelidade completa

Para criar uma mensagem slack de fidelidade completa, desajei a Activity propriedade do channelData objeto a um objeto JSON que especifica mensagens Slack, anexos Slack e/ou botões Slack.

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 channelData propriedade é 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.

Criar uma notificação do Facebook

Para criar uma notificação do Facebook, desajei a Activity propriedade do channelData objeto 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 telegrama

Para criar uma mensagem que implemente ações específicas do Telegram, como partilhar um memorando de voz ou um autocolante, de definiu a Activity propriedade do channelData objeto num 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"
        }
    }
]

Recursos adicionais