Envoyer une activité au bot dans l’API de ligne directe 3,0Send an activity to the bot in Direct Line API 3.0

  • 4 minutes de lecture

Le protocole Direct Line 3.0 permet aux clients et aux robots d’échanger différents types d’activités, notamment des activités de messagerie et de saisie, ainsi que des activités personnalisées prises en charge par le robot.Using the Direct Line 3.0 protocol, clients and bots may exchange several different types of activities, including message activities, typing activities, and custom activities that the bot supports. Un client ne peut envoyer qu’une seule activité par requête.A client may send a single activity per request.

Envoyer une activitéSend an activity

Pour envoyer une activité au robot, le client doit créer un objet Activité pour définir l’activité, puis envoyer une requête POST à https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities en précisant l’objet de l’activité dans le corps de la requête.To send an activity to the bot, the client must create an Activity object to define the activity and then issue a POST request to https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, specifying the Activity object in the body of the request.

Les extraits de code suivants montrent la requête et la réponse de l’activité d’envoi.The following snippets provide an example of the Send Activity request and response.

RequêteRequest

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]

{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hello"
}

responseResponse

Lorsque l’activité est fournie au robot, le service répond avec un code d’état HTTP qui correspond au code d’état du robot.When the activity is delivered to the bot, the service responds with an HTTP status code that reflects the bot's status code. Si le robot génère une erreur, une réponse HTTP 502 (« passerelle incorrecte ») est renvoyée au client en réponse à sa requête d’activité d’envoi.If the bot generates an error, an HTTP 502 response ("Bad Gateway") is returned to the client in response to its Send Activity request.

Notes

Cela peut être dû au fait qu’un jeton correct n’a pas été utilisé.This can be caused by the fact that a correct token was not used. Seul le jeton reçu pour démarrer la conversation peut être utilisé pour envoyer une activité.Only the token which was received against start conversation can be used to send an activity.

Si la PUBLICATION est réussie, la réponse contient une charge utile JSON qui spécifie l’identifiant de I’activité envoyée au robot.If the POST is successful, the response contains a JSON payload that specifies the ID of the Activity that was sent to the bot.

HTTP/1.1 200 OK
[other headers]

{
    "id": "0001"
}

Durée totale de requête/réponse de l’activité d’envoiTotal time for the Send Activity request/response

La durée totale de PUBLICATION d’un message à une conversation Direct Line est égale à la somme des éléments suivants :The total time to POST a message to a Direct Line conversation is the sum of the following:

  • Délai de transmission de la requête HTTP du client au service Direct LineTransit time for the HTTP request to travel from the client to the Direct Line service
  • Temps de traitement interne dans Direct Line (généralement inférieur à 120 ms)Internal processing time within Direct Line (typically less than 120ms)
  • Délai de transmission entre le service Direct Line et le robotTransit time from the Direct Line service to the bot
  • Temps de traitement au sein du robotProcessing time within the bot
  • Délai de transmission de la réponse HTTP au clientTransit time for the HTTP response to travel back to the client

Envoyer des pièces jointes au robotSend attachment(s) to the bot

Dans certains cas, un client peut avoir besoin d’envoyer des pièces jointes au robot, par exemple des images ou des documents.In some situations, a client may need to send attachments to the bot such as images or documents. Un client peut envoyer des pièces jointes au robot en indiquant la ou les URL de la ou des pièces jointes dans l’objet Activité envoyé à l’aide de POST /v3/directline/conversations/{conversationId}/activities ou en téléchargeant la ou les pièces jointes à l’aide de POST /v3/directline/conversations/{conversationId}/upload.A client may send attachments to the bot either by specifying the URL(s) of the attachment(s) within the Activity object that it sends using POST /v3/directline/conversations/{conversationId}/activities or by uploading attachment(s) using POST /v3/directline/conversations/{conversationId}/upload.

Envoyer des pièces jointes par URLSend attachment(s) by URL

Pour envoyer une ou plusieurs pièces jointes faisant partie de l’objet Activité à l’aide de POST /v3/directline/conversations/{conversationId}/activities, il suffit d’inclure un ou plusieurs objets Attachment dans l’objet Activité et de définir la propriété contentUrl de chaque objet Pièce jointe pour spécifier l’URI HTTP, HTTPS ou data. URI de la pièce jointe.To send one or more attachments as part of the Activity object using POST /v3/directline/conversations/{conversationId}/activities, simply include one or more Attachment objects within the Activity object and set the contentUrl property of each Attachment object to specify the HTTP, HTTPS, or data URI of the attachment.

Envoyer des pièces jointes par chargementSend attachment(s) by upload

Il arrive souvent qu’un client ait des images ou des documents sur un périphérique qu’il veut envoyer au bot, mais ne dispose pas des URL correspondant aux fichiers.Often, a client may have image(s) or document(s) on a device that it wants to send to the bot, but no URLs corresponding to those files. Dans cette situation, un client peut lancer une requête POST /v3/directline/conversations/{conversationId}/upload afin d’envoyer des pièces jointes au robot par téléchargement.In this situation, a client can can issue a POST /v3/directline/conversations/{conversationId}/upload request to send attachments to the bot by upload. Le format et le contenu de la demande varient selon que le client envoie une pièce jointe unique ou envoie plusieurs pièces jointes.The format and contents of the request will depend upon whether the client is sending a single attachment or sending multiple attachments.

Envoyer une seule pièce jointe par téléchargementSend a single attachment by upload

Pour envoyer une seule pièce jointe par chargement, exécutez la demande suivante :To send a single attachment by upload, issue this request:

POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]

[file content]

Dans cette requête URI, remplacez {conversationId} par l’identifiant de la conversation et {userId} par l’identifiant de l’utilisateur qui envoie le message.In this request URI, replace {conversationId} with the ID of the conversation and {userId} with the ID of the user that is sending the message. Le paramètre userId est obligatoire.The userId parameter is required. Dans les en-têtes de demande, définissez Content-Type pour spécifier le type de la pièce jointe, et définissez Content-Disposition pour spécifier le nom de fichier de la pièce jointe.In the request headers, set Content-Type to specify the attachment's type and set Content-Disposition to specify the attachment's filename.

Les extraits de code suivants montrent la requête et la réponse de l’envoi d’une seule pièce jointe.The following snippets provide an example of the Send (single) Attachment request and response.

RequêteRequest

POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]

[JPEG content]

responseResponse

Si la requête est acceptée, un message d’activité est envoyé au robot à la fin du téléchargement et la réponse reçue par le client contient l’identifiant de l’activité envoyée.If the request is successful, a message Activity is sent to the bot when the upload completes and the response that the client receives will contain the ID of the Activity that was sent.

HTTP/1.1 200 OK
[other headers]

{
  "id": "0003"
}

Envoyer plusieurs pièces jointes par chargementSend multiple attachments by upload

Pour envoyer plusieurs pièces jointes par chargement, publiez (POST) une demande en plusieurs parties sur le point de terminaison /v3/directline/conversations/{conversationId}/upload.To send multiple attachments by upload, POST a multipart request to the /v3/directline/conversations/{conversationId}/upload endpoint. Définissez l’en-tête Content-Type de la requête sur multipart/form-data et insérez les en-têtes Content-Type et Content-Disposition à chaque partie pour indiquer le type et le nom de fichier de chaque pièce jointe.Set the Content-Type header of the request to multipart/form-data and include the Content-Type header and Content-Disposition header for each part to specify each attachment's type and filename. Dans la requête URI, définissez le paramètre userId à l’identifiant de l’utilisateur qui envoie le message.In the request URI, set the userId parameter to the ID of the user that is sending the message.

Vous pouvez inclure un objet Activity dans la requête en ajoutant une partie qui indique la valeur application/vnd.microsoft.activity de l’en-tête Content-Type.You may include an Activity object within the request by adding a part that specifies the Content-Type header value application/vnd.microsoft.activity. Si la requête comprend une activité, les pièces jointes indiquées par d’autres parties de la charge utile sont ajoutées comme pièces jointes à cette activité avant qu’elle ne soit envoyée.If the request includes an Activity, the attachments that are specified by other parts of the payload are added as attachments to that Activity before it is sent. Si la requête n’inclut pas d’activité, une activité vide est créée pour servir de conteneur dans lequel les pièces jointes indiquées sont envoyées.If the request does not include an Activity, an empty Activity is created to serve as the container in which the specified attachments are sent.

Les extraits de code suivants montrent la requête et la réponse de l’envoi de plusieurs pièces jointes.The following snippets provide an example of the Send (multiple) Attachments request and response. Dans cet exemple, la demande envoie un message contenant du texte et une image unique en pièce jointe.In this example, the request sends a message that contains some text and a single image attachment. La requête peut comporter des parties supplémentaires afin d’inclure plusieurs pièces jointes dans le message.Additional parts could be added to the request to include multiple attachments in this message.

RequêteRequest

POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]

----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]

[JPEG content]

----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]

{
  "type": "message",
  "from": {
    "id": "user1"
  },
  "text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}

----DD4E5147-E865-4652-B662-F223701A8A89

responseResponse

Si la requête est acceptée, un message d’activité est envoyé au robot à la fin du téléchargement et la réponse reçue par le client contient l’identifiant de l’activité envoyée.If the request is successful, a message Activity is sent to the bot when the upload completes and the response that the client receives will contain the ID of the Activity that was sent.

HTTP/1.1 200 OK
[other headers]

{
    "id": "0004"
}

Ressources supplémentairesAdditional resources