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

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

L'URI de base

Pour accéder à l’API Direct Line 3.0, utilisez l’une de ces URI de base pour toutes les demandes d’API :

• Pour les bots globaux, utilisez https://directline.botframework.com

• Pour un bot régional, entrez l’URI suivant en fonction de la région sélectionnée :

  Région	L'URI de base
  Europe	https://europe.directline.botframework.com
  Inde	https://india.directline.botframework.com

En-têtes

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. Spécifiez l’en-tête Authorization au format suivant :

Authorization: Bearer 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.

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.

Les extraits suivants montrent un exemple de requête et la réponse d’erreur qui en résulte.

Requête

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

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.

Générer un jeton

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

POST /v3/directline/tokens/generate

Jeton d‘actualisation

Permet d’actualiser le jeton.

POST /v3/directline/tokens/refresh

Opérations de conversation

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

Start Conversation (Démarrer une conversation)

Ouvre une nouvelle conversation avec le bot.

POST /v3/directline/conversations

Obtenir des informations de Conversation

Cette opération obtient des informations sur une conversation existante et génère également une nouvelle URL de flux de données WebSocket qu’un client peut utiliser pour se reconnecter à une conversation. Vous pouvez éventuellement fournir le paramètre watermark dans l’URI de requête pour indiquer le dernier message vu par le client.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Obtenir des activités

Récupère des activités provenant du bot pour la conversation spécifiée. Vous pouvez éventuellement fournir le paramètre watermark dans l’URI de requête pour indiquer le dernier message vu par le client.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Envoyer une activité

Envoyer une activité au bot.

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

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 la ou les pièces jointes.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

schéma

Le schéma Direct Line 3.0 inclut tous les objets définis par le schéma Bot Framework ainsi que des objets qui sont spécifiques à Direct Line.

Objet ActivitySet

Définit un ensemble d’activités.

Objet Conversation

Définit une conversation Direct Line.

Objet TokenParameters

Paramètres pour la création d’un jeton.

Activités

Pour chaque Activité qu’un client reçoit d’un bot via Direct Line :

• Les cartes de pièces jointes sont conservées.
• Les URL pour les pièces jointes chargées sont masquées avec un lien privé.
• La propriété channelData est conservée sans modification.

Les clients peuvent recevoir plusieurs activités à partir du bot en tant que partie d’un ActivitySet.

Lorsqu’un client envoie une Activity à un bot via Direct Line :

• La type propriété spécifie l’activité de type qu’elle envoie (généralement le message).
• La propriété from doit être remplie avec un ID d’utilisateur choisi par le client.
• Les pièces jointes peuvent contenir des URL de ressources existantes, ou des URL chargés via le point de terminaison de pièce jointe de Direct Line.
• La propriété channelData est conservée sans modification.
• La taille totale de l’activité, quand elle est sérialisée dans JSON et chiffrée, ne doit pas dépasser 256 000 caractères. Nous vous recommandons de conserver les activités de moins de 150 000 ko. Si d’autres données sont nécessaires, envisagez de fractionner l’activité ou d’utiliser des pièces jointes.

Un client peut envoyer une seule activité par requête.

Ressources supplémentaires

• Spécification des activités Bot Framework