Envío y recepción de mensajes con Bot Connector API
Bot Connector service permite a un bot comunicarse mediante varios canales, como el correo electrónico, Slack y mucho más. Facilita la comunicación entre el bot y el usuario mediante la retransmisión de actividades desde el bot hacia el canal y viceversa. Cada actividad contiene información utilizada para enrutar el mensaje al destino adecuado junto con información sobre quién creó el mensaje, cuál es su contexto y quién es el destinatario del mismo. En este artículo se describe cómo usar el servicio Bot Connector para intercambiar actividades de mensaje entre el bot y el usuario en un canal.
Respuestas para un mensaje
Creación de una respuesta
Cuando el usuario envía un mensaje al bot, el bot recibirá el mensaje como un objeto Actividad de tipo message. Para crear una respuesta para el mensaje de un usuario, cree un nuevo objeto Activity y comience por establecer estas propiedades:
| Propiedad | Value |
|---|---|
| conversación | Establezca esta propiedad como el contenido de la propiedad conversation en el mensaje del usuario. |
| desde | Establezca esta propiedad como el contenido de la propiedad recipient en el mensaje del usuario. |
| locale | Establezca esta propiedad como el contenido de la propiedad locale en el mensaje del usuario, si está especificada. |
| recipient | Establezca esta propiedad como el contenido de la propiedad from en el mensaje del usuario. |
| replyToId | Establezca esta propiedad como el contenido de la propiedad id en el mensaje del usuario. |
| type | Establezca esta propiedad como message. |
A continuación, establezca las propiedades que especifican la información que desea comunicarle al usuario. Por ejemplo, puede establecer la propiedad text para especificar el texto que se mostrará en el mensaje, la propiedad speak para especificar el texto que su bot dirá en voz alta y la propiedad attachments para especificar los adjuntos multimedia o las tarjetas enriquecidas que se incluirán en el mensaje. Para obtener información detallada acerca de las propiedades de mensaje más usadas, consulte Create messages (Creación de mensajes).
Envío de la respuesta
Use la propiedad serviceUrl de la solicitud entrante para identificar la URI base que el bot debería usar para emitir su respuesta.
Para enviar una respuesta, emita esta solicitud:
POST /v3/conversations/{conversationId}/activities/{activityId}
En este URI de solicitud, reemplace {conversationId} por el valor de la propiedad id del objeto conversation dentro de la actividad (respuesta) y reemplace {activityId} por el valor de la propiedad replyToId dentro de la actividad (respuesta). Establezca el cuerpo de la solicitud como el objeto Actividad que creó para representar el mensaje de respuesta.
En el ejemplo siguiente se muestra una solicitud que envía una respuesta sencilla de solo texto al mensaje de un usuario. En la solicitud del ejemplo, https://smba.trafficmanager.net/teams representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
Envío de un mensaje (de no respuesta)
La mayoría de los mensajes que el bot envíe serán una respuesta a los mensajes que recibe del usuario. Sin embargo, puede haber ocasiones en las que el bot necesite enviar un mensaje a la conversación que no sea una respuesta directa a ningún mensaje del usuario. Por ejemplo, es posible que su bot requiera iniciar un nuevo tema de conversación o enviar un mensaje de despedida al final de la conversación.
Para enviar un mensaje a una conversación que no sea una respuesta directa a ningún mensaje del usuario, emita esta solicitud:
POST /v3/conversations/{conversationId}/activities
En este URI de solicitud, reemplace {conversationId} por el identificador de la conversación.
Establezca el cuerpo de la solicitud como un objeto Actividad que se crea para representar la respuesta.
Nota
Bot Framework no impone ninguna restricción en el número de mensajes que un bot puede enviar. Sin embargo, la mayoría de los canales aplican valores de limitación para impedir que los bots envíen un gran número de mensajes en un breve período de tiempo. Además, si el bot envía varios mensajes en una sucesión rápida, puede que el canal no siempre procese los mensajes en el orden correcto.
Inicio de una conversación
Puede haber ocasiones en las que su bot debe iniciar una conversación con uno o varios usuarios. Para iniciar una conversación con algún usuario en un canal, su bot debe conocer la información de su cuenta y la información de la cuenta del usuario en dicho canal.
Sugerencia
Si es posible que su bot deba iniciar conversaciones con sus usuarios en el futuro, copie en caché la información de la cuenta de usuario, además de otra información pertinente, como las preferencias del usuario, la configuración regional y la dirección URL del servicio (para usarla como la URI base en la solicitud de inicio de la conversación).
Para iniciar una conversación, emita esta solicitud:
POST /v3/conversations
Establezca el cuerpo de la solicitud como un objeto ConversationParameters que especifica la información de la cuenta de su bot y la información de la cuenta de los usuarios que se van a incluir en la conversación.
Nota:
No todos los canales admiten conversaciones de grupo. Consulte la documentación del canal para determinar si un canal es compatible con las conversaciones de grupo e identificar el número máximo de participantes que un canal permite en una conversación.
En el ejemplo siguiente se muestra una solicitud que inicia una conversación. En la solicitud del ejemplo, https://smba.trafficmanager.net/teams representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).
POST https://smba.trafficmanager.net/teams/v3/conversations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
Si se establece la conversación con los usuarios especificados, la respuesta contendrá un identificador para identificar la conversación.
{
"id": "abcd1234"
}
Por lo tanto, el bot puede usar este identificador de conversación para enviar un mensaje a los usuarios dentro de la conversación.