Aggiunta di allegati di schede avanzate ai messaggi con l'API bot Connector
Alcuni canali consentono al bot di inviare schede avanzate agli utenti. Una scheda avanzata è un allegato che contiene elementi interattivi, ad esempio pulsanti, testo, immagini, audio, video e così via.
Questo articolo descrive come creare schede avanzate che è possibile allegare a un messaggio. Vedere come aggiungere allegati multimediali ai messaggi per istruzioni specifiche sull'aggiunta di un allegato a un messaggio.
Tipi di schede avanzate
Una scheda avanzata è costituita da un titolo, una descrizione, un collegamento e immagini. Un messaggio può contenere più schede avanzate, visualizzate in formato sequenza o in formato elenco. Bot Framework supporta attualmente otto tipi di schede avanzate:
| Tipo di scheda | Descrizione |
|---|---|
| AdaptiveCard | Scheda personalizzabile che può contenere qualsiasi combinazione di testo, parlato, immagini, pulsanti e campi di input. Vedere per-channel support (Supporto per canale). |
| AnimationCard | Scheda che può eseguire GIF animate o brevi video. |
| AudioCard | Scheda che può eseguire un file audio. |
| HeroCard | Scheda che contiene in genere un'unica grande immagine, uno o più pulsanti e testo. |
| ThumbnailCard | Scheda che contiene in genere un'unica immagine di anteprima, uno o più pulsanti e testo. |
| ReceiptCard | Scheda che permette a un bot di fornire una ricevuta all'utente. Contiene in genere l'elenco di voci da includere nella ricevuta, informazioni su imposte e totali e altro testo. |
| SignInCard | Scheda che permette a un bot di richiedere che un utente esegua l'accesso. Contiene in genere testo e uno o più pulsanti su cui l'utente può fare clic per avviare il processo di accesso. |
| VideoCard | Scheda che può riprodurre video. |
Suggerimento
Per informazioni sulle funzionalità supportate in ogni canale, vedere l'articolo di riferimento sui canali.
Elaborare gli eventi nelle schede avanzate
Per elaborare gli eventi nelle schede avanzate, usare gli oggetti CardAction per specificare che cosa avviene quando l'utente fa clic su un pulsante o tocca una sezione della scheda. Ogni CardAction oggetto contiene queste proprietà:
| Proprietà | Type | Descrizione |
|---|---|---|
| channelData | string | dati specifici del canale associati a questa azione |
| displayText | string | testo da visualizzare nel feed della chat se si fa clic sul pulsante |
| Testo | string | testo dell'azione |
| type | string | tipo di azione (uno dei valori specificati nella tabella seguente) |
| title | string | titolo del pulsante |
| image | string | URL dell'immagine del pulsante |
| value | string | valore necessario per eseguire il tipo di azione specificato |
Nota
I pulsanti nelle schede adattive non vengono creati usando gli oggetti CardAction, ma usando lo schema definito dalle schede adattive.
Vedere Aggiungere una scheda adattiva a un messaggio per un esempio che illustra come aggiungere pulsanti a una scheda adattiva.
Per funzionare correttamente, assegnare un tipo di azione a ogni elemento selezionabile su una scheda hero. Questa tabella elenca e descrive i tipi di azioni disponibili e il valore da inserire nella proprietà valore associata.
L'azione messageBack della scheda ha un significato più generalizzato rispetto alle altre azioni della scheda. Vedere la sezione Azione scheda dello schema Attività per altre informazioni sui messageBack tipi di azione e altri tipi di azione scheda.
| Tipo | Descrizione | valore |
|---|---|---|
| call | Avvia una chiamata telefonica. | Destinazione della chiamata telefonica in questo formato: tel:123123123123. |
| downloadFile | Scarica un file. | URL del file da scaricare. |
| ImBack | Invia un messaggio al bot e pubblica una risposta visibile nella chat. | Testo del messaggio da inviare. |
| messageBack | Rappresenta una risposta di testo da inviare tramite il sistema di chat. | Valore programmatico facoltativo da includere nei messaggi generati. |
| openUrl | Apre un URL nel browser predefinito. | URL da aprire. |
| PlayAudio | Riproduce un contenuto audio. | URL dell'audio da riprodurre. |
| PlayVideo | Riproduce un contenuto video. | URL del video da riprodurre. |
| PostBack | Invia un messaggio al bot e potrebbe non pubblicare una risposta visibile nella chat. | Testo del messaggio da inviare. |
| showImage | Visualizza un'immagine. | URL dell'immagine da visualizzare. |
| signin | Avvia un processo di accesso OAuth. | URL del flusso OAuth da iniziare. |
Aggiungere una scheda banner a un messaggio
Per aggiungere un allegato di scheda avanzata a un messaggio:
- Creare un oggetto che rappresenta il tipo di scheda da aggiungere al messaggio.
- Creare un oggetto Attachment :
- Impostarne la
contentTypeproprietà sul tipo di supporto della scheda. - Impostarne la
contentproprietà sull'oggetto creato per rappresentare la scheda.
- Impostarne la
- Aggiungere l'oggetto
Attachmentallaattachmentsmatrice del messaggio.
Suggerimento
I messaggi che contengono allegati di schede avanzate in genere non specificano text.
Alcuni canali consentono di aggiungere più schede avanzate alla matrice attachments in un messaggio. Questa funzionalità può essere utile negli scenari in cui si vuole fornire all'utente più opzioni. Se ad esempio il bot consente agli utenti di prenotare camere di hotel, può presentare all'utente un elenco di schede avanzate che mostra i tipi di camere disponibili. Ogni scheda può contenere un'immagine e un elenco di servizi corrispondente al tipo di camera e l'utente può selezionare un tipo di camera toccando una scheda o facendo clic su un pulsante.
Suggerimento
Per visualizzare più schede avanzate in formato elenco, impostare la proprietà attachmentLayout dell'oggetto Activity su "list".
Per visualizzare più schede avanzate in formato sequenza, impostare la proprietà attachmentLayout dell'oggetto Activity su "carousel".
Se il canale non supporta il formato carousel, visualizzerà le schede avanzate in formato elenco, anche se la attachmentLayout proprietà specifica "carousel".
L'esempio seguente mostra un messaggio completo che contiene un singolo allegato della scheda Hero. 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"
},
"attachments": [
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "title goes here",
"subtitle": "subtitle goes here",
"text": "descriptive text goes here",
"images": [
{
"url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"alt": "picture of a duck",
"tap": {
"type": "playAudio",
"value": "url to an audio track of a duck call goes here"
}
}
],
"buttons": [
{
"type": "playAudio",
"title": "Duck Call",
"value": "url to an audio track of a duck call goes here"
},
{
"type": "openUrl",
"title": "Watch Video",
"image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"value": "url goes here of the duck in flight"
}
]
}
}
],
"replyToId": "5d5cdc723"
}
Aggiungere una scheda adattiva a un messaggio
La scheda adattiva può contenere qualsiasi combinazione di testo, parlato, immagini, pulsanti e campi di input. Le schede adattive vengono create usando il formato JSON specificato nelle schede adattive, che offrono il controllo completo sul contenuto e sul formato delle schede.
Il sito Adaptive Cards (Schede adattive) offre informazioni sullo schema delle schede adattive, consente di esplorare gli elementi delle schede adattive e fornisce esempi JSON che possono essere usati per creare schede di varia composizione e complessità. È anche possibile usare il visualizzatore interattivo per progettare i payload delle schede adattive e visualizzare in anteprima l'output delle schede.
Nell'esempio seguente viene illustrato un singolo oggetto allegato scheda adattiva che rappresenta un'assegnazione di lavoro. Per inviarlo a un utente, è necessario aggiungerlo come allegato in un messaggio.
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Publish Adaptive Card schema",
"weight": "bolder",
"size": "medium"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"size": "small",
"style": "person"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Matt Hidinger",
"weight": "bolder",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "none",
"text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
"isSubtle": true,
"wrap": true
}
]
}
]
}
]
},
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Card"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Comment",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Text",
"id": "comment",
"isMultiline": true,
"placeholder": "Enter your comment"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
]
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
]
}
La scheda risultante contiene un titolo, le informazioni sull'autore della scheda (nome e avatar), la data di creazione della scheda, una descrizione delle assegnazioni di lavoro e le informazioni correlate all'assegnazione. Sono inoltre disponibili pulsanti su cui è possibile fare clic per commentare l'assegnazione di lavoro o visualizzarla:
