Informations de référence sur l’API - API Direct Line 1.1

Article
03/08/2023

Important

Cet article contient les informations de référence relatives à l’API Direct Line 1.1. Si vous créez une connexion entre votre application cliente et le bot, utilisez Direct Line’API 3.0 à la place.

Vous pouvez activer la communication de votre application cliente avec votre bot à l’aide de l’API Direct Line 1.1. L’API Direct Line 1.1 utilise les standards REST et JSON sur HTTPS.

URI de base

Pour accéder à l’API Direct Line 1.1, utilisez l’URI de base ci-après pour toutes les requêtes d’API :

https://directline.botframework.com

headers

Outre les en-têtes de requête HTTP standard, une requête d’API Direct Line doit inclure un en-tête Authorization qui spécifie un secret ou un jeton pour authentifier le client émettant la requête. Vous pouvez spécifier l’en-tête Authorization à l’aide du schéma « Bearer » ou « BotConnector ».

Schéma Bearer :

Authorization: Bearer SECRET_OR_TOKEN

Schéma BotConnector :

Authorization: BotConnector SECRET_OR_TOKEN

Pour plus d’informations sur l’obtention d’un secret ou d’un jeton que votre client peut utiliser pour authentifier ses requêtes d’API Direct Line, consultez l’article Authentification.

Codes d’état HTTP

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

Code d'état HTTP	Signification
200	La requête a réussi.
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 client n’est pas autorisé à effectuer la demande. Dans la plupart des cas, ce code d’état signale que l’en-tête `Authorization` est manquant ou qu’il présente un format incorrect.
403	Le client n’est pas autorisé à effectuer l’opération demandée. Dans la plupart des cas, ce code d’état signale que l’en-tête `Authorization` spécifie un jeton ou un secret non valides.
404	La ressource demandée est introuvable. Ce code d’état signale généralement un URI de requête non valide.
500	Une erreur de serveur interne s’est produite dans le service Direct Line.
502	Une défaillance s’est produite dans le bot ; le bot n’est pas disponible ou a renvoyé une erreur. Ce code d’erreur est courant.

Opérations de jeton

Utilisez les opérations ci-après pour créer ou actualiser un jeton permettant à un client d’accéder à une conversation spécifique.

Opération	Description
Générer un jeton	Permet de générer un jeton pour une nouvelle conversation.
Actualiser le jeton	Permet d’actualiser un jeton.

Générer un jeton

Permet de générer un jeton valide pour une seule conversation.

POST /api/tokens/conversation

Contenu	Description
Corps de la demande	n/a
Retourne	Chaîne représentant le jeton

Actualiser le jeton

Permet d’actualiser le jeton.

GET /api/tokens/{conversationId}/renew

Contenu	Description
Corps de la demande	n/a
Retourne	Chaîne représentant le nouveau jeton

Opérations de conversation

Utilisez les opérations ci-après pour ouvrir une conversation avec votre bot et pour échanger des messages entre le client et le bot.

Opération	Description
Start Conversation (Démarrer une conversation)	Ouvre une nouvelle conversation avec le bot.
Get Messages	Récupère les messages émanant du bot.
Envoyer un message	Envoie un message au bot.
Upload and Send File(s) (Charger et envoyer des fichiers)	Charge et envoie un ou plusieurs fichiers sous forme de pièces jointes.

Start Conversation (Démarrer une conversation)

Ouvre une nouvelle conversation avec le bot.

POST /api/conversations

Contenu	Description
Corps de la demande	n/a
Retourne	Objet Conversation

Obtenir les messages

Récupère les messages émanant du bot pour la conversation spécifiée. Définissez le paramètre watermark dans l’URI de requête pour indiquer le dernier message vu par le client.

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}

Contenu	Description
Corps de la demande	n/a
Retourne	Objet MessageSet. La réponse contient `watermark` en tant que propriété de l’objet `MessageSet`. Les clients doivent parcourir les messages disponibles en augmentant la valeur `watermark` jusqu’à ce qu’aucun message ne soit plus renvoyé.

Envoyer un message

Envoie un message au bot.

POST /api/conversations/{conversationId}/messages

Contenu	Description
Corps de la demande	Objet Message
Retourne	Aucune donnée n’est retournée dans le corps de la réponse. Le service répond par un code d’état HTTP 204 si le message a été envoyé avec succès. Le client peut obtenir le message qu’il a envoyé (ainsi que tous les messages qu’il a reçus du bot) en utilisant l’opération Obtenir les messages.

Charger et envoyer des fichiers

Charge et envoie un ou plusieurs fichiers sous forme de pièces jointes. Définissez le paramètre userId dans l’URI de requête pour spécifier l’ID de l’utilisateur envoyant les pièces jointes.

POST /api/conversations/{conversationId}/upload?userId={userId}

Contenu	Description
Corps de la demande	Dans le cas d’une pièce jointe unique, remplissez le corps de la requête avec le contenu du fichier. Dans le cas de plusieurs pièces jointes, créez un corps de requête en plusieurs parties, contenant une partie pour chaque pièce jointe, et également (en option) une partie pour l’objet Message qui doit servir de conteneur pour les pièces jointes spécifiées. Pour plus d’informations, consultez Envoyer un message au bot.
Retourne	Aucune donnée n’est retournée dans le corps de la réponse. Le service répond par un code d’état HTTP 204 si le message a été envoyé avec succès. Le client peut obtenir le message qu’il a envoyé (ainsi que tous les messages qu’il a reçus du bot) en utilisant l’opération Obtenir les messages.

Contenu

Description

Corps de la demande

Dans le cas d’une pièce jointe unique, remplissez le corps de la requête avec le contenu du fichier. Dans le cas de plusieurs pièces jointes, créez un corps de requête en plusieurs parties, contenant une partie pour chaque pièce jointe, et également (en option) une partie pour l’objet Message qui doit servir de conteneur pour les pièces jointes spécifiées. Pour plus d’informations, consultez Envoyer un message au bot.

Retourne

Aucune donnée n’est retournée dans le corps de la réponse. Le service répond par un code d’état HTTP 204 si le message a été envoyé avec succès. Le client peut obtenir le message qu’il a envoyé (ainsi que tous les messages qu’il a reçus du bot) en utilisant l’opération Obtenir les messages.

Notes

Les fichiers chargés sont supprimés au bout de 24 heures.

schéma

Le schéma Direct Line 1.1 est une copie simplifiée du schéma Bot Framework v1 incluant les objets suivants.

Objet Message

Définit un message qu’un client envoie à un bot ou reçoit d’un bot.

Propriété	Type	Description
id	string	ID identifiant de manière unique le message (attribué par Direct Line).
conversationId	string	ID identifiant la conversation.
created	string	Date et heure de création du message, exprimées au format ISO-8601).
from	string	ID identifiant l’utilisateur qui a expédié le message. Lorsque vous créez un message, les clients doivent définir cette propriété sur un ID d’utilisateur stable. Bien que Direct Line attribue un ID d’utilisateur si aucun n’est fourni, cette opération entraîne généralement un comportement inattendu.
text	string	Texte du message envoyé par l’utilisateur au bot ou par le bot à l’utilisateur.
channelData	object	Objet contenant le contenu propre au canal. Certains canaux fournissent des fonctionnalités qui nécessitent des informations supplémentaires qui ne peuvent pas être représentées à 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. Ces données sont envoyées telles quelles entre le client et le bot. Cette propriété doit être définie sur un objet complexe ou laissée vide. Ne la définissez pas sur une chaîne, un nombre ou un autre type simple.
images	string[]	Tableau de chaînes contenant l’URL des images figurant dans le message. Dans certains cas, les chaînes de ce tableau peuvent être des URL relatives. Si une chaîne de ce tableau ne commence pas par « http » ou « https », `https://directline.botframework.com` ajoutez la chaîne pour former l’URL complète.
attachments	Attachment[]	Tableau d’objets Attachment représentant les pièces jointes autres que des images qui figurent dans le message. Chaque objet du tableau contient une propriété `url` et une propriété `contentType`. Dans les messages qu’un client reçoit d’un bot, la propriété `url` peut parfois spécifier une URL relative. Pour toute `url` valeur de propriété qui ne commence pas par « http » ou « https », ajoutez `https://directline.botframework.com` la chaîne pour former l’URL complète.

L’exemple ci-après présente un objet Message contenant toutes les propriétés possibles. Dans la plupart des cas, lors de la création d’un message, le client doit uniquement fournir la from propriété et au moins une propriété de contenu (telle que text, images, attachmentsou channelData).

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

Objet MessageSet

Définit un ensemble de messages.

Propriété	Type	Description
messages	Message[]	Tableau d’objets Message.
watermark	string	Filigrane maximal des messages au sein de l’ensemble. Un client peut utiliser la valeur `watermark` pour indiquer le dernier message qu’il a vu lors de la récupération des messages émanant du bot.

Objet Attachment

Définit une pièce jointe autre qu’une image.

Propriété	Type	Description
contentType	string	Type de média du contenu de la pièce jointe.
url	string	URL du contenu de la pièce jointe.

Objet Conversation

Définit une conversation Direct Line.

Propriété	Type	Description
conversationId	string	ID identifiant de manière unique la conversation pour laquelle le jeton spécifié est valide.
token	string	Jeton valide pour la conversation spécifiée.
expires_in	nombre	Nombre de secondes avant l’expiration du jeton.

Objet d’erreur

Définit une erreur.

Propriété	Type	Description
code	string	Code d’erreur. Une des valeurs suivantes : MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
message	string	Description de l’erreur.
statusCode	nombre	Code d’état.

Objet ErrorMessage

Charge utile d’erreur de message normalisée.

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

Partager via