Envío y recepción de mensajes con Bot Connector APISend and receive messages with the Bot Connector API

Bot Connector service permite a un bot comunicarse mediante varios canales, como el correo electrónico, Slack y mucho más.The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. Facilita la comunicación entre el bot y el usuario mediante la retransmisión de actividades desde el bot hacia el canal y viceversa.It facilitates communication between bot and user, by relaying activities from bot to channel and from channel to bot. 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.Every activity contains information used for routing the message to the appropriate destination along with information about who created the message, the context of the message, and the recipient of the message. 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.This article describes how to use the Bot Connector service to exchange message activities between bot and user on a channel.

Respuestas para un mensajeReply to a message

Creación de una respuestaCreate a reply

Cuando el usuario envía un mensaje al bot, el bot recibirá el mensaje como un objeto Actividad de tipo message.When the user sends a message to your bot, your bot will receive the message as an Activity object of type message. Para crear una respuesta para el mensaje de un usuario, cree un nuevo objeto Activity y comience por establecer estas propiedades:To create a reply to a user's message, create a new Activity object and start by setting these properties:

PropiedadProperty ValueValue
conversaciónconversation Establezca esta propiedad como el contenido de la propiedad conversation en el mensaje del usuario.Set this property to the contents of the conversation property in the user's message.
desdefrom Establezca esta propiedad como el contenido de la propiedad recipient en el mensaje del usuario.Set this property to the contents of the recipient property in the user's message.
localelocale Establezca esta propiedad como el contenido de la propiedad locale en el mensaje del usuario, si está especificada.Set this property to the contents of the locale property in the user's message, if specified.
recipientrecipient Establezca esta propiedad como el contenido de la propiedad from en el mensaje del usuario.Set this property to the contents of the from property in the user's message.
replyToIdreplyToId Establezca esta propiedad como el contenido de la propiedad id en el mensaje del usuario.Set this property to the contents of the id property in the user's message.
typetype Establezca esta propiedad como message.Set this property to message.

A continuación, establezca las propiedades que especifican la información que desea comunicarle al usuario.Next, set the properties that specify the information that you want to communicate to the user. 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.For example, you can set the text property to specify the text to be displayed in the message, set the speak property to specify text to be spoken by your bot, and set the attachments property to specify media attachments or rich cards to include in the message. Para obtener información detallada acerca de las propiedades de mensaje más usadas, consulte Create messages (Creación de mensajes).For detailed information about commonly-used message properties, see Create messages.

Envío de la respuestaSend the reply

Use la propiedad serviceUrl de la solicitud entrante para identificar la URI base que el bot debería usar para emitir su respuesta.Use the serviceUrl property in the incoming activity to identify the base URI that your bot should use to issue its response.

Para enviar una respuesta, emita esta solicitud:To send the reply, issue this request:

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).In this request URI, replace {conversationId} with the value of the conversation object's id property within your (reply) Activity and replace {activityId} with the value of the replyToId property within your (reply) Activity. Establezca el cuerpo de la solicitud como el objeto Actividad que creó para representar el mensaje de respuesta.Set the body of the request to the Activity object that you created to represent your reply.

En el ejemplo siguiente se muestra una solicitud que envía una respuesta sencilla de solo texto al mensaje de un usuario.The following example shows a request that sends a simple text-only reply to a user's message. En la solicitud del ejemplo, https://smba.trafficmanager.net/apis representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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 (sin respuesta)Send a (non-reply) message

La mayoría de los mensajes que el bot envíe serán una respuesta a los mensajes que recibe del usuario.A majority of the messages that your bot sends will be in reply to messages that it receives from the user. Sin embargo, puede haber ocasiones en las que su bot requiera enviar a la conversación un mensaje que no es una respuesta directa a algún mensaje del usuario.However, there may be times when your bot needs to send a message to the conversation that is not a direct reply to any message from the user. 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.For example, your bot may need to start a new topic of conversation or send a goodbye message at the end of the conversation.

Para enviar a la conversación un mensaje que no sea una respuesta directa a algún mensaje del usuario, emita esta solicitud:To send a message to a conversation that is not a direct reply to any message from the user, issue this request:

POST /v3/conversations/{conversationId}/activities

En este URI de solicitud, reemplace {conversationId} por el identificador de la conversación.In this request URI, replace {conversationId} with the ID of the conversation.

Establezca el cuerpo de la solicitud como un objeto Actividad que se crea para representar la respuesta.Set the body of the request to an Activity object that you create to represent your reply.

Nota

Bot Framework no impone ninguna restricción en el número de mensajes que puede enviar un bot.The Bot Framework does not impose any restrictions on the number of messages that a bot may send. 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.However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. 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.Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

Inicio de una conversaciónStart a conversation

Puede haber ocasiones en las que su bot debe iniciar una conversación con uno o varios usuarios.There may be times when your bot needs to initiate a conversation with one or more users. 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.To start a conversation with a user on a channel, your bot must know its account information and the user's account information on that channel.

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).If your bot may need to start conversations with its users in the future, cache user account information, other relevant information such as user preferences and locale, and the service URL (to use as the base URI in the Start Conversation request).

Para iniciar una conversación, emita esta solicitud:To start a conversation, issue this request:

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.Set the body of the request to a ConversationParameters object that specifies your bot's account information and the account information of the user(s) that you want to include in the conversation.

Nota

No todos los canales admiten conversaciones de grupo.Not all channels support group conversations. 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.Consult the channel's documentation to determine whether a channel supports group conversations and to identify the maximum number of participants that a channel allows in a conversation.

En el ejemplo siguiente se muestra una solicitud que inicia una conversación.The following example shows a request that starts a conversation. En la solicitud del ejemplo, https://smba.trafficmanager.net/apis representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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.If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "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.Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

Recursos adicionalesAdditional resources