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

  • Article

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é.

Retour au tableau Schéma

Objet AnimationCard

Définit une carte pouvant lire des images GIF animées ou de courtes vidéos.

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.

Retour au tableau Schéma

Objet Attachment

Définit des informations supplémentaires à inclure dans le message. Une pièce jointe peut être un fichier (image, audio ou vidéo) ou une carte enrichie.

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.

Retour au tableau Schéma

Objet AttachmentData

Décrit les données d’une pièce jointe.

Propriété Type Description
name Chaîne Nom de la pièce jointe.
originalBase64 Chaîne Contenu de la pièce jointe.
thumbnailBase64 Chaîne Contenu de la miniature de la pièce jointe.
type Chaîne Type de contenu de la pièce jointe.

Retour au tableau Schéma

Objet AttachmentInfo

Métadonnées d’une pièce jointe.

Propriété Type Description
name Chaîne Nom de la pièce jointe.
type Chaîne Type de contenu de la pièce jointe.
vues AttachmentView[] Tableau d’objets AttachmentView qui représentent les affichages disponibles pour la pièce jointe.

Retour au tableau Schéma

Objet AttachmentView

Définit un objet qui représente une vue disponible pour une pièce jointe.

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

Retour au tableau Schéma

Objet AudioCard

Définit une carte qui peut lire un fichier audio.

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.

Retour au tableau Schéma

Objet CardAction

Définit une action cliquable avec un bouton.

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.

Retour au tableau Schéma

Objet CardImage

Définit l’image à afficher sur une carte.

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...).

Retour au tableau Schéma

Objet ChannelAccount

Définit le bot ou le compte d’utilisateur sur le canal.

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.

Retour au tableau Schéma

Objet ConversationAccount

Définit une conversation sur un canal.

Propriété Type Description
aadObjectId Chaîne L'ID d'objet de ce compte dans Microsoft Entra ID.
conversationType Chaîne Indique le type de conversation dans les canaux qui distinguent les types de conversation (par exemple, groupe ou personnel).
id Chaîne ID qui identifie la conversation. L’ID est unique sur chaque canal. Si le canal lance la conversion, il définit cet ID ; sinon, le bot définit cette propriété sur l’ID qu’il reçoit dans la réponse quand il démarre la conversation (voir Créer une conversation).
isGroup Boolean Indicateur qui indique si la conversation contient plus de deux participants au moment où l’activité est générée. Définissez la valeur true s’il s’agit d’une conversation de groupe ; sinon, false. La valeur par défaut est false.
name Chaîne Nom convivial qui peut être utilisé pour identifier la conversation.
role Chaîne Rôle de l’entité derrière le compte. user ou bot.
tenantId Chaîne ID de locataire de cette conversation.

Retour au tableau Schéma

Objet ConversationMembers

Définit les membres d’une conversation.

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

Retour au tableau Schéma

Objet ConversationParameters

Définit des paramètres pour la création d’une 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.

Retour au tableau Schéma

Objet ConversationReference

Définit un endroit particulier d’une conversation.

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.

Retour au tableau Schéma

Objet ConversationResourceResponse

Définit une réponse à Créer une conversation.

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.

Retour au tableau Schéma

Objet ConversationsResult

Définit le résultat de Obtenir des conversations.

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.

Retour au tableau Schéma

Objet Entity

Objet de métadonnées appartenant à une activité.

Propriété Type Description
type Chaîne Type de cette entité (IRI RFC 3987).

Retour au tableau Schéma

Objet Error

Objet représentant les informations d’erreur.

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.

Retour au tableau Schéma

Objet ErrorResponse

Définit une réponse d’API HTTP.

Propriété Type Description
error Error Objet Error contenant des informations concernant l’erreur.

Retour au tableau Schéma

Objet Fact

Définit une paire clé-valeur contenant un fait.

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.

Retour au tableau Schéma

Objet GeoCoordinates

Définit un emplacement géographique à l’aide des coordonnées World Geodetic System (WSG84).

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.

Retour au tableau Schéma

Objet HeroCard

Définit une carte avec une grande image, un titre, du texte et des boutons d’action.

Propriété Type Description
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.
images CardImage[] Tableau d’objets CardImage qui spécifie l’image à afficher sur la carte. Une carte Héros contient une seule image.
subtitle Chaîne Sous-titre à afficher sous le titre de la carte.
tap CardAction Objet CardAction qui spécifie l’action à effectuer si l’utilisateur appuie ou clique sur la carte. Il peut s’agir de la même action que celle d’un bouton, ou d’une action différente.
texte Chaîne Description ou invitation à afficher sous le titre ou le sous-titre de la carte.
title Chaîne Titre de la carte.

Retour au tableau Schéma

Objet InnerHttpError

Objet représentant une erreur HTTP interne.

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.

Retour au tableau Schéma

Objet MediaEventValue

Paramètre supplémentaire des événements multimédias.

Propriété Type Description
cardValue Object Paramètre de rappel spécifié dans le champ valeur de la carte multimédia qui a déclenché cet événement.

Retour au tableau Schéma

Objet MediaUrl

Définit l’URL de la source d’un fichier multimédia.

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.

Retour au tableau Schéma

Objet Mention

Définit un utilisateur ou un bot mentionné dans la conversation.

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.

Retour au tableau Schéma

Objet MessageReaction

Définit une réaction à un message.

Propriété Type Description
type Chaîne Type de réaction. like ou plusOne.

Retour au tableau Schéma

Objet PagedMembersResult

Page de membres retournée par Obtenir les membres paginés de la conversation.

Propriété Type Description
continuationToken Chaîne Jeton de continuation qui peut être utilisé dans les appels postérieurs à Obtenir les membres paginés de la conversation.
members ChannelAccount[] Tableau des membres de la conversation.

Retour au tableau Schéma

Objet Place

Définit un lieu mentionné dans la conversation.

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.

Retour au tableau Schéma

Objet ReceiptCard

Définit une carte qui contient un reçu pour un achat.

Propriété Type Description
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.
facts Fact[] Tableau d’objets Fact qui spécifient des informations sur l’achat. Par exemple, la liste de faits du reçu d’un séjour à l’hôtel peut inclure les dates d’arrivée et de départ. Le canal détermine le nombre de faits que vous pouvez spécifier.
items ReceiptItem[] Tableau d’objets ReceiptItem qui spécifient les articles achetés
tap CardAction Objet CardAction qui spécifie l’action à effectuer si l’utilisateur appuie ou clique sur la carte. Il peut s’agir de la même action que celle d’un bouton, ou d’une action différente.
tax Chaîne Chaîne au format devise qui spécifie la somme de la taxe appliquée à l’achat.
title Chaîne Titre affiché en haut du reçu.
total Chaîne Chaîne au format devise qui spécifie le prix total d’un achat, y compris toutes les taxes applicables.
vat Chaîne Chaîne au format devise qui spécifie la somme de la TVA appliquée au prix de l’achat.

Retour au tableau Schéma

Objet ReceiptItem

Définit une ligne dans un reçu.

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.

Retour au tableau Schéma

Objet ResourceResponse

Définit une réponse qui contient un ID de ressource.

Propriété Type Description
id Chaîne ID qui identifie de façon unique la ressource.

Retour au tableau Schéma

Objet SemanticAction

Définit une référence à une action de programmation.

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.

Retour au tableau Schéma

Objet SignInCard

Définit une carte qui permet à un utilisateur de se connecter à un service.

Propriété Type Description
buttons CardAction[] Tableau d’objets CardAction qui permettent à l’utilisateur de se connecter à un service. Le canal détermine le nombre de boutons que vous pouvez spécifier.
texte Chaîne Description ou invitation à inclure dans la carte de connexion.

Retour au tableau Schéma

Objet SuggestedActions

Définit les options qu’un utilisateur peut choisir.

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.

Retour au tableau Schéma

Objet TextHighlight

Référence une sous-chaîne de contenu dans un autre champ.

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.

Retour au tableau Schéma

Objet ThumbnailCard

Définit une carte avec une miniature, un titre, du texte et des boutons d’action.

Propriété Type Description
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.
images CardImage[] Tableau d’objets CardImage qui spécifie les images miniatures à afficher sur la carte. Le canal détermine le nombre d’images miniatures que vous pouvez spécifier.
subtitle Chaîne Sous-titre à afficher sous le titre de la carte.
tap CardAction Objet CardAction qui spécifie l’action à effectuer si l’utilisateur appuie ou clique sur la carte. Il peut s’agir de la même action que celle d’un bouton, ou d’une action différente.
texte Chaîne Description ou invitation à afficher sous le titre ou le sous-titre de la carte.
title Chaîne Titre de la carte.

Retour au tableau Schéma

Objet ThumbnailUrl

Définit l’URL de la source d’une image.

Propriété Type Description
alt Chaîne Description de l’image. Vous devez inclure la description pour des raisons d’accessibilité.
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...).

Retour au tableau Schéma

Objet Transcript

Collection d’activités à charger à l’aide de Envoyer l’historique des conversations.

Propriété Type Description
activités tableau Tableau d’objets Activity. Ils doivent posséder chacun un ID unique et un horodatage.

Retour au tableau Schéma

Objet VideoCard

Définit une carte pouvant lire des vidéos.

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

Retour au tableau Schéma