Envío de una actividad al bot en Direct Line API 3.0
Mediante el protocolo Direct Line 3.0, los clientes y los bots pueden intercambiar varios tipos diferentes de actividades, incluidas las actividades de mensaje, las de escritura y las actividades personalizadas que admita el bot. Un cliente puede enviar una sola actividad por solicitud.
Envío de una actividad
Para enviar una actividad al bot, el cliente debe crear un objeto Actividad para definir la actividad y, a continuación, emitir una solicitud POST a https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, especificando el objeto Activity en el cuerpo de la solicitud.
Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud de envío de la actividad y la respuesta.
Solicitud
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"
}
Response
Cuando se entrega la actividad al bot, el servicio responde con un código de estado HTTP que refleja el código de estado del bot. Si el bot genera un error, se devuelve una respuesta HTTP 502 ("Puerta de enlace incorrecta") al cliente en respuesta a su solicitud de envío de actividad.
Nota
Esto puede deberse al hecho de que no se usó un token correcto. Para enviar una actividad solo se puede usar el token que se recibió al iniciar la conversación.
Si la solicitud POST se realiza correctamente, la respuesta contiene una carga JSON que especifica el identificador de la actividad que se envió al bot.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Tiempo total para la solicitud y respuesta del envío de la actividad
El tiempo total para el envío POST de un mensaje en una conversación de Direct Line es la suma de lo siguiente:
- Tiempo de tránsito de la solicitud HTTP para desplazarse desde el cliente al servicio Direct Line
- Tiempo de procesamiento interno en Direct Line (normalmente menos de 120 ms)
- Tiempo de tránsito desde el servicio Direct Line al bot
- Tiempo de procesamiento en el bot
- Tiempo de tránsito de la respuesta HTTP hasta el cliente
Envío de datos adjuntos al bot
En algunas situaciones, un cliente debe enviar datos adjuntos al bot, como imágenes o documentos. Un cliente puede enviar datos adjuntos al bot ya sea especificando las direcciones URL de los datos adjuntos en el objeto Actividad que envía mediante POST /v3/directline/conversations/{conversationId}/activities o cargando los datos adjuntos mediante POST /v3/directline/conversations/{conversationId}/upload.
Envío de datos adjuntos por dirección URL
Para enviar uno o varios archivos adjuntos como parte del objeto Actividad mediante POST /v3/directline/conversations/{conversationId}/activities, basta con incluir uno o varios objetos Datos adjuntos dentro del objeto Activity y establecer la propiedad contentUrl de cada objeto Attachment para especificar la dirección HTTP o HTTPS o el identificador URI data de los datos adjuntos.
Envío de datos adjuntos mediante carga
A menudo, un cliente puede tener imágenes o documentos en un dispositivo que desea enviar al bot, pero no hay direcciones URL correspondientes a esos archivos. En esta situación, un cliente puede emitir una solicitud POST /v3/directline/conversations/{conversationId}/upload para enviar datos adjuntos al bot mediante carga. El formato y el contenido de la solicitud dependerán de si el cliente envía un único dato adjunto o envía varios datos adjuntos.
Envío de un único dato adjunto mediante carga
Para enviar un único dato adjunto mediante carga, emita esta solicitud:
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]
En este identificador URI de solicitud, reemplace {conversationId} por el identificador de la conversación y {userId} por el identificador del usuario que envía el mensaje. El parámetro userId es obligatorio. En los encabezados de solicitud, establezca Content-Type para especificar el tipo de datos adjuntos y establezca Content-Disposition para especificar el nombre de archivo de los datos adjuntos.
Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud de envío de un único dato adjunto y la respuesta.
Solicitud
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]
Response
Si la solicitud es correcta, se envía un mensaje Activity al bot cuando finaliza la carga y la respuesta que recibe el cliente incluirá el identificador de la actividad que se envió.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Envío de varios datos adjuntos mediante carga
Para enviar varios datos adjuntos mediante carga, emita una solicitud POST de varias partes al punto de conexión /v3/directline/conversations/{conversationId}/upload. Establezca el encabezado Content-Type de la solicitud en multipart/form-data e incluya el encabezado Content-Type y el encabezado Content-Disposition para que cada parte especifique el tipo y el nombre de archivo de los datos adjuntos. En el identificador URI de la solicitud, establezca el parámetro userId en el identificador del usuario que envía el mensaje.
Puede incluir un objeto Activity en la solicitud con la adición de una parte que especifica como encabezado Content-Type el valor application/vnd.microsoft.activity. Si la solicitud incluye una actividad, los datos adjuntos especificados por otras partes de la carga se agregan como datos adjuntos a esa actividad antes de enviarlos. Si la solicitud no incluye una actividad, se crea una actividad vacía para que actúe como el contenedor en el que se envían los datos adjuntos especificados.
Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud de envío de varios datos adjuntos y la respuesta. En este ejemplo, la solicitud envía un mensaje que contiene texto y un único adjunto de imagen. Se pueden agregar partes adicionales a la solicitud para incluir varios datos adjuntos en este mensaje.
Solicitud
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
Response
Si la solicitud es correcta, se envía un mensaje Activity al bot cuando finaliza la carga y la respuesta que recibe el cliente incluirá el identificador de la actividad que se envió.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}