Informazioni di riferimento sulle API per il servizio bot Framework Connessione or

Articolo
10/09/2024

Nota

L'API REST non equivale all'SDK. L'API REST viene fornita per consentire la comunicazione REST standard; tuttavia, il metodo preferito per interagire con il Bot Framework è il SDK.

All'interno di Bot Framework, il servizio Bot Connector consente al bot di scambiare messaggi con gli utenti sui canali configurati nel portale di Bot Framework. Il servizio usa gli standard di settore REST e JSON tramite HTTPS.

URI di base

Quando un utente invia un messaggio al bot, la richiesta in ingresso contiene un oggetto Activity con una proprietà serviceUrl che specifica l'endpoint a cui il bot deve inviare la risposta. Per accedere al servizio Bot Connector, usare il valore serviceUrl come URI di base per le richieste API.

Quando non si ha già un URL del servizio per il canale, usare https://smba.trafficmanager.net/teams/ come URL del servizio. Per altre informazioni, vedere come creare una conversazione e un messaggio proattivo in Teams.

Ad esempio, si supponga che il bot riceva l'attività seguente quando l'utente invia un messaggio al bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

La serviceUrl proprietà all'interno del messaggio dell'utente indica che il bot deve inviare la risposta all'endpoint https://smba.trafficmanager.net/teams/. L'URL del servizio sarà l'URI di base per le richieste successive che il bot emette nel contesto di questa conversazione. Se il bot necessita di inviare un messaggio proattivo all'utente, assicurarsi di salvare il valore di serviceUrl.

Nell'esempio seguente viene illustrata la richiesta che il bot emette per rispondere al messaggio dell'utente.

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

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

Intestazioni

Intestazioni delle richieste

Oltre alle intestazioni delle richieste HTTP standard, ogni richiesta API emessa deve includere un'intestazione Authorization che specifica un token di accesso per l'autenticazione del bot. Specificare l'intestazione Authorization usando questo formato:

Authorization: Bearer ACCESS_TOKEN

Per informazioni dettagliate su come ottenere un token di accesso per il bot, vedere Autenticare le richieste del bot per il servizio Bot Connector.

Intestazioni della risposta

Oltre alle intestazioni di risposta HTTP standard, ogni risposta conterrà un'intestazione X-Correlating-OperationId. Il valore di questa intestazione è un ID che corrisponde alla voce di log di Bot Framework, che contiene informazioni dettagliate sulla richiesta. Quando si riceve una risposta di errore, è necessario acquisire il valore di questa intestazione. Se non è possibile risolvere il problema in modo indipendente, includere questo valore nelle informazioni fornite al team di supporto quando si segnala il problema.

Codici di stato HTTP

Il codice di stato HTTP restituito con ogni risposta indica il risultato della richiesta corrispondente.

Nota

Nella tabella seguente vengono descritti i codici di stato HTTP più comuni. Alcuni errori vengono generati dal canale. Per altre informazioni, potrebbe essere necessario leggere la documentazione per sviluppatori del canale.

Codice di stato HTTP	Significato
200	La richiesta è stata completata.
201	La richiesta è stata completata.
202	La richiesta è stata accettata per l'elaborazione.
204	La richiesta è stata completata ma non è stato restituito alcun contenuto.
400	La richiesta è in formato non valido o comunque non corretta.
401	Il bot non è ancora autenticato.
403	Il bot non è autorizzato a eseguire l'operazione richiesta.
404	La risorsa richiesta non è stata trovata.
405	Il canale non supporta l'operazione richiesta.
500	Si è verificato un errore interno del server.
503	Il servizio è temporaneamente non disponibile.

Errors

Nel corpo di qualsiasi risposta che specifica un codice di stato HTTP compreso nell'intervallo 4xx o 5xx sarà incluso un oggetto ErrorResponse contenente informazioni sull'errore. Se viene restituita una risposta di errore compresa nell'intervallo 4xx, controllare l'oggetto ErrorResponse per identificare la causa dell'errore e risolvere il problema prima di inviare di nuovo la richiesta.

Operazioni riguardanti la conversazione

Usare queste operazioni per creare conversazioni, inviare messaggi (attività) e gestire il contenuto delle conversazioni.

Importante

Non tutti i canali supportano tutti gli endpoint. Tuttavia, tutti i canali devono supportare la risposta all'endpoint dell'attività.

Ad esempio, solo Direct Line e chat Web supportano l'endpoint di recupero delle conversazioni.

Operazione	Descrizione
Creare conversazione	Crea una nuova conversazione.
Attività Delete	Eliminare un'attività esistente.
Eliminare un membro della conversazione	Rimuove un membro da una conversazione.
Ottenere i membri dell'attività	Recupera i membri dell'attività specificata all'interno della conversazione specificata.
Ottenere un membro della conversazione	Recupera i dettagli relativi a un membro di una conversazione.
Ottenere i membri della conversazione	Recupera i membri della conversazione specificata.
Ottenere membri con pagine di conversazione	Recupera i membri della conversazione specificata una pagina alla volta.
Ottenere conversazioni	Recupera un elenco di conversazioni a cui il bot ha partecipato.
Rispondi all'attività	Invia un'attività (messaggio) alla conversazione specificata, come risposta all'attività specificata.
Inviare la cronologia della conversazione	Carica una trascrizione delle attività precedenti alla conversazione.
Invia alla conversazione	Invia un'attività (messaggio) alla fine della conversazione specificata.
Attività di aggiornamento	Aggiorna un'attività esistente.
Caricare l'allegato nel canale	Carica un allegato direttamente nell'archiviazione BLOB di un canale.

Creare una conversazione

Crea una nuova conversazione.

POST /v3/conversations

Contenuto	Descrizione
Testo della richiesta	Un oggetto ConversationParameters
Resi	Un oggetto ConversationResourceResponse

Attività Delete

Alcuni canali consentono di eliminare un'attività esistente. Se l'operazione riesce, l'attività specificata all'interno della conversazione specificata viene rimossa.

DELETE /v3/conversations/{conversationId}/activities/{activityId}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un codice di stato HTTP che indica il risultato dell'operazione. Nel corpo della risposta non è specificato nulla.

Eliminare un membro della conversazione

Rimuove un membro da una conversazione. Se tale membro è stato l'ultimo della conversazione, verrà eliminata anche la conversazione.

DELETE /v3/conversations/{conversationId}/members/{memberId}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un codice di stato HTTP che indica il risultato dell'operazione. Nel corpo della risposta non è specificato nulla.

Recuperare i membri dell'attività

Recupera i membri dell'attività specificata all'interno della conversazione specificata.

GET /v3/conversations/{conversationId}/activities/{activityId}/members

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Una matrice di oggetti ChannelAccount

Ottenere conversazioni

Recupera un elenco di conversazioni a cui il bot ha partecipato.

GET /v3/conversations?continuationToken={continuationToken}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un oggetto ConversationsResult

Ottenere un membro della conversazione

Recupera i dettagli relativi a un membro specifico di una conversazione specifica.

GET /v3/conversations/{conversationId}/members/{memberId}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un oggetto ChannelAccount per il membro.

GetConversationMembers

Recupera i membri della conversazione specificata.

GET /v3/conversations/{conversationId}/members

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Una matrice di oggetti ChannelAccount per i membri della conversazione.

Ottenere membri con pagine di conversazione

Recupera i membri della conversazione specificata una pagina alla volta.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un oggetto PagedMembersResult

Rispondi all'attività

Invia un'attività (messaggio) alla conversazione specificata, come risposta all'attività specificata. L'attività verrà aggiunta come una risposta a un'altra attività, se il canale la supporta. Se il canale non supporta le risposte annidate, questa operazione si comporta come Invia a conversazione.

POST /v3/conversations/{conversationId}/activities/{activityId}

Contenuto	Descrizione
Testo della richiesta	Un oggetto Activity
Resi	Un oggetto ResourceResponse

Invia cronologia conversazioni

Carica una trascrizione delle attività precedenti alla conversazione in modo che il client possa eseguirne il rendering.

POST /v3/conversations/{conversationId}/activities/history

Contenuto	Descrizione
Testo della richiesta	Un oggetto Transcript.
Resi	Un oggetto ResourceResponse.

Invia alla conversazione

Invia un'attività (messaggio) alla conversazione specificata. L'attività verrà accodata alla fine della conversazione in base al timestamp o alla semantica del canale. Per rispondere a un messaggio specifico all'interno della conversazione, usare Rispondere all'attività.

POST /v3/conversations/{conversationId}/activities

Contenuto	Descrizione
Testo della richiesta	Un oggetto Activity
Resi	Un oggetto ResourceResponse

UpdateActivity

Alcuni canali consentono di modificare un'attività esistente in modo da riflettere il nuovo stato di una conversazione di bot. Ad esempio, si potrebbero rimuovere i pulsanti da un messaggio nella conversazione dopo che l'utente ha fatto clic su uno dei pulsanti. Se l'operazione riesce, l'attività specificata all'interno della conversazione specificata viene aggiornata.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Contenuto	Descrizione
Testo della richiesta	Un oggetto Activity
Resi	Un oggetto ResourceResponse

Caricare l'allegato nel canale

Carica un allegato per la conversazione specificata direttamente nell'archiviazione BOLB di un canale. In questo modo è possibile archiviare i dati in un archivio conforme.

POST /v3/conversations/{conversationId}/attachments

Contenuto	Descrizione
Testo della richiesta	Un oggetto AttachmentData.
Resi	Un oggetto ResourceResponse. La proprietà id specifica l'ID allegato che può essere usato con l'operazione Get attachment information (Ottieni informazioni sugli allegati) e l'operazione Get attachment (Ottieni allegato ).

Operazioni relative agli allegati

Usare queste operazioni per recuperare informazioni su un allegato e sui dati binari del file stesso.

Operazione	Descrizione
Ottenere info sugli allegati	Ottiene informazioni sull'allegato specificato, inclusi il nome del file, il tipo di file e le visualizzazioni disponibili, ad esempio originale o anteprima.
Ottenere allegato	Ottiene la vista specificata dell'allegato specificato come contenuto binario.

Ottenere informazioni sugli allegati

Ottiene informazioni sull'allegato specificato, inclusi il nome del file, il tipo e le visualizzazioni disponibili, ad esempio originale o anteprima.

GET /v3/attachments/{attachmentId}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Un oggetto AttachmentInfo

Ottieni allegato

Ottiene la vista specificata dell'allegato specificato come contenuto binario.

GET /v3/attachments/{attachmentId}/views/{viewId}

Contenuto	Descrizione
Testo della richiesta	n/d
Resi	Il contenuto binario che rappresenta la vista specificata dell'allegato specificato

Operazioni relative allo stato (deprecate)

Il servizio di informazioni sullo stato di Microsoft Bot Framework è stato ritirato il 30 marzo 2018. In precedenza, i bot basati su Azure AI servizio Bot o Bot Builder SDK avevano una connessione predefinita a questo servizio ospitato da Microsoft per archiviare i dati sullo stato del bot. I bot dovranno essere aggiornati per usare il proprio spazio di archiviazione dello stato.

Operazione	Descrizione
`Set User Data`	Archivia i dati di stato di un utente specifico in un canale.
`Set Conversation Data`	Archivia i dati di stato di una conversazione specifica in un canale.
`Set Private Conversation Data`	Archivia i dati di stato di un utente specifico nel contesto di una conversazione specifica in un canale.
`Get User Data`	Recupera i dati di stato che sono stati precedentemente archiviati per un utente specifico in tutte le conversazioni in un canale.
`Get Conversation Data`	Recupera i dati di stato che sono stati precedentemente archiviati per una conversazione specifica in un canale.
`Get Private Conversation Data`	Recupera i dati di stato che sono stati precedentemente archiviati per un utente specifico nel contesto di una conversazione specifica in un canale.
`Delete State For User`	Elimina i dati di stato precedentemente archiviati per un utente.

Schema

Lo schema di Bot Framework definisce gli oggetti e le proprietà che il bot può usare per comunicare con un utente.

Oggetto	Descrizione
Oggetto Activity	Definisce un messaggio che viene scambiato tra bot e utente.
Oggetto AnimationCard	Definisce una scheda che può riprodurre GIF animate o brevi video.
Oggetto Attachment	Definisce le informazioni aggiuntive da includere nel messaggio. Un allegato può essere un file multimediale (ad esempio audio, video, immagine, file) o una scheda avanzata.
Oggetto AttachmentData	Descrive i dati di un allegato.
Oggetto AttachmentInfo	Descrive un allegato.
Oggetto AttachmentView	Definisce un oggetto che rappresenta una visualizzazione disponibile per un allegato.
Oggetto AudioCard	Definisce una scheda che può riprodurre un file audio.
Oggetto CardAction	Definisce un'azione da eseguire.
Oggetto CardImage	Definisce un'immagine da visualizzare nella scheda.
Oggetto ChannelAccount	Definisce un account utente o bot nel canale.
Oggetto ConversationAccount	Definisce una conversazione in un canale.
Oggetto ConversationMembers	Definisce i membri di una conversazione.
Oggetto ConversationParameters	Definisce i parametri per la creazione di una nuova conversazione
Oggetto ConversationReference	Definisce un punto specifico in una conversazione.
Oggetto ConversationResourceResponse	Definisce una risposta all'operazione Creare conversazione.
Oggetto ConversationsResult	Definisce il risultato di una chiamata all'operazione Recuperare conversazioni.
Oggetto Entity	Definisce un oggetto entità.
Oggetto Error	Definisce un errore.
Oggetto ErrorResponse	Definisce una risposta di API HTTP.
Oggetto Fact	Definisce una coppia chiave-valore che contiene un fact.
Oggetto GeoCoordinates	Definisce una posizione geografica usando le coordinate World Geodetic System (WSG84).
Oggetto HeroCard	Definisce una scheda con una grande immagine, titolo, testo e pulsanti di azione.
Oggetto InnerHttpError	Oggetto che rappresenta un errore HTTP interno.
Oggetto MediaEventValue	Parametro supplementare per gli eventi multimediali.
Oggetto MediaUrl	Definisce l'URL all'origine di un file multimediale.
Oggetto Mention	Definisce un utente o un bot menzionato nella conversazione.
Oggetto MessageReaction	Definisce una reazione a un messaggio.
Oggetto PagedMembersResult	Pagina dei membri restituiti da Recuperare membri della conversazione per pagine.
Oggetto Place	Definisce un luogo menzionato nella conversazione.
Oggetto ReceiptCard	Definisce una scheda contenente una ricevuta per un acquisto.
Oggetto ReceiptItem	Definisce una voce all'interno di una ricevuta.
Oggetto ResourceResponse	Definisce una risorsa.
Oggetto SemanticAction	Definisce un riferimento a un'azione programmatica.
Oggetto SignInCard	Definisce una scheda che consente a un utente di accedere a un servizio.
Oggetto SuggestedActions	Definisce le opzioni tra cui un utente può scegliere.
Oggetto TextHighlight	Fa riferimento a una sottostringa di contenuto all'interno di un altro campo.
Oggetto ThumbnailCard	Definisce una scheda con un'immagine anteprima, titolo, testo e pulsanti di azione.
Oggetto ThumbnailUrl	Definisce l'URL all'origine di un'immagine.
Oggetto Transcript	Una raccolta di attività da caricare tramite l'operazione Inviare la cronologia dell'operazione.
Oggetto VideoCard	Definisce una scheda che può riprodurre video.

Oggetto Activity

Definisce un messaggio che viene scambiato tra bot e utente.

Proprietà	Digita	Descrizione
azione	Stringa	L'azione da applicare o che è stata applicata. Usare la proprietà type per determinare il contesto per l'azione. Ad esempio, se type è contactRelationUpdate, il valore della proprietà action sarà add se l'utente ha aggiunto il bot al proprio elenco contatti, oppure remove se il bot è stato rimosso dall'elenco contatti.
attachmentLayout	Stringa	Layout degli allegati della scheda avanzata inclusi nel messaggio. Uno dei seguenti valori: carousel, list. Per altre informazioni sugli allegati della scheda avanzata, vedere Aggiungere allegati della scheda avanzata ai messaggi.
attachments	Attachment[]	Una matrice di oggetti Attachment che definisce le informazioni aggiuntive da includere nel messaggio. Ogni allegato può essere un file (ad esempio audio, video, immagine) o una scheda avanzata.
callerId	Stringa	Stringa contenente un IRI che identifica il chiamante di un bot. Questo campo non è destinato a essere trasmesso in rete, ma viene popolato da bot e client basati su dati verificabili crittograficamente che asserisce l'identità dei chiamanti (ad esempio token).
channelData	Oggetto	Un oggetto che include contenuto specifico del canale. Alcuni canali forniscono funzionalità che richiedono informazioni aggiuntive che non possono essere rappresentate usando lo schema degli allegati. In questi casi, impostare questa proprietà per il contenuto specifico del canale, come definito nella documentazione relativa al canale. Per altre informazioni, vedere Implementare funzionalità specifiche del canale.
channelId	Stringa	L'ID che identifica il canale in modo univoco. Impostato dal canale.
code	Stringa	Codice che indica il motivo per cui la conversazione è terminata.
conversation	ConversationAccount	Un oggetto ConversationAccount che definisce la conversazione a cui appartiene l'attività.
deliveryMode	Stringa	Hint di recapito per segnalare al destinatario percorsi di recapito alternativi per l'attività. Uno dei valori seguenti: normal, notification.
entities	object[]	Matrice di oggetti che rappresenta le entità menzionate nel messaggio. Gli oggetti in questa matrice possono essere qualsiasi oggetto Schema.org. Ad esempio, la matrice può includere gli oggetti Mention che identificano un utente menzionato nella conversazione e gli oggetti Place che identificano un luogo menzionato nella conversazione.
expiration	Stringa	Il momento in cui l'attività deve essere considerata "scaduta" e non deve essere presentata al destinatario.
da	ChannelAccount	Un oggetto ChannelAccount che specifica il mittente del messaggio.
historyDisclosed	Boolean	Flag che indica se viene fornita o meno la cronologia. Il valore predefinito è false.
id	Stringa	L'ID che identifica in modo univoco l'attività nel canale.
importance	Stringa	Definisce l'importanza di un'attività. Uno dei valori seguenti: low, normal, high.
inputHint	Stringa	Valore che indica se il bot sta accettando, sta ignorando o prevede un input dell'utente dopo che il messaggio è stato recapitato al client. Uno dei seguenti valori: acceptingInput, expectingInput, ignoringInput.
etichetta	Stringa	Etichetta descrittiva per l'attività.
listenFor	String[]	Elenco di frasi e riferimenti che devono essere ascoltati dai sistemi di priming voce e lingua.
impostazioni locali	Stringa	Impostazioni locali della lingua che deve essere usata per visualizzare il testo all'interno del messaggio, nel formato `<language>-<country>`. Il canale utilizza questa proprietà per indicare la lingua dell'utente, in modo che il bot possa specificare le stringhe visualizzate in tale lingua. Il valore predefinito è en-US.
localTimestamp	Stringa	Data e ora in cui il messaggio è stato inviato nel fuso orario locale, espresse nel formato ISO-8601.
localTimezone	Stringa	Contiene il nome del fuso orario locale del messaggio, espresso nel formato di database del fuso orario IANA, ad esempio America/Los_Angeles.
membersAdded	ChannelAccount[]	Matrice di oggetti ChannelAccount che rappresenta l'elenco di utenti che fanno parte della conversazione. Presente solo se il type dell'attività è "conversationUpdate" e gli utenti fanno parte della conversazione.
membersRemoved	ChannelAccount[]	Matrice di oggetti ChannelAccount che rappresenta l'elenco di utenti che hanno abbandonato la conversazione. Presente solo se il type dell'attività è "conversationUpdate" e gli utenti hanno abbandonato la conversazione.
name	string	Nome dell'operazione per richiamare o il nome dell'evento.
reactionsAdded	MessageReaction[]	Raccolta di reazioni aggiunte alla conversazione.
reactionsRemoved	MessageReaction[]	Raccolta di reazioni rimosse dalla conversazione.
recipient	ChannelAccount	Un oggetto ChannelAccount che specifica il destinatario del messaggio.
relatesTo	ConversationReference	Un oggetto ConversationReference che definisce un punto specifico in una conversazione.
replyToId	Stringa	L'ID del messaggio di cui questo messaggio è la risposta. Per rispondere a un messaggio inviato dall'utente, impostare per questa proprietà l'ID del messaggio dell'utente. Non tutti i canali supportano le risposte organizzate in thread. In questi casi il canale ignorerà questa proprietà e userà semantica ordinata in base al tempo (timestamp) per accodare il messaggio alla conversazione.
semanticAction	SemanticAction	Oggetto SemanticAction che rappresenta un riferimento a un'azione programmatica.
serviceUrl	Stringa	URL che specifica l'endpoint di servizio del canale. Impostato dal canale.
speak	Stringa	Testo che il bot legge in un canale con servizio di sintesi vocale abilitato. Per controllare varie caratteristiche del servizio di sintesi vocale del bot, ad esempio voce, velocità, volume, pronuncia e tono, specificare questa proprietà nel formato Speech Synthesis Markup Language (SSML).
suggestedActions	SuggestedActions	Un oggetto SuggestedActions che definisce le opzioni tra cui l'utente può scegliere.
summary	Stringa	Riepilogo delle informazioni contenute nel messaggio. Ad esempio, per un messaggio che viene inviato tramite un canale di posta elettronica, questa proprietà specifica i primi 50 caratteri del messaggio di posta elettronica.
text	Stringa	Testo del messaggio inviato dall'utente al bot o dal bot all'utente. Vedere la documentazione del canale per i limiti imposti sul contenuto di questa proprietà.
textFormat	Stringa	Formato del testo del messaggio. Uno dei seguenti valori: markdown, plain, xml. Per altre informazioni sul formato del testo, vedere Creazione di messaggi.
textHighlights	TextHighlight[]	Raccolta di frammenti di testo da evidenziare quando l'attività contiene un valore replyToId.
timestamp	Stringa	Data e ora in cui il messaggio è stato inviato nel fuso orario UTC, espresse nel formato ISO-8601.
topicName	Stringa	Argomento della conversazione a cui appartiene l'attività.
type	Stringa	Tipo di attività. Uno dei valori seguenti: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Per informazioni dettagliate sui tipi di attività, vedere Panoramica delle attività.
value	Oggetto	Valore aperto.
valueType	Stringa	Tipo dell'oggetto value dell'attività.

Proprietà	Digita	Descrizione
aspect	Boolean	Proporzioni del segnaposto per anteprime/file multimediali. I valori consentiti sono "16:9" e "4:3".
autoloop	Boolean	Flag che indica se riprodurre nuovamente l'elenco di immagini GIF animate quando l'ultima termina. Impostare questa proprietà su true per riprodurre di nuovo l'animazione in modo automatico; in caso contrario, impostare su false. Il valore predefinito è true.
autostart	Boolean	Flag che indica se riprodurre automaticamente l'animazione quando viene visualizzata la scheda. Impostare questa proprietà su true per riprodurre automaticamente l'animazione; in caso contrario, impostare su false. Il valore predefinito è true.
buttons	CardAction[]	Matrice di oggetti CardAction che consentono all'utente di eseguire una o più azioni. Il canale determina il numero di pulsanti che è possibile specificare.
duration	Stringa	Durata del contenuto multimediale nel formato di durata ISO 8601.
Immagine	ThumbnailUrl	Un oggetto ThumbnailUrl che specifica l'immagine da visualizzare sulla scheda.
media	MediaUrl[]	Matrice di oggetti MediaUrl. Quando questo campo contiene più URL, ogni URL è un formato alternativo dello stesso contenuto.
shareable	Boolean	Flag che indica se l'animazione può essere condivisa con altri utenti. Impostare questa proprietà su true se l'animazione può essere condivisa; in caso contrario, impostare su false. Il valore predefinito è true.
subtitle	Stringa	Sottotitolo da visualizzare sotto il titolo della scheda.
text	Stringa	Descrizione o prompt da visualizzare sotto il titolo della scheda o il sottotitolo.
title	Stringa	Titolo della scheda.
value	Oggetto	Parametro supplementare per questa scheda.

Proprietà	Digita	Descrizione
content	Oggetto	Contenuto dell'allegato. Se l'allegato è una scheda avanzata, impostare questa proprietà sull'oggetto della scheda avanzata. Questa proprietà e la proprietà contentUrl si escludono a vicenda.
contentType	Stringa	Il tipo di file multimediali del contenuto dell'allegato. Per i file multimediali, impostare questa proprietà su tipi di file multimediali noti, ad esempio image/png, audio/wav e video/mp4. Per le schede avanzate, impostare questa proprietà su uno di questi tipi specifici del fornitore: application/vnd.microsoft.card.adaptive: una cheda avanzata che può contenere qualsiasi combinazione di testo, parlato, immagini, pulsanti e campi di input. Impostare la proprietà content su un oggetto AdaptiveCard. application/vnd.microsoft.card.animation: una scheda avanzata che può riprodurre animazioni. Impostare la proprietà content su un oggetto AnimationCard. application/vnd.microsoft.card.audio: una scheda avanzata che può riprodurre file audio. Impostare la proprietà content su un oggetto AudioCard. application/vnd.microsoft.card.hero: una scheda Banner. Impostare la proprietà content su un oggetto HeroCard. application/vnd.microsoft.card.receipt: scheda ricevuta. Impostare la proprietà content su un oggetto ReceiptCard. application/vnd.microsoft.card.signin: scheda di accesso utente. Impostare la proprietà content su un oggetto SignInCard. application/vnd.microsoft.card.thumbnail: una scheda Anteprima. Impostare la proprietà content su un oggetto ThumbnailCard. application/vnd.microsoft.card.video: una scheda avanzata che può riprodurre video. Impostare la proprietà content su un oggetto VideoCard.
contentUrl	Stringa	URL del contenuto dell'allegato. Ad esempio, se l'allegato è un'immagine, è possibile impostare contentUrl sull'URL che rappresenta il percorso dell'immagine. I protocolli supportati sono: HTTP, HTTPS, file e dati.
name	string	Nome dell'allegato.
thumbnailUrl	Stringa	URL di un'immagine di anteprima che il canale può usare se supporta l'uso di una forma alternativa di dimensioni ridotte di content oppure contentUrl. Ad esempio, se si imposta contentType su application/word e contentUrl sul percorso del documento Word, è possibile includere un'immagine di anteprima che rappresenta il documento. Il canale è riuscito a visualizzare l'immagine di anteprima anziché il documento. Quando l'utente fa clic sull'immagine, il canale aprirà il documento.

Proprietà	Digita	Descrizione
size	Numero	Dimensione del file.
viewId	Stringa	ID vista.

Proprietà	Digita	Descrizione
aspect	Stringa	Proporzioni dell'anteprima specificate nella proprietà image. I valori validi sono 16:9 e 4:3.
autoloop	Boolean	Flag che indica se riprodurre nuovamente l'elenco di file audio quando l'ultimo termina. Impostare questa proprietà su true per riprodurre di nuovo i file audio in modo automatico; in caso contrario, impostare su false. Il valore predefinito è true.
autostart	Boolean	Flag che indica se riprodurre automaticamente l'audio quando viene visualizzata la scheda. Impostare questa proprietà su true per riprodurre automaticamente l'audio; in caso contrario, impostare su false. Il valore predefinito è true.
buttons	CardAction[]	Matrice di oggetti CardAction che consentono all'utente di eseguire una o più azioni. Il canale determina il numero di pulsanti che è possibile specificare.
duration	Stringa	Durata del contenuto multimediale nel formato di durata ISO 8601.
Immagine	ThumbnailUrl	Un oggetto ThumbnailUrl che specifica l'immagine da visualizzare sulla scheda.
media	MediaUrl[]	Matrice di oggetti MediaUrl. Quando questo campo contiene più URL, ogni URL è un formato alternativo dello stesso contenuto.
shareable	Boolean	Flag che indica se i file audio possono essere condivisi con altri utenti. Impostare questa proprietà su true se l'audio può essere condiviso; in caso contrario, impostare su false. Il valore predefinito è true.
subtitle	Stringa	Sottotitolo da visualizzare sotto il titolo della scheda.
text	Stringa	Descrizione o prompt da visualizzare sotto il titolo della scheda o il sottotitolo.
title	Stringa	Titolo della scheda.
value	Oggetto	Parametro supplementare per questa scheda.

Proprietà	Digita	Descrizione
channelData	Stringa	Dati specifici del canale associati a questa azione.
displayText	Stringa	Testo da visualizzare nel feed della chat se si fa clic sul pulsante.
Immagine	Stringa	URL dell'immagine che verrà visualizzato sul pulsante accanto all'etichetta di testo.
text	Stringa	Testo dell'azione.
title	Stringa	Descrizione del testo visualizzata sul pulsante.
type	Stringa	Tipo di azione da eseguire. Per un elenco di valori validi, vedere Allegare schede avanzate ai messaggi.
value	Oggetto	Parametro supplementare per questa azione. Il comportamento di questa proprietà varierà in base alla proprietà type dell'azione. Per altre informazioni, vedere Allegare schede avanzate ai messaggi.

Proprietà	Digita	Descrizione
alt	Stringa	Descrizione dell'immagine. È consigliabile includere la descrizione per supportare l'accessibilità.
tap	CardAction	Un oggetto CardAction che specifica l'azione da eseguire se l'utente tocca o fa clic sull'immagine.
url	Stringa	URL all'origine dell'immagine o al binario base64 dell'immagine (ad esempio, `data:image/png;base64,iVBORw0KGgo...`).

Proprietà	Digita	Descrizione
aadObjectId	Stringa	ID oggetto dell'account all'interno dell'ID Microsoft Entra.
id	Stringa	ID univoco per l'utente o il bot in questo canale.
name	string	Nome descrittivo del bot o dell'utente.
ruolo	Stringa	Ruolo dell'entità dietro l'account. Valore: user o bot.

Proprietà	Digita	Descrizione
id	Stringa	ID conversazione.
members	ChannelAccount[]	Elenco di membri in questa conversazione.

Proprietà	Digita	Descrizione
activity	Attività	Messaggio iniziale da inviare alla conversazione al momento della creazione.
bot	ChannelAccount	Informazioni sull'account del canale necessarie per indirizzare un messaggio al bot.
channelData	Oggetto	Payload specifico del canale per la creazione della conversazione.
isGroup	Boolean	Indica se si tratta di una conversazione di gruppo.
members	ChannelAccount[]	Informazioni sull'account del canale necessarie per indirizzare un messaggio a ogni utente.
tenantId	Stringa	ID tenant in cui deve essere creata la conversazione.
topicName	Stringa	Argomento della conversazione. Questa proprietà viene usata solo se supporta dal canale.

Proprietà	Digita	Description
activityId	Stringa	ID che identifica in modo univoco l'attività a cui fa riferimento questo oggetto.
bot	ChannelAccount	Un oggetto ChannelAccount che identifica il bot nella conversazione a cui fa riferimento questo oggetto.
channelId	Stringa	Un ID che identifica in modo univoco il canale nella conversazione a cui fa riferimento questo oggetto.
conversation	ConversationAccount	Un oggetto ConversationAccount che definisce la conversazione a cui fa riferimento questo oggetto.
serviceUrl	Stringa	URL che specifica l'endpoint di servizio del canale nella conversazione a cui fa riferimento questo oggetto.
user	ChannelAccount	Un oggetto ChannelAccount che identifica l'utente nella conversazione a cui fa riferimento questo oggetto.

Proprietà	Digita	Description
activityId	Stringa	ID dell'attività, se inviata.
id	Stringa	ID della risorsa.
serviceUrl	Stringa	Endpoint di servizio in cui è possibile eseguire operazioni relative alla conversazione.

Proprietà	Digita	Descrizione
conversazioni	ConversationMembers[]	Membri in ognuna delle conversazioni.
continuationToken	Stringa	Il token di continuazione che può essere usato nelle chiamate successive all'operazione Recuperare conversazioni.

Proprietà	Digita	Descrizione
code	Stringa	Codice di errore.
innerHttpError	InnerHttpError	Oggetto che rappresenta l'errore HTTP interno.
message	Stringa	Una descrizione dell'errore.

Proprietà	Digita	Descrizione
key	Stringa	Nome del fact. Ad esempio: Check-in. La chiave viene usata come etichetta quando viene visualizzato il valore del fact.
value	Stringa	Valore del fact. Ad esempio, 10 ottobre 2016.

Proprietà	Digita	Descrizione
elevation	Numero	Altitudine della posizione.
latitude	Numero	Latitudine della posizione.
longitude	Numero	Longitudine della posizione.
name	string	Nome della posizione.
type	Stringa	Tipo dell'oggetto . Sempre impostato su GeoCoordinates.

Proprietà	Digita	Descrizione
statusCode	Numero	Codice di stato HTTP della richiesta non riuscita.
body	Oggetto	Corpo della richiesta non riuscita.

Proprietà	Digita	Descrizione
profile	Stringa	Suggerimento che descrive il contenuto dei file multimediali.
url	Stringa	URL all'origine del file multimediale.

Proprietà	Digita	Descrizione
mentioned	ChannelAccount	Un oggetto ChannelAccount che specifica l'utente o il bot menzionato. Alcuni canali, ad esempio Slack, assegnano nomi per conversazione, quindi è possibile che il nome indicato dal bot (nella proprietà del destinatario del messaggio) sia diverso dall'handle specificato al momento della registrazione del bot. Tuttavia, gli ID account saranno gli stessi per entrambi.
text	Stringa	L'utente o il bot menzionato nella conversazione. Ad esempio, se il messaggio è "@ColorBot selezionare un nuovo colore", questa proprietà verrà impostata su @ColorBot. Non tutti i canali sono in grado di impostare questa proprietà.
type	Stringa	Il tipo di questo oggetto. Sempre impostato su Mention.

Proprietà	Digita	Descrizione
address	Oggetto	Indirizzo di un luogo. Questa proprietà può essere una stringa o un oggetto complesso di tipo PostalAddress.
geo	GeoCoordinates	Un oggetto GeoCoordinates che specifica le coordinate geografiche del luogo.
hasMap	Oggetto	Eseguire il mapping al luogo. Questa proprietà può essere una stringa o un oggetto complesso di tipo Map.
name	string	Nome del luogo.
type	Stringa	Il tipo di questo oggetto. Sempre impostato su Place.

Proprietà	Digita	Descrizione
Immagine	CardImage	Un oggetto CardImage che specifica l'immagine di anteprima da visualizzare accanto alla voce.
price	Stringa	Una stringa in formato di valuta che specifica il prezzo totale di tutte le unità acquistate.
quantity	Stringa	Stringa numerica che specifica il numero di unità acquistate.
subtitle	Stringa	Sottotitolo visualizzato sotto il titolo della voce.
tap	CardAction	Un oggetto CardAction che specifica l'azione da eseguire se l'utente tocca o fa clic sulla voce.
text	Stringa	Descrizione della voce.
title	Stringa	Titolo della voce.

Condividi tramite

Informazioni di riferimento sulle API per il servizio bot Framework Connessione or

URI di base

Intestazioni

Intestazioni delle richieste

Intestazioni della risposta

Codici di stato HTTP

Errors

Operazioni riguardanti la conversazione

Creare una conversazione

Attività Delete

Eliminare un membro della conversazione

Recuperare i membri dell'attività

Ottenere conversazioni

Ottenere un membro della conversazione

GetConversationMembers

Ottenere membri con pagine di conversazione

Rispondi all'attività

Invia cronologia conversazioni

Invia alla conversazione

UpdateActivity

Caricare l'allegato nel canale

Operazioni relative agli allegati

Ottenere informazioni sugli allegati

Ottieni allegato

Operazioni relative allo stato (deprecate)

Schema

Oggetto Activity

Oggetto AnimationCard

Oggetto Attachment

Oggetto AttachmentData

Oggetto AttachmentInfo

Oggetto AttachmentView

Oggetto AudioCard

Oggetto CardAction

Oggetto CardImage

Oggetto ChannelAccount

Oggetto ConversationAccount

Oggetto ConversationMembers

Oggetto ConversationParameters

Oggetto ConversationReference

Oggetto ConversationResourceResponse

Oggetto ConversationsResult

Oggetto Entity

Oggetto errore

Oggetto ErrorResponse

Oggetto Fact

Oggetto GeoCoordinates

Oggetto HeroCard

Oggetto InnerHttpError

Oggetto MediaEventValue

Oggetto MediaUrl

Oggetto Mention

Oggetto MessageReaction

Oggetto PagedMembersResult

Oggetto Place

Oggetto ReceiptCard

Oggetto ReceiptItem

Oggetto ResourceResponse

Oggetto SemanticAction

Oggetto SignInCard

Oggetto SuggestedActions

Oggetto TextHighlight

Oggetto ThumbnailCard

Oggetto ThumbnailUrl

Oggetto Transcript

Oggetto VideoCard

Risorse aggiuntive

Proprietà	Digita	Descrizione
entities	Oggetto	Oggetto in cui il valore di ogni proprietà è un oggetto Entity.
id	Stringa	ID di questa azione.
state	Stringa	Stato di questa azione. Valori consentiti: start, continue, done.

Proprietà	Digita	Descrizione
actions	CardAction[]	Matrice di oggetti CardAction che definiscono le azioni consigliate.
to	String[]	Matrice di stringhe contenente gli ID dei destinatari che devono visualizzare le azioni consigliate.

Proprietà	Digita	Descrizione
occurrence	Numero	Occorrenza del campo di testo all'interno del testo a cui si fa riferimento, se ne esiste più di una.
text	Stringa	Definisce il frammento di testo da evidenziare.

Proprietà	Digita	Descrizione
aspect	Stringa	Proporzioni del video. Valore: 16:9 o 4:3.
autoloop	Boolean	Flag che indica se riprodurre nuovamente l'elenco di video quando l'ultimo termina. Impostare questa proprietà su true per riprodurre di nuovo i video in modo automatico; in caso contrario, impostare su false. Il valore predefinito è true.
autostart	Boolean	Flag che indica se riprodurre automaticamente i video quando viene visualizzata la scheda. Impostare questa proprietà su true per riprodurre automaticamente i video; in caso contrario, impostare su false. Il valore predefinito è true.
buttons	CardAction[]	Matrice di oggetti CardAction che consentono all'utente di eseguire una o più azioni. Il canale determina il numero di pulsanti che è possibile specificare.
duration	Stringa	Durata del contenuto multimediale nel formato di durata ISO 8601.
Immagine	ThumbnailUrl	Un oggetto ThumbnailUrl che specifica l'immagine da visualizzare sulla scheda.
media	MediaUrl[]	Matrice di MediaUrl. Quando questo campo contiene più URL, ogni URL è un formato alternativo dello stesso contenuto.
shareable	Boolean	Flag che indica se i video possono essere condivisi con altri utenti. Impostare questa proprietà su true se i video possono essere condivisi; in caso contrario, impostare su false. Il valore predefinito è true.
subtitle	Stringa	Sottotitolo da visualizzare sotto il titolo della scheda.
text	Stringa	Descrizione o prompt da visualizzare sotto il titolo della scheda o il sottotitolo.
title	Stringa	Titolo della scheda.
value	Oggetto	Parametro supplementare per questa scheda