Envoyer et recevoir des messages avec l’API du connecteur botSend and receive messages with the Bot Connector API

Le service Bot Connector permet à un bot de communiquer sur plusieurs canaux tels que Email, Slack, etc.The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. Il facilite la communication entre bot et utilisateur en relayant les activités du bot vers le canal, et du canal vers le bot.It facilitates communication between bot and user, by relaying activities from bot to channel and from channel to bot. Chaque activité contient des informations utilisées pour acheminer le message vers la destination appropriée, ainsi que des informations sur l’auteur du message, le contexte du message et le destinataire du message.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. Cet article explique comment utiliser le service Bot Connector pour échanger des activités de message entre bot et utilisateur sur un canal.This article describes how to use the Bot Connector service to exchange message activities between bot and user on a channel.

Répondre à un messageReply to a message

Créer une réponseCreate a reply

Lorsque l’utilisateur envoie un message à votre robot, ce dernier reçoit le message comme un objet Activité de type message.When the user sends a message to your bot, your bot will receive the message as an Activity object of type message. Pour créer une réponse au message d’un utilisateur, créez un nouvel objet Activity, puis démarrez en définissant les propriétés suivantes :To create a reply to a user's message, create a new Activity object and start by setting these properties:

PropriétéProperty ValeurValue
conversationconversation Définissez cette propriété sur le contenu de la propriété conversation dans le message de l’utilisateur.Set this property to the contents of the conversation property in the user's message.
defrom Définissez cette propriété sur le contenu de la propriété recipient dans le message de l’utilisateur.Set this property to the contents of the recipient property in the user's message.
localelocale Définissez cette propriété sur le contenu de la propriété locale dans le message de l’utilisateur, si spécifié.Set this property to the contents of the locale property in the user's message, if specified.
recipientrecipient Définissez cette propriété sur le contenu de la propriété from dans le message de l’utilisateur.Set this property to the contents of the from property in the user's message.
replyToIdreplyToId Définissez cette propriété sur le contenu de la propriété id dans le message de l’utilisateur.Set this property to the contents of the id property in the user's message.
typetype Définissez cette propriété sur message.Set this property to message.

Ensuite, définissez les propriétés qui spécifient les informations que vous souhaitez communiquer à l’utilisateur.Next, set the properties that specify the information that you want to communicate to the user. Par exemple, vous pouvez définir la propriété text pour spécifier le texte à afficher dans le message, définir la propriété speak pour spécifier le texte qui doit être prononcé par votre bot, et définir la propriété attachments pour spécifier les pièces jointes multimédias ou les cartes enrichies à inclure dans le message.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. Pour plus d’informations sur les propriétés de message les plus couramment utilisées, consultez Créer des messages.For detailed information about commonly-used message properties, see Create messages.

Envoyer la réponseSend the reply

Utilisez la propriété serviceUrl dans l’activité entrante pour identifier l’URI de base que votre bot doit utiliser pour émettre sa réponse.Use the serviceUrl property in the incoming activity to identify the base URI that your bot should use to issue its response.

Pour envoyer la réponse, envoyez la requête suivante :To send the reply, issue this request:

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

Dans cet URI de requête, remplacez {conversationId} par la valeur de la propriété id de l’objet conversation de votre activité de réponse, et remplacez {activityId} par la valeur de la propriété replyToId de votre activité de réponse.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. Définissez le corps de la requête sur l’objet Activité que vous avez créé pour représenter votre réponse.Set the body of the request to the Activity object that you created to represent your reply.

L’exemple suivant montre une requête qui envoie une réponse textuelle simple au message d’un utilisateur.The following example shows a request that sends a simple text-only reply to a user's message. Dans cet exemple de demande, https://smba.trafficmanager.net/apis représente l’URI de base. L’URI de base pour les demandes émises par votre robot peut être différente.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. Pour plus d’informations sur la définition de l’URI de base, voir Informations de référence sur l’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"
}

Envoyer un message (autre qu’une réponse)Send a (non-reply) message

La majorité des messages envoyés par votre bot le seront en réponse aux messages reçus par l’utilisateur.A majority of the messages that your bot sends will be in reply to messages that it receives from the user. Toutefois, il peut arriver que votre bot doive envoyer un message à la conversation qui n’est pas une réponse directe à un message envoyé par l’utilisateur.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. Par exemple, votre bot peut avoir besoin de lancer un nouveau sujet de conversation ou d’envoyer un message pour dire au revoir à la fin d’une conversation.For example, your bot may need to start a new topic of conversation or send a goodbye message at the end of the conversation.

Pour envoyer un message à une conversation qui ne soit pas une réponse directe à un message de l’utilisateur, exécutez la requête suivante :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

Dans cet URI de requête, remplacez {conversationId} par l’ID de la conversation.In this request URI, replace {conversationId} with the ID of the conversation.

Définissez le corps de la requête sur un objet Activité que vous avez créé pour représenter votre réponse.Set the body of the request to an Activity object that you create to represent your reply.

Notes

Bot Framework n’impose aucune restriction concernant le nombre de messages qu’un bot peut envoyer.The Bot Framework does not impose any restrictions on the number of messages that a bot may send. Toutefois, la plupart des canaux appliquent des limitations de requêtes pour empêcher les bots d’envoyer un grand nombre de messages dans un court laps de temps.However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. En outre, si le bot envoie plusieurs messages successifs rapidement, le canal risque de ne pas toujours afficher les messages dans le bon ordre.Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

Démarrer une conversationStart a conversation

Il peut arriver que votre bot ait besoin de démarrer une conversation avec un ou plusieurs utilisateurs.There may be times when your bot needs to initiate a conversation with one or more users. Pour démarrer une conversation avec un utilisateur sur un canal, votre bot doit connaître ses informations de compte, ainsi que les informations de compte de l’utilisateur sur ce 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.

Conseil

Si votre bot aura besoin plus tard de démarrer des conversations avec ses utilisateurs, mettez dans le cache les informations de compte d’utilisateur, d’autres informations pertinentes comme les préférences utilisateur et les paramètres régionaux, et enfin, l’URL du service (à utiliser comme URI de base dans la requête Start Conversation).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).

Pour démarrer une conversation, exécutez la requête suivante :To start a conversation, issue this request:

POST /v3/conversations

Définissez le corps de la requête sur un objet ConversationParameters qui spécifie les informations de compte de votre robot et les informations de compte du ou des utilisateurs que vous souhaitez inclure dans la conversation.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.

Notes

Tous les canaux ne prennent pas en charge les conversations de groupe.Not all channels support group conversations. Consultez la documentation du canal pour déterminer si un canal prend en charge les conversations de groupe, et pour connaître le nombre maximal de participants autorisés par un canal dans une conversation.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.

L’exemple suivant montre une requête qui démarre une conversation.The following example shows a request that starts a conversation. Dans cet exemple de demande, https://smba.trafficmanager.net/apis représente l’URI de base. L’URI de base pour les demandes émises par votre robot peut être différente.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. Pour plus d’informations sur la définition de l’URI de base, voir Informations de référence sur l’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 la conversation est établie avec les utilisateurs spécifiés, la réponse contient un ID qui identifie la conversation.If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "id": "abcd1234"
}

Votre bot peut ensuite utiliser cet ID de conversation pour envoyer un message aux utilisateurs dans le cadre de la conversation.Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

Ressources supplémentairesAdditional resources