Adicionar anexos de multimédia a mensagens com a API do Bot Connector

Normalmente, os bots e canais trocam cadeias de texto, mas alguns canais também suportam a troca de anexos, o que permite que o bot envie mensagens mais ricas aos utilizadores. Por exemplo, o bot pode enviar anexos multimédia (como imagens, vídeos, áudio, ficheiros) e cartões avançados. Este artigo descreve como adicionar anexos de multimédia a mensagens com o serviço Bot Connector.

Adicionar um anexo de multimédia

Para adicionar um anexo multimédia a uma mensagem, crie um objeto Anexo , defina a name propriedade, defina a contentUrl propriedade para o URL do ficheiro de multimédia e defina a contentType propriedade para o tipo de suporte de dados adequado (como imagem/jpg, áudio/wav, vídeo/mp4). Em seguida, no objeto Atividade que representa a sua mensagem, especifique o objeto Attachment dentro da attachments matriz.

O exemplo seguinte mostra um pedido que envia uma mensagem com texto e um único anexo de imagem. Neste pedido de exemplo, https://smba.trafficmanager.net/teams representa o URI base; o URI base para pedidos de que os problemas do bot podem ser diferentes. Para obter detalhes sobre como definir o URI base, veja Referência da 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 suportam binários inline de uma imagem, pode definir a contentUrl propriedade do Attachment para um binário base64 da imagem (por exemplo, data:image/jpg; base64,iVBORw0KGgo...). O canal apresentará a imagem ou o URL da imagem junto à 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"
}

Pode anexar um ficheiro de vídeo ou ficheiro de áudio a uma mensagem através do mesmo processo descrito acima para um ficheiro de imagem. Dependendo do canal, o vídeo e o áudio podem ser reproduzidos inline ou podem ser apresentados como uma ligação.

Adicionar um anexo AudioCard

Adicionar um anexo AudioCard ou VideoCard é o mesmo que adicionar um anexo de multimédia. Por exemplo, o seguinte JSON mostra como adicionar um cartão de áudio no anexo de multimé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 este anexo, começará a reproduzir o ficheiro de áudio. Se um utilizador interagir com áudio ao selecionar Colocar em Pausa, por exemplo, o canal enviará uma chamada de retorno para o bot com um JSON semelhante ao seguinte:

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

O nome do evento multimédia media media/pausa aparecerá no activity.name campo. Veja a tabela abaixo para obter uma lista de todos os nomes de eventos multimédia.

Recursos adicionais

• Criar mensagens
• Enviar e receber mensagens
• Adicionar cartões avançados a mensagens
• Esquema de Atividade do Bot Framework
• Esquema de cartão do Bot Framework