Aggiungere allegati multimediali ai messaggi con l'API Bot Connector
Bot e canali in genere scambiano stringhe di testo, ma alcuni canali supportano anche lo scambio di allegati, che consente al bot di inviare messaggi più completi agli utenti. Ad esempio, il bot può inviare allegati multimediali (ad esempio immagini, video, audio, file) e schede avanzate. Questo articolo descrive come aggiungere allegati multimediali ai messaggi usando il servizio Bot Connector.
Suggerimento
Per informazioni sulle funzionalità supportate in ogni canale, vedere l'articolo di riferimento sui canali .
Aggiungere un allegato multimediale
Per aggiungere un allegato multimediale a un messaggio, creare un oggetto Attachment , impostare la proprietà sull'URL name del file multimediale e impostare la contentUrlcontentType proprietà sul tipo di supporto appropriato, ad esempio image/jpg, audio/wav, video/mp4. Quindi all'interno dell'oggetto Attività che rappresenta il messaggio specificare l'oggetto Attachment all'interno della matrice attachments.
L'esempio seguente illustra una richiesta che invia un messaggio contenente testo e un unico allegato immagine. In questa richiesta di esempio https://smba.trafficmanager.net/teams rappresenta l'URI di base. L'URI di base per le richieste inviate dal bot può essere diverso. Per informazioni dettagliate sull'impostazione dell'URI di base, vedere Informazioni di riferimento sulle 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"
}
Per i canali che supportano i file binari inline di un'immagine, è possibile impostare la contentUrl proprietà di su un binario base64 dell'immagine Attachment , ad esempio data:image/jpg; base64,iVBORw0KGgo...). Il canale visualizzerà l'immagine o l'URL dell'immagine accanto alla stringa di testo del messaggio.
{
"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"
}
È possibile collegare un file video o audio a un messaggio usando lo stesso processo come descritto in precedenza per un file di immagine. In base al canale, video e audio possono essere riprodotti inline oppure visualizzati come collegamento.
Nota
Il bot può inoltre ricevere i messaggi che contengono gli allegati multimediali. Ad esempio, un messaggio ricevuto dal bot può contenere un allegato se il canale consente all'utente di caricare una foto da analizzare o un documento da archiviare.
Aggiungere un allegato AudioCard
Il procedimento di aggiunta di un allegato AudioCard o VideoCard è uguale a quello di un allegato multimediale. Ad esempio, il codice JSON seguente mostra come aggiungere una scheda audio all'allegato multimediale.
{
"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"
}
Una volta ricevuto questo allegato, il canale avvierà la riproduzione del file audio. Se un utente interagisce con l'audio selezionando Pausa, ad esempio, il canale invierà un callback al bot con un codice JSON simile al seguente:
{
...
"type": "event",
"name": "media/pause",
"value": {
"url": // URL for media
"cardValue": {
// Supplementary parameter for this card
}
}
}
Il nome dell'evento multimediale media/pause verrà visualizzato nel campo activity.name. Fare riferimento alla tabella seguente per un elenco di tutti i nomi di eventi multimediali.
| Event | Descrizione |
|---|---|
| media/next | Il client è saltato al file multimediale successivo |
| media/pause | Il client ha interrotto la riproduzione di file multimediali |
| media/play | Il client ha avviato la riproduzione di file multimediali |
| media/previous | Il client è saltato al file multimediale precedente |
| media/resume | Il client ha ripreso la riproduzione di file multimediali |
| media/stop | Il client ha interrotto la riproduzione di file multimediali |