Informations de référence sur l’API - DIRECT LINE API 3.0

Vous pouvez permettre à votre application cliente de communiquer avec votre bot à l’aide de Direct Line API 3.0. Direct Line API 3.0 utilise rest et JSON standard sur HTTPS.

Base de l'URI

Pour accéder à Direct Line API 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	Base de l'URI
  Europe	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

En-têtes

En plus des en-têtes de requête HTTP standard, une demande d’API Direct Line doit inclure un Authorization en-tête qui spécifie un secret ou un jeton pour authentifier le client qui émet 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 demandes d’API Direct Line, consultez Authentification.

Codes d’état HTTP

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

Errors

Toute réponse qui spécifie un code d’état HTTP dans la plage 4xx ou 5xx inclut 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, inspectez l’objet ErrorResponse pour identifier la cause de l’erreur et résoudre votre problème avant de renvoyer la requête.

Les extraits de code suivants montrent un exemple de requête et la réponse d’erreur résultante.

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 ces opérations pour créer ou actualiser un jeton qu’un client peut utiliser pour accéder à une seule conversation.

Générer un jeton

Génère un jeton valide pour une conversation.

POST /v3/directline/tokens/generate

Actualiser le jeton

Actualise le jeton.

POST /v3/directline/tokens/refresh

Opérations de conversation

Utilisez ces opérations pour ouvrir une conversation avec votre bot et échanger des activités entre le client et le bot.

Lancer la conversation

Ouvre une nouvelle conversation avec le bot.

POST /v3/directline/conversations

Obtenir des informations sur la conversation

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

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

Obtenir des activités

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

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

Envoyer une activité

Envoie une activité au bot.

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

Charger et envoyer des fichiers

Charge et envoie des fichiers en tant que pièces jointes. Définissez le userId paramètre dans l’URI de requête pour spécifier l’ID de l’utilisateur qui envoie la ou les pièces jointes.

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

Schema

Le schéma Direct Line 3.0 inclut tous les objets définis par le schéma Bot Framework, ainsi que certains objets 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 de 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èce jointe sont conservées.
• Les URL pour les pièces jointes chargées sont masquées avec une liaison privée.
• La channelData propriété est conservée sans modification.

Les clients peuvent recevoir plusieurs activités du bot dans le cadre d’un ActivitySet.

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

• La type propriété spécifie l’activité de type qu’elle envoie (généralement le message).
• La from propriété doit être remplie avec un ID d’utilisateur, choisi par le client.
• Les pièces jointes peuvent contenir des URL vers des ressources existantes ou des URL chargées via le point de terminaison de pièce jointe Direct Line.
• La channelData propriété est conservée sans modification.
• La taille totale de l’activité, lorsqu’elle est sérialisée au format 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.

Les clients peuvent envoyer une activité unique par requête.

Ressources additionnelles

• Spécification du protocole d’activité