Référence API pour le service Bot Framework Connector

Article
12/21/2023

Remarque

L'API REST n'est pas équivalente au Kit de développement logiciel (SDK). L’API REST permet une communication standard REST. Toutefois, la méthode d’interaction recommandée avec Bot Framework reste le SDK.

Au sein de Bot Framework, le service Bot Connector permet à votre bot d’échanger des messages avec des utilisateurs sur des canaux configurés dans le portail Bot Framework. Le service utilise les ressources REST et JSON standard sur HTTPS.

L'URI de base

Lorsqu’un utilisateur envoie un message à votre bot, la requête entrante contient un objet Activity avec une propriété serviceUrl qui spécifie le point de terminaison auquel votre bot doit envoyer sa réponse. Pour accéder au service Bot Connector, utilisez la valeur serviceUrl comme URI de base pour les requêtes d’API.

Quand vous n'avez pas encore d'URL de service pour le canal, utilisez https://smba.trafficmanager.net/teams/ comme URL de service. Pour plus d'informations, consultez comment créer une conversation et un message proactif dans Teams.

Supposons, par exemple, que votre bot reçoive l’activité suivante lorsque l’utilisateur lui envoie un message.

{
    "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 propriété serviceUrl dans le message de l'utilisateur indique que le bot doit envoyer sa réponse au point de terminaison https://smba.trafficmanager.net/teams/. L'URL de service sera l'URI de base pour toutes les demandes suivantes qu'émet le bot dans le contexte de cette conversation. Si votre bot a besoin d’envoyer un message proactif à l’utilisateur, veillez à enregistrer la valeur de serviceUrl.

L’exemple suivant montre la requête émise par le bot pour répondre au message de l’utilisateur.

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..."
}

En-têtes

En-têtes de requête

Outre les en-têtes de requête HTTP standard, chaque requête d’API que vous émettez doit inclure un en-tête Authorization qui spécifie un jeton d’accès permettant d’authentifier votre bot. Spécifiez l’en-tête Authorization au format suivant :

Authorization: Bearer ACCESS_TOKEN

Pour plus d’informations sur l’obtention d’un jeton d’accès pour votre bot, consultez Authentifier les requêtes envoyées par votre bot au service Bot Connector.

En-têtes de réponse

Outre les en-têtes de réponse HTTP standard, chaque réponse contient un en-tête X-Correlating-OperationId. La valeur de cet en-tête est un ID qui correspond à l'entrée de journal Bot Framework, dans laquelle se trouvent des informations détaillées sur la requête. Lorsque vous recevez une réponse d'erreur, vous devez capturer la valeur de cet en-tête. Si vous ne parvenez pas à résoudre le problème, fournissez cette valeur à l'équipe de support technique lorsque vous lui signalez le problème.

Codes d’état HTTP

Le code d’état HTTP retourné avec chaque réponse indique le résultat de la requête correspondante.

Remarque

Le tableau suivant décrit les codes d'état HTTP les plus courants. Certaines erreurs sont générées par le canal. Pour plus d'informations, vous devrez peut-être lire la documentation du développeur du canal.

Code de statut HTTP	Signification
200	La requête a réussi.
201	La requête a réussi.
202	La demande a été acceptée pour traitement.
204	La requête a réussi, mais aucun contenu n’a été retourné.
400	La requête présentait un format inadéquat ou était incorrecte.
401	Le bot n'est pas encore authentifié.
403	Le bot n'est pas autorisé à effectuer l'opération demandée.
404	La ressource demandée est introuvable.
405	Ce canal ne prend pas en charge l'opération demandée.
500	Une erreur de serveur interne s’est produite.
503	Le service est temporairement indisponible.

Erreurs

Toute réponse qui spécifie un code d’état HTTP dans la plage 4xx ou 5xx va inclure un objet ErrorResponse dans le corps de la réponse qui fournit des informations sur l’erreur. Si vous recevez une réponse d’erreur dans la plage 4xx, examinez l’objet ErrorResponse pour identifier la cause de l’erreur et résoudre votre problème avant de renvoyer la requête.

Opérations de conversation

Utilisez ces opérations pour créer des conversations, envoyer des messages (activités) et gérer le contenu des conversations.

Important

Tous les canaux ne prennent pas en charge tous les points de terminaison. Toutefois, tous les canaux doivent prendre en charge la réponse au point de terminaison d'activité.

Par exemple, seule Direct Line et Chat Web prennent en charge le point de terminaison obtenir des conversations.

Operation	Description
Créer une conversation	Crée une conversation.
Supprimer l’activité	Supprime une activité existante.
Supprimer un membre de conversation	Supprime un membre d’une conversation.
Obtenir les membres d'une activité	Obtient les membres de l’activité spécifiée dans la conversation spécifiée.
Obtenir un membre de conversation	Obtient des détails sur un membre d’une conversation.
Obtenir des membres de conversation	Obtient les membres de la conversation spécifiée.
Obtenir des membres paginés de conversation	Obtient les membres de la conversation spécifiée, une page à la fois.
Obtenir des conversations	Obtient la liste des conversations auxquelles un robot a participé.
Répondre à l'activité	Envoie une activité (message) à la conversation spécifiée, en réponse à l’activité spécifiée.
Envoyer l’historique des conversations	Charge une transcription des activités passées de la conversation.
Envoyer vers la conversation	Envoie une activité (message) à la fin de la conversation spécifiée.
Mettre à jour l'activité	Met à jour une activité existante.
Charger la pièce jointe vers le canal	Charge une pièce jointe directement dans le stockage d’objets blob d’un canal.

Créer une conversation

Crée une conversation.

POST /v3/conversations

Contenu	Description
Corps de la demande	Un objet ConversationParameters
Renvoie	Objet ConversationResourceResponse

Supprimer l’activité

Certains canaux vous permettent de supprimer une activité existante. En cas de réussite, cette opération supprime l’activité spécifiée dans la conversation spécifiée.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Code d’état HTTP indiquant le résultat de l’opération. Rien n’est spécifié dans le corps de la réponse.

Supprimer un membre de conversation

Supprime un membre d’une conversation. Si ce membre a été le dernier membre de la conversation, la conversation est également supprimée.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Code d’état HTTP indiquant le résultat de l’opération. Rien n’est spécifié dans le corps de la réponse.

Obtenir les membres d’une activité

Obtient les membres de l’activité spécifiée dans la conversation spécifiée.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Tableau d’objets ChannelAccount

Obtenir des conversations

Obtient la liste des conversations auxquelles un robot a participé.

GET /v3/conversations?continuationToken={continuationToken}

Contenu	Description
Corps de la demande	n/a
Renvoie	Objet ConversationsResult

Obtenir un membre de conversation

Obtient des détails sur un membre spécifique d’une conversation spécifique.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Objet ChannelAccount pour le membre.

GetConversationMembers

Obtient les membres de la conversation spécifiée.

GET /v3/conversations/{conversationId}/members

Contenu	Description
Corps de la demande	n/a
Renvoie	Tableau d’objets ChannelAccount qui identifient les membres de la conversation.

Obtenir les membres paginés de conversation

Obtient les membres de la conversation spécifiée, une page à la fois.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Objet PagedMembersResult

Répondre à l'activité

Envoie une activité (message) à la conversation spécifiée, en réponse à l’activité spécifiée. L’activité sera ajoutée comme réponse à une autre activité, si le canal le permet. Si le canal ne prend pas en charge les réponses imbriquées, cette opération se comporte comme l'opération Envoyer vers la conversation.

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

Contenu	Description
Corps de la demande	Objet Activity
Renvoie	Objet ResourceResponse

Envoyer l'historique des conversations

Charge une transcription des activités passées de la conversation pour permettre au client de les afficher.

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

Contenu	Description
Corps de la demande	Objet Transcript.
Renvoie	Objet ResourceResponse.

Envoyer vers la conversation

Envoie une activité (message) vers la conversation spécifiée. L’activité est ajoutée à la fin de la conversation, selon l’horodatage ou la sémantique du canal. Pour répondre à un message de la conversation, utilisez plutôt Répondre à l’activité.

POST /v3/conversations/{conversationId}/activities

Contenu	Description
Corps de la demande	Objet Activity
Renvoie	Objet ResourceResponse

UpdateActivity

Certains canaux vous permettent de modifier une activité existante afin de refléter le nouvel état d’une conversation de bot. Par exemple, vous pouvez supprimer des boutons dans un message de la conversation après qu’un utilisateur a cliqué sur l’un d’eux. En cas de réussite, cette opération met à jour l’activité spécifiée dans la conversation spécifiée.

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

Contenu	Description
Corps de la demande	Objet Activity
Renvoie	Objet ResourceResponse

Charger la pièce jointe vers le canal

Charge une pièce jointe pour la conversation spécifiée, directement dans le stockage d’objets blob d’un canal. Cela permet de stocker des données dans un magasin conforme.

POST /v3/conversations/{conversationId}/attachments

Contenu	Description
Corps de la demande	Objet AttachmentData.
Renvoie	Objet ResourceResponse. La propriété id spécifie l'ID de la pièce jointe qui peut être utilisée avec l'opération Obtenir des informations sur la pièce jointe et l'opération Obtenir la pièce jointe.

Opérations de pièce jointe

Utilisez ces opérations pour récupérer des informations sur une pièce jointe, ainsi que les données binaires du fichier.

Operation	Description
Obtenir les informations de la pièce jointe	Obtient des informations sur la pièce jointe spécifiée, notamment le nom du fichier, le type du fichier et les vues disponibles (par exemple affichage d'origine ou miniature).
Obtenir la pièce jointe	Obtient l’affichage spécifié de la pièce jointe spécifiée sous forme de contenu binaire.

Obtenir des informations sur la pièce jointe

Obtient des informations sur la pièce jointe spécifiée, notamment le nom du fichier, le type et les vues disponibles (par exemple affichage d'origine ou miniature).

GET /v3/attachments/{attachmentId}

Contenu	Description
Corps de la demande	n/a
Renvoie	Objet AttachmentInfo

Obtenir une pièce jointe

Obtient l’affichage spécifié de la pièce jointe spécifiée sous forme de contenu binaire.

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

Contenu	Description
Corps de la demande	n/a
Renvoie	Contenu binaire qui représente l’affichage spécifié de la pièce jointe spécifiée.

Opérations d’état (dépréciées)

Le service Microsoft Bot Framework State a été mis hors service le 30 mars 2018. Auparavant, les bots basés sur Azure AI Bot Service ou le kit de développement logiciel (SDK) Bot Builder avaient une connexion par défaut à ce service hébergé par Microsoft pour stocker les données Bot State. Les bots doivent être mis à jour pour utiliser leur propre stockage d’état.

Operation	Description
`Set User Data`	Stocke les données d’état pour un utilisateur d’un canal.
`Set Conversation Data`	Stocke les données d’état pour une conversation d’un canal.
`Set Private Conversation Data`	Stocke les données d’état d’un utilisateur dans le contexte d’une conversation d’un canal.
`Get User Data`	Récupère les données d’état précédemment stockées pour un utilisateur dans toutes les conversations d’un canal.
`Get Conversation Data`	Récupère les données d’état précédemment stockées pour une conversation d’un canal.
`Get Private Conversation Data`	Récupère les données d’état précédemment stockées pour un utilisateur dans le contexte d’une conversation d’un canal.
`Delete State For User`	Supprime les données d’état qui ont été précédemment stockées pour un utilisateur.

schéma

Le schéma Bot Framework définit les objets et leurs propriétés que votre bot peut utiliser pour communiquer avec un utilisateur.

Object	Description
Objet Activity	Définit un message qui est échangé entre le bot et l’utilisateur.
Objet AnimationCard	Définit une carte pouvant lire des images GIF animées ou de courtes vidéos.
Objet Attachment	Définit des informations supplémentaires à inclure dans le message. Une pièce jointe peut être un fichier multimédia (par exemple audio, vidéo, image, fichier) ou une carte enrichie.
Objet AttachmentData	Décrit les données d’une pièce jointe.
Objet AttachmentInfo	Décrit une pièce jointe.
Objet AttachmentView	Définit un objet qui représente une vue disponible pour une pièce jointe.
Objet AudioCard	Définit une carte qui peut lire un fichier audio.
Objet CardAction	Définit une action à effectuer.
Objet CardImage	Définit l’image à afficher sur une carte.
Objet ChannelAccount	Définit le bot ou le compte d’utilisateur sur le canal.
Objet ConversationAccount	Définit une conversation sur un canal.
Objet ConversationMembers	Définit les membres d’une conversation.
Objet ConversationParameters	Définit des paramètres pour la création d’une conversation.
Objet ConversationReference	Définit un endroit particulier d’une conversation.
Objet ConversationResourceResponse	Définit une réponse à Créer une conversation.
Objet ConversationsResult	Définit le résultat d’un appel de Obtenir des conversations.
Objet Entity	Définit un objet d’entité.
Objet Error	Définit une erreur.
Objet ErrorResponse	Définit une réponse d’API HTTP.
Objet Fact	Définit une paire clé-valeur contenant un fait.
Objet GeoCoordinates	Définit un emplacement géographique à l’aide des coordonnées World Geodetic System (WSG84).
Objet HeroCard	Définit une carte avec une grande image, un titre, du texte et des boutons d’action.
Objet InnerHttpError	Objet représentant une erreur HTTP interne.
Objet MediaEventValue	Paramètre supplémentaire des événements multimédias.
Objet MediaUrl	Définit l’URL de la source d’un fichier multimédia.
Objet Mention	Définit un utilisateur ou un bot mentionné dans la conversation.
Objet MessageReaction	Définit une réaction à un message.
Objet PagedMembersResult	Page de membres retournée par Obtenir les membres paginés de la conversation.
Objet Place	Définit un lieu mentionné dans la conversation.
Objet ReceiptCard	Définit une carte qui contient un reçu pour un achat.
Objet ReceiptItem	Définit une ligne dans un reçu.
Objet ResourceResponse	Définit une ressource.
Objet SemanticAction	Définit une référence à une action de programmation.
Objet SignInCard	Définit une carte qui permet à un utilisateur de se connecter à un service.
Objet SuggestedActions	Définit les options qu’un utilisateur peut choisir.
Objet TextHighlight	Référence une sous-chaîne de contenu dans un autre champ.
Objet ThumbnailCard	Définit une carte avec une miniature, un titre, du texte et des boutons d’action.
Objet ThumbnailUrl	Définit l’URL de la source d’une image.
Objet Transcript	Collection d’activités à charger à l’aide de Envoyer l’historique des conversations.
Objet VideoCard	Définit une carte pouvant lire des vidéos.

Objet Activity

Définit un message qui est échangé entre le bot et l’utilisateur.

Propriété	Type	Description
action	Chaîne	Action à appliquer ou qui a été appliquée. Utilisez la propriété type pour déterminer le contexte de l’action. Par exemple, si type a la valeur contactRelationUpdate, la valeur de la propriété action sera add si l’utilisateur ajoute votre bot à sa liste de contacts, ou remove s’il supprime votre bot de sa liste de contacts.
attachmentLayout	Chaîne	Disposition des pièces jointes de la carte enrichie incluses dans le message. Peut avoir l’une des valeurs suivantes : carousel, list. Pour plus d’informations sur les pièces jointes de carte enrichie, consultez Ajouter des pièces jointes de cartes enrichies aux messages.
attachments	Attachment[]	Tableau d’objets Attachment qui définit des informations supplémentaires à inclure dans le message. Chaque pièce jointe peut être soit un fichier multimédia (par exemple audio, vidéo, image), soit une carte enrichie.
callerId	Chaîne	Chaîne contenant un IRI identifiant l’appelant d’un bot. Ce champ n'est pas destiné à être transmis par câble, mais il est rempli par les bots et les clients sur la base de données vérifiables par chiffrement qui affirment l'identité des appelants (par exemple, des jetons).
channelData	Object	Objet contenant le contenu propre au canal. Certains canaux fournissent des caractéristiques qui nécessitent des informations supplémentaires impossibles à représenter à l'aide du schéma de pièce jointe. Dans ce type de cas, définissez cette propriété sur le contenu propre au canal, tel que défini dans la documentation du canal. Pour plus d’informations, consultez Implémenter des fonctionnalités spécifiques au canal.
channelId	Chaîne	ID qui identifie de façon unique le canal. Défini par le canal.
code	Chaîne	Code indiquant pourquoi la conversation s’est terminée.
conversation	ConversationAccount	Objet ConversationAccount qui définit la conversation à laquelle appartient l’activité.
deliveryMode	Chaîne	Indicateur de distribution pour signaler au destinataire d’autres chemins de distribution pour l’activité. Une des valeurs suivantes : normal, notification.
entities	object[]	Tableau d’objets qui représente les entités mentionnées dans le message. Les objets de ce tableau peuvent correspondre à n’importe quel objet Schema.org. Par exemple, le tableau peut inclure des objets Mention qui identifient une personne mentionnée dans la conversation, ainsi que des objets Place qui identifient un lieu mentionné dans la conversation.
expiration	Chaîne	Heure à laquelle l'activité doit être considérée comme étant « expirée » et ne doit pas être présentée au destinataire.
from	ChannelAccount	Objet ChannelAccount qui spécifie l’expéditeur du message.
historyDisclosed	Boolean	Indicateur qui indique si l’historique est divulgué ou non. La valeur par défaut est False.
id	Chaîne	ID qui identifie de façon unique l’activité sur le canal.
importance	Chaîne	Définit l’importance d’une activité. Une des valeurs suivantes : low, normal, high.
inputHint	Chaîne	Valeur qui indique si votre bot accepte, attend ou ignore l’entrée utilisateur, une fois le message remis au client. Peut avoir l’une des valeurs suivantes : acceptingInput, expectingInput, ignoringInput.
label	Chaîne	Étiquette descriptive de l’activité.
listenFor	String[]	Liste des expressions et des références dont les systèmes d’amorçage de la parole et de la langue doivent être à l’écoute.
locale	Chaîne	Paramètres régionaux de la langue qui doit être utilisée pour afficher du texte dans le message, au format `<language>-<country>`. Le canal utilise cette propriété pour indiquer la langue de l’utilisateur, pour que le bot puisse spécifier des chaînes d’affichage dans cette langue. La valeur par défaut est en-US.
localTimestamp	Chaîne	Date et heure auxquelles le message a été envoyé dans le fuseau horaire local, exprimées au format ISO-8601.
localTimezone	Chaîne	Contient le nom du fuseau horaire local du message, exprimé au format de base de données de fuseau horaire IANA. Par exemple, America/Los_Angeles.
membersAdded	ChannelAccount[]	Tableau d’objets ChannelAccount qui représente la liste des utilisateurs qui ont rejoint la conversation. Présent uniquement si le type d’activité est « conversationUpdate » et si les utilisateurs ont rejoint la conversation.
membersRemoved	ChannelAccount[]	Tableau d’objets ChannelAccount qui représente la liste des utilisateurs qui ont quitté la conversation. Présent uniquement si le type d’activité est « conversationUpdate » et si les utilisateurs ont quitté la conversation.
name	Chaîne	Nom de l’opération à appeler ou nom de l’événement.
reactionsAdded	MessageReaction[]	Collection de réactions ajoutées à la conversation.
reactionsRemoved	MessageReaction[]	Collection de réactions supprimées de la conversation.
recipient	ChannelAccount	Objet ChannelAccount qui spécifie le destinataire du message.
relatesTo	ConversationReference	Objet ConversationReference qui définit un endroit particulier de la conversation.
replyToId	Chaîne	ID du message auquel ce message répond. Pour répondre à un message envoyé par l’utilisateur, définissez cette propriété sur l’ID du message de l’utilisateur. Certains canaux ne prennent pas en charge les réponses à thread. Dans ce cas, le canal ignore cette propriété et utilise une sémantique chronologique (horodatage) pour ajouter le message à la conversation.
semanticAction	SemanticAction	Un objet SemanticAction qui représente une référence à une action de programmation.
serviceUrl	Chaîne	URL qui spécifie le point de terminaison de service du canal. Défini par le canal.
speak	Chaîne	Texte que doit prononcer votre bot sur un canal où les fonctionnalités vocales sont activées. Pour contrôler les différentes caractéristiques vocales de votre bot, telles que la voix, le débit, le volume, la prononciation et la hauteur, spécifiez cette propriété au format SSML (Speech Synthesis Markup Language).
suggestedActions	SuggestedActions	Objet SuggestedActions qui définit les options qu’un utilisateur peut choisir.
summary	Chaîne	Résumé des informations que contient le message. Par exemple, pour un message envoyé sur un canal d’e-mail, cette propriété peut spécifier les 50 premiers caractères de l’e-mail.
texte	Chaîne	Texte du message envoyé par l’utilisateur au bot ou par le bot à l’utilisateur. Consultez la documentation du canal pour connaître les limites qui sont imposées au contenu de cette propriété.
textFormat	Chaîne	Format du texte du message. Peut avoir l’une des valeurs suivantes : markdown, plain, xml. Pour plus d’informations sur le format du texte, consultez Créer des messages.
textHighlights	TextHighlight[]	Collection de fragments de texte à mettre en surbrillance quand l’activité contient une valeur replyToId.
timestamp	Chaîne	Date et heure auxquelles le message a été envoyé dans le fuseau horaire UTC, exprimées au format ISO-8601.
topicName	Chaîne	Sujet de la conversation à laquelle appartient l’activité.
type	Chaîne	Type d’activité. Une des valeurs suivantes : message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Pour plus d’informations sur les types d’activités, consultez Vue d’ensemble des activités.
value	Object	Valeur à durée indéterminée.
valueType	Chaîne	Type de l’objet de valeur de l’activité.

Propriété	Type	Description
aspect	Boolean	Proportions de l’espace réservé des miniatures/médias. Les valeurs autorisées sont « 16:9 » et « 4:3 ».
autoloop	Boolean	Indicateur qui indique s’il faut relire la liste des images GIF animées lorsque la dernière est terminée. Définissez cette propriété sur true pour relire automatiquement l’animation ; sinon, définissez-la sur false. La valeur par défaut est true.
autostart	Boolean	Indicateur qui indique s’il faut lire automatiquement l’animation lorsque la carte s’affiche. Définissez cette propriété sur true pour lire automatiquement l’animation ; sinon, définissez-la sur false. La valeur par défaut est true.
buttons	CardAction[]	Tableau d’objets CardAction qui permettent à l’utilisateur d’effectuer une ou plusieurs actions. Le canal détermine le nombre de boutons que vous pouvez spécifier.
duration	Chaîne	La longueur du contenu du média, au format de durée ISO 8601.
image	ThumbnailUrl	Objet ThumbnailUrl qui spécifie l’image à afficher sur la carte.
media	MediaUrl[]	Tableau d’objets MediaUrl. Quand ce champ contient plusieurs URL, chaque URL est un autre format du même contenu.
shareable	Boolean	Indicateur qui indique si l’animation peut être partagée avec d’autres utilisateurs. Définissez cette propriété sur true si l’animation peut être partagée ; sinon, sur false. La valeur par défaut est true.
subtitle	Chaîne	Sous-titre à afficher sous le titre de la carte.
texte	Chaîne	Description ou invitation à afficher sous le titre ou le sous-titre de la carte.
title	Chaîne	Titre de la carte.
value	Object	Paramètre supplémentaire pour cette carte.

Propriété	Type	Description
content	Object	Contenu de la pièce jointe. Si la pièce jointe est une carte enrichie, définissez cette propriété sur l’objet de carte enrichie. Cette propriété et la propriété contentUrl s’excluent mutuellement.
contentType	Chaîne	Type de média du contenu de la pièce jointe. Pour les fichiers multimédias, définissez cette propriété sur les types de médias connus comme image/png, audio/wav ou video/mp4. Pour les cartes enrichies, définissez cette propriété sur l’un de ces types spécifiques au fabricant : application/vnd.microsoft.card.adaptive : carte pouvant inclure toute combinaison de texte, données vocales, images, boutons et champs d’entrée. Définissez la propriété content sur un objet AdaptiveCard. application/vnd.Microsoft.Card.Animation : carte enrichie qui lit l’animation. Définissez la propriété content sur un objet AnimationCard. application/vnd.microsoft.card.audio : carte enrichie qui lit les fichiers audio. Définissez la propriété content sur un objet AudioCard. application/vnd.microsoft.card.hero : carte Héros. Définissez la propriété content sur un objet HeroCard. application/vnd.microsoft.card.receipt : une carte de reçu. Définissez la propriété content sur un objet ReceiptCard. application/vnd.microsoft.com.card.signin : une carte de connexion utilisateur. Définissez la propriété content sur un objet SignInCard. application/vnd.microsoft.card.thumbnail : carte de miniature. Définissez la propriété content sur un objet ThumbnailCard. application/vnd.microsoft.card.video : carte enrichie qui lit les vidéos. Définissez la propriété content sur un objet VideoCard.
contentUrl	Chaîne	URL du contenu de la pièce jointe. Par exemple, si la pièce jointe est une image, vous pouvez définir contentUrl sur l’URL qui représente l’emplacement de l’image. Protocoles pris en charge : HTTP, HTTPS, fichiers et données.
name	Chaîne	Nom de la pièce jointe.
thumbnailUrl	Chaîne	URL d’une image miniature que le canal peut utiliser s’il prend en charge l’utilisation d’une forme plus petite de content ou de contentUrl. Par exemple, si vous définissez contentType sur application/word et définissez contentUrl sur l’emplacement du document Word, vous pouvez inclure une image miniature qui représente le document. Le canal peut alors afficher l’image miniature au lieu du document. Lorsque l’utilisateur clique sur l’image, le canal ouvre le document.

Propriété	Type	Description
size	Number	Taille du fichier.
viewId	Chaîne	ID de l’affichage.

Propriété	Type	Description
aspect	Chaîne	Proportions de la miniature qui est spécifiée dans la propriété image. Les valeurs valides sont 16:9 et 4:3.
autoloop	Boolean	Indicateur qui indique s’il faut relire la liste des fichiers audio lorsque le dernier est terminé. Définissez cette propriété sur true pour relire automatiquement les fichiers audio ; sinon, définissez-la sur false. La valeur par défaut est true.
autostart	Boolean	Indicateur qui indique s’il faut lire automatiquement le fichier audio lorsque la carte s’affiche. Définissez cette propriété sur true pour relire automatiquement les fichiers audio ; sinon, définissez-la sur false. La valeur par défaut est true.
buttons	CardAction[]	Tableau d’objets CardAction qui permettent à l’utilisateur d’effectuer une ou plusieurs actions. Le canal détermine le nombre de boutons que vous pouvez spécifier.
duration	Chaîne	La longueur du contenu du média, au format de durée ISO 8601.
image	ThumbnailUrl	Objet ThumbnailUrl qui spécifie l’image à afficher sur la carte.
media	MediaUrl[]	Tableau d’objets MediaUrl. Quand ce champ contient plusieurs URL, chaque URL est un autre format du même contenu.
shareable	Boolean	Indicateur qui indique si les fichiers audio peuvent être partagés avec d’autres utilisateurs. Définissez cette propriété sur true si les fichiers audio peuvent être partagés ; sinon, sur false. La valeur par défaut est true.
subtitle	Chaîne	Sous-titre à afficher sous le titre de la carte.
texte	Chaîne	Description ou invitation à afficher sous le titre ou le sous-titre de la carte.
title	Chaîne	Titre de la carte.
value	Object	Paramètre supplémentaire pour cette carte.

Propriété	Type	Description
channelData	Chaîne	Données spécifiques au canal associées à cette action.
displayText	Chaîne	Texte à afficher dans le flux de conversation si l’utilisateur clique sur le bouton.
image	Chaîne	URL de l'image qui apparaît sur le bouton, à côté de l'étiquette de texte.
texte	Chaîne	Texte de l’action.
title	Chaîne	Description du texte qui apparaît sur le bouton.
type	Chaîne	Type d’action à effectuer. Pour obtenir la liste des valeurs valides, consultez Ajouter des pièces jointes de cartes riches aux messages.
value	Object	Paramètre supplémentaire de l’action. Le comportement de cette propriété varie en fonction du type de l’action. Pour plus d’informations, consultez Ajouter des pièces jointes de cartes enrichies aux messages.

Propriété	Type	Description
alt	Chaîne	Description de l’image. Vous devez inclure la description pour des raisons d’accessibilité.
tap	CardAction	Objet CardAction qui spécifie l’action à effectuer si l’utilisateur appuie ou clique sur l’image.
url	Chaîne	URL de la source de l’image ou du fichier binaire en base64 de l’image (par exemple, `data:image/png;base64,iVBORw0KGgo...`).

Propriété	Type	Description
aadObjectId	Chaîne	L'ID d'objet de ce compte dans Microsoft Entra ID.
id	Chaîne	ID unique de l’utilisateur ou du robot sur ce canal.
name	Chaîne	Nom convivial du robot ou de l’utilisateur.
role	Chaîne	Rôle de l’entité derrière le compte. user ou bot.

Propriété	Type	Description
id	Chaîne	ID de conversation.
members	ChannelAccount[]	Liste des membres de cette conversation.

Propriété	Type	Description
activity	Activité	Message initial à envoyer à la conversation quand elle est créée.
bot	ChannelAccount	Informations de compte de canal nécessaires à l’acheminement d’un message vers le robot.
channelData	Object	Charge utile spécifique au canal pour la création de la conversation.
isGroup	Boolean	Indique s’il s’agit d’une conversation de groupe.
members	ChannelAccount[]	Informations de compte de canal nécessaires à l’acheminement d’un message vers chaque utilisateur.
tenantId	Chaîne	ID de locataire dans lequel la conversation doit être créée.
topicName	Chaîne	Sujet de la conversation. Cette propriété est uniquement utilisée si le canal la prend en charge.

Propriété	Type	Description
activityId	Chaîne	ID qui identifie de façon unique l’activité que cet objet référence.
bot	ChannelAccount	Objet ChannelAccount qui identifie le bot dans la conversation référencée par cet objet.
channelId	Chaîne	ID qui identifie de façon unique le canal dans la conversation référencée par cet objet.
conversation	ConversationAccount	Objet ConversationAccount qui définit la conversation référencée par cet objet.
serviceUrl	Chaîne	URL qui spécifie le point de terminaison de service du canal dans la conversation référencée par cet objet.
utilisateur	ChannelAccount	Objet ChannelAccount qui identifie l’utilisateur dans la conversation référencée par cet objet.

Propriété	Type	Description
activityId	Chaîne	ID de l’activité, si elle est envoyée.
id	Chaîne	ID de la ressource.
serviceUrl	Chaîne	Point de terminaison de service dans lequel les opérations relatives à la conversation peuvent être effectuées.

Propriété	Type	Description
conversations	ConversationMembers[]	Membres dans chacune des conversations.
continuationToken	Chaîne	Jeton de continuation qui peut être utilisé dans les appels postérieurs à l’appel de Obtenir des conversations.

Propriété	Type	Description
code	Chaîne	Code d’erreur.
innerHttpError	InnerHttpError	Objet représentant l’erreur HTTP interne.
message	Chaîne	Description de l’erreur.

Propriété	Type	Description
key	Chaîne	Nom du fait. Par exemple : Archivage. La clé est utilisée comme étiquette quand vous affichez la valeur du fait.
value	Chaîne	Valeur du fait. Par exemple, 10 octobre 2016.

Propriété	Type	Description
elevation	Number	Élévation de l’emplacement.
latitude	Number	Latitude de l’emplacement.
longitude	Number	Longitude de l’emplacement.
name	Chaîne	Nom de l’emplacement.
type	Chaîne	Type de cet objet . Toujours définir sur GeoCoordinates.

Propriété	Type	Description
statusCode	Number	Code d’état HTTP de la requête en échec.
corps	Object	Corps de la requête en échec.

Propriété	Type	Description
profile	Chaîne	Indicateur qui décrit le contenu du fichier multimédia.
url	Chaîne	URL de la source du fichier multimédia.

Propriété	Type	Description
mentioned	ChannelAccount	Objet ChannelAccount qui spécifie l’utilisateur ou le bot mentionné. Certains canaux, comme Slack, attribuent des noms par conversation, il est donc possible que le nom mentionné par votre bot (dans la propriété du destinataire du message) soit différent du gestionnaire que vous avez spécifié lors de l'inscription de votre bot. Toutefois, l’ID de compte des deux noms reste le même.
texte	Chaîne	Utilisateur ou bot mentionné dans la conversation. Par exemple, si le message est « @ColorBot choisissez une nouvelle couleur », cette propriété sera définie sur @ColorBot. Certains canaux ne définissent pas cette propriété.
type	Chaîne	Type de cet objet. Toujours définir sur Mention.

Propriété	Type	Description
address	Object	Adresse d’un lieu. Cette propriété peut être une chaîne ou un objet complexe de type PostalAddress.
geo	GeoCoordinates	Objet GeoCoordinates qui spécifie les coordonnées géographiques du lieu.
hasMap	Object	Carte du lieu. Cette propriété peut être une chaîne (URL) ou un objet complexe de type Map.
name	Chaîne	Nom du lieu.
type	Chaîne	Type de cet objet. Toujours définir sur Place.

Propriété	Type	Description
image	CardImage	Objet CardImage qui spécifie l’image miniature à afficher à côté de la ligne.
price	Chaîne	Chaîne au format devise qui spécifie le prix total de toutes les unités achetées.
quantity	Chaîne	Chaîne numérique qui spécifie le nombre d’unités achetées.
subtitle	Chaîne	Sous-titre à afficher sous le titre de la ligne.
tap	CardAction	Objet CardAction qui spécifie l’action à effectuer si l’utilisateur appuie ou clique sur la ligne.
texte	Chaîne	Description de la ligne.
title	Chaîne	Titre de la ligne.

Référence API pour le service Bot Framework Connector

L'URI de base

En-têtes

En-têtes de requête

En-têtes de réponse

Codes d’état HTTP

Erreurs

Opérations de conversation

Créer une conversation

Supprimer l’activité

Supprimer un membre de conversation

Obtenir les membres d’une activité

Obtenir des conversations

Obtenir un membre de conversation

GetConversationMembers

Obtenir les membres paginés de conversation

Répondre à l'activité

Envoyer l'historique des conversations

Envoyer vers la conversation

UpdateActivity

Charger la pièce jointe vers le canal

Opérations de pièce jointe

Obtenir des informations sur la pièce jointe

Obtenir une pièce jointe

Opérations d’état (dépréciées)

schéma

Objet Activity

Objet AnimationCard

Objet Attachment

Objet AttachmentData

Objet AttachmentInfo

Objet AttachmentView

Objet AudioCard

Objet CardAction

Objet CardImage

Objet ChannelAccount

Objet ConversationAccount

Objet ConversationMembers

Objet ConversationParameters

Objet ConversationReference

Objet ConversationResourceResponse

Objet ConversationsResult

Objet Entity

Objet Error

Objet ErrorResponse

Objet Fact

Objet GeoCoordinates

Objet HeroCard

Objet InnerHttpError

Objet MediaEventValue

Objet MediaUrl

Objet Mention

Objet MessageReaction

Objet PagedMembersResult

Objet Place

Objet ReceiptCard

Objet ReceiptItem

Objet ResourceResponse

Objet SemanticAction

Objet SignInCard

Objet SuggestedActions

Objet TextHighlight

Objet ThumbnailCard

Objet ThumbnailUrl

Objet Transcript

Objet VideoCard

Ressources supplémentaires

Propriété	Type	Description
entities	Object	Objet où la valeur de chaque propriété est un objet Entity.
id	Chaîne	ID de cette action.
state	Chaîne	État de cette action. Valeurs autorisées : start, continue, done.

Propriété	Type	Description
actions	CardAction[]	Tableau d’objets CardAction qui définissent les actions suggérées.
to	String[]	Tableau de chaînes qui contient les ID des destinataires pour lesquels les actions suggérées doivent être affichées.

Propriété	Type	Description
occurrence	Number	Occurrence du champ de texte dans le texte référencé, s’il en existe plusieurs.
texte	Chaîne	Définit l’extrait de texte à mettre en surbrillance.

Propriété	Type	Description
aspect	Chaîne	Proportions de la vidéo. 16:9 ou 4:3.
autoloop	Boolean	Indicateur qui indique s’il faut relire la liste des vidéos lorsque la dernière est terminée. Définissez cette propriété sur true pour relire automatiquement les vidéos ; sinon, définissez-la sur false. La valeur par défaut est true.
autostart	Boolean	Indicateur qui indique s’il faut lire automatiquement les vidéos lorsque la carte s’affiche. Définissez cette propriété sur true pour lire automatiquement les vidéos ; sinon, définissez-la sur false. La valeur par défaut est true.
buttons	CardAction[]	Tableau d’objets CardAction qui permettent à l’utilisateur d’effectuer une ou plusieurs actions. Le canal détermine le nombre de boutons que vous pouvez spécifier.
duration	Chaîne	La longueur du contenu du média, au format de durée ISO 8601.
image	ThumbnailUrl	Objet ThumbnailUrl qui spécifie l’image à afficher sur la carte.
media	MediaUrl[]	Tableau d’objets MediaUrl. Quand ce champ contient plusieurs URL, chaque URL est un autre format du même contenu.
shareable	Boolean	Indicateur qui indique si les vidéos peuvent être partagées avec d’autres utilisateurs. Définissez cette propriété sur true si les vidéos peuvent être partagées ; sinon, sur false. La valeur par défaut est true.
subtitle	Chaîne	Sous-titre à afficher sous le titre de la carte.
texte	Chaîne	Description ou invitation à afficher sous le titre ou le sous-titre de la carte.
title	Chaîne	Titre de la carte.
value	Object	Paramètre supplémentaire de cette carte