Adicionar anexos de mídia a mensagens com a API do Bot Connector

Bots e canais normalmente trocam cadeias de caracteres de texto, mas alguns canais também oferecem suporte a troca de anexos, o que permite que seu bot envie mensagens mais ricas para os usuários. Por exemplo, seu bot pode enviar anexos de mídia (como imagens, vídeos, áudio, arquivos) e cartões avançados. Este artigo descreve como adicionar anexos de mídia às mensagens usando o serviço Conector de Bot.

Adicionar um anexo de mídia

Para adicionar um anexo de mídia a uma mensagem, crie um objeto Attachment , defina a name propriedade , defina a contentUrl propriedade como a URL do arquivo de mídia e defina a contentType propriedade como o tipo de mídia apropriado (como image/jpg, audio/wav, video/mp4). Em seguida, dentro do objeto Atividade que representa sua mensagem, especifique seu objeto Attachment dentro da matriz attachments.

O exemplo a seguir mostra uma solicitação que envia uma mensagem contendo o texto e um anexo de imagem única. Nessa solicitação de exemplo, https://smba.trafficmanager.net/teams representa o URI base; o URI base das solicitações emitidas pelo bot pode ser diferente. Para obter detalhes sobre como definir o URI base, confira Referência de API.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/jpg",
            "contentUrl": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

Para canais que dão suporte a binários embutidos de uma imagem, você pode definir a contentUrl propriedade do Attachment como um binário base64 da imagem (por exemplo, data:image/jpg; base64,iVBORw0KGgo...). O canal exibirá a imagem ou a URL da imagem ao lado da cadeia de texto da mensagem.

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/jpg",
            "contentUrl": "data:image/jpg;base64,iVBORw0KGgo...",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

Você pode anexar um arquivo de vídeo ou áudio a uma mensagem usando o mesmo processo descrito acima para um arquivo de imagem. Dependendo do canal, áudio e vídeo podem ser reproduzidos em linha ou ele exibidos como um link.

Adicionar um anexo de AudioCard

A adição de um anexo de AudioCard ou VideoCard é o mesmo que adicionar um anexo de mídia. Por exemplo, o JSON a seguir mostra como adicionar uma cartão de áudio ao anexo de mídia.

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.audio",
      "content": {
        "title": "Allegro in C Major",
        "subtitle": "Allegro Duet",
        "text": "No Image, No Buttons, Autoloop, Autostart, Sharable",
        "duration": "PT2M55S",
        "media": [
          {
            "url": "https://contoso.com/media/AllegrofromDuetinCMajor.mp3"
          }
        ],
        "shareable": true,
        "autoloop": true,
        "autostart": true,
        "value": {
            // Supplementary parameter for this card
        }
      }
    }],
    "replyToId": "5d5cdc723"
}

Assim que o canal receber esse anexo, ele iniciará a execução do arquivo de áudio. Se um usuário interagir com o áudio selecionando Pausar, por exemplo, o canal enviará um retorno de chamada para o bot com um JSON semelhante a este:

{
    ...
    "type": "event",
    "name": "media/pause",
    "value": {
        "url": // URL for media
        "cardValue": {
            // Supplementary parameter for this card
        }
    }
}

O nome do evento de mídia media/pause aparecerá no campo activity.name. Consulte a tabela abaixo para obter uma lista com todos os nomes de evento de mídia.

Recursos adicionais

• Criar mensagens
• Enviar e receber mensagens
• Adicionar cartões ricos mensagens
• Esquema de atividade Bot Framework
• Esquema de cartão do bot Framework