Bot Connector API를 사용 하 여 메시지 보내기 및 받기Send and receive messages with the Bot Connector API

Bot Connector 서비스를 사용하면 봇이 이메일, Slack 등의 여러 채널을 통해 통신할 수 있습니다.The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. 봇에서 채널로, 그리고 채널에서 봇으로 활동을 릴레이하여 봇과 사용자 간에 쉽게 통신할 수 있게 합니다.It facilitates communication between bot and user, by relaying activities from bot to channel and from channel to bot. 모든 활동에는 메시지를 만든 사람, 메시지 컨텍스트 및 메시지 받는 사람에 대한 정보와 함께 메시지를 적절한 대상에게 라우팅하는 데 사용되는 정보가 포함되어 있습니다.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. 이 문서에서는 Bot Connector 서비스를 사용하여 채널에서 봇과 사용자 간에 메시지 활동을 교환하는 방법을 설명합니다.This article describes how to use the Bot Connector service to exchange message activities between bot and user on a channel.

메시지에 회신Reply to a message

회신 만들기Create a reply

사용자가 봇에 메시지를 보내면 봇은 message 형식의 Activity 개체로 메시지를 받습니다.When the user sends a message to your bot, your bot will receive the message as an Activity object of type message. 사용자 메시지에 대한 회신을 만들려면 새 Activity 개체를 만들고 다음 속성을 설정하여 시작합니다.To create a reply to a user's message, create a new Activity object and start by setting these properties:

속성Property Value
대화conversation 이 속성을 사용자 메시지의 conversation 속성 내용으로 설정합니다.Set this property to the contents of the conversation property in the user's message.
원본from 이 속성을 사용자 메시지의 recipient 속성 내용으로 설정합니다.Set this property to the contents of the recipient property in the user's message.
localelocale 지정된 경우 이 속성을 사용자 메시지의 locale 속성 내용으로 설정합니다.Set this property to the contents of the locale property in the user's message, if specified.
recipientrecipient 이 속성을 사용자 메시지의 from 속성 내용으로 설정합니다.Set this property to the contents of the from property in the user's message.
replyToIdreplyToId 이 속성을 사용자 메시지의 id 속성 내용으로 설정합니다.Set this property to the contents of the id property in the user's message.
typetype 이 속성을 message로 설정합니다.Set this property to message.

사용자에게 전달하려는 정보를 지정하는 속성을 설정합니다.Next, set the properties that specify the information that you want to communicate to the user. 예를 들어, text 속성을 설정하여 메시지에 표시할 텍스트를 지정하고, speak 속성을 설정하여 봇이 말할 텍스트를 지정하고, attachments 속성을 설정하여 메시지에 포함할 미디어 첨부 파일 또는 서식 있는 카드를 지정할 수 있습니다.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. 일반적으로 사용되는 메시지 속성에 대한 자세한 내용은 메시지 만들기를 참조하세요.For detailed information about commonly-used message properties, see Create messages.

회신 보내기Send the reply

들어오는 활동의 serviceUrl 속성을 사용하여 봇이 해당 응답을 실행하는 데 사용해야 하는 기본 URI를 식별합니다.Use the serviceUrl property in the incoming activity to identify the base URI that your bot should use to issue its response.

회신을 보내려면 다음 요청을 실행합니다.To send the reply, issue this request:

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

이 요청 URI에서 {conversationId} 를 (회신) Activity 내 conversation 개체의 id 속성 값으로 바꾸고, {activityId} 를 (회신) Activity 내 replyToId 속성 값으로 바꿉니다.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. 요청 본문을, 회신을 나타내기 위해 만든 Activity 개체로 설정합니다.Set the body of the request to the Activity object that you created to represent your reply.

다음 예제에서는 사용자 메시지에 대한 단순한 텍스트 전용 회신을 보내는 요청을 보여 줍니다.The following example shows a request that sends a simple text-only reply to a user's message. 이 예제 요청에서 https://smba.trafficmanager.net/apis는 기본 URI를 나타냅니다. 봇이 실행하는 요청의 기본 URI는 다를 수 있습니다.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. 기본 URI를 설정하는 방법에 대한 자세한 내용은 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"
}

(비회신) 메시지 보내기Send a (non-reply) message

봇이 보내는 대부분의 메시지는 사용자로부터 받은 메시지에 대한 회신입니다.A majority of the messages that your bot sends will be in reply to messages that it receives from the user. 그러나 봇이 사용자 메시지에 대한 직접 회신이 아닌 메시지를 대화에 보내야 하는 경우도 있을 수 있습니다.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. 예를 들어, 봇이 대화의 새 주제를 시작하거나 대화를 끝낼 때 인사 메시지를 보내야 할 수 있습니다.For example, your bot may need to start a new topic of conversation or send a goodbye message at the end of the conversation.

사용자 메시지에 대한 직접 회신이 아닌 메시지를 대화에 보내려면 다음 요청을 실행합니다.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

이 요청 URI에서 {conversationId} 를 대화의 ID로 바꿉니다.In this request URI, replace {conversationId} with the ID of the conversation.

요청 본문을, 회신을 나타내기 위해 만든 Activity 개체로 설정합니다.Set the body of the request to an Activity object that you create to represent your reply.

참고

Bot Framework에는 봇이 보낼 수 있는 메시지 수에 대한 제한이 없습니다.The Bot Framework does not impose any restrictions on the number of messages that a bot may send. 그러나 대부분의 채널은 제한 한도를 적용하여 봇이 짧은 기간에 다수의 메시지를 보낼 수 없도록 제한합니다.However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. 또한 봇이 여러 메시지를 빠르게 연속적으로 보내는 경우 채널이 메시지를 올바른 순서로 렌더링하지 못할 수도 있습니다.Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

대화 시작Start a conversation

봇이 한 명 이상의 사용자와 대화를 시작해야 하는 경우도 있을 수 있습니다.There may be times when your bot needs to initiate a conversation with one or more users. 채널에서 사용자와 대화를 시작하려면 봇이 해당 계정 정보 및 채널의 사용자 계정 정보를 알고 있어야 합니다.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.

나중에 봇이 사용자와 대화를 시작해야 할 수 있는 경우 사용자 계정 정보, 기타 관련 정보(예: 사용자 기본 설정, 로캘) 및 서비스 URL(대화 시작 요청에서 기본 URI로 사용)을 캐시합니다.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).

대화를 시작하려면 다음 요청을 실행합니다.To start a conversation, issue this request:

POST /v3/conversations

요청 본문을, 봇의 계정 정보 및 대화에 포함하려는 사용자의 계정 정보를 지정하는 ConversationParameters 개체로 설정합니다.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.

참고

일부 채널은 그룹 대화를 지원하지 않습니다.Not all channels support group conversations. 채널 설명서를 참조하여 채널이 그룹 대화를 지원하는지 확인하고, 채널이 대화에 허용하는 최대 참가자 수를 파악합니다.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.

다음 예제에서는 대화를 시작하는 요청을 보여 줍니다.The following example shows a request that starts a conversation. 이 예제 요청에서 https://smba.trafficmanager.net/apis는 기본 URI를 나타냅니다. 봇이 실행하는 요청의 기본 URI는 다를 수 있습니다.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. 기본 URI를 설정하는 방법에 대한 자세한 내용은 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"
}

지정한 사용자와 대화가 설정되면 대화를 식별하는 ID가 응답에 포함됩니다.If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "id": "abcd1234"
}

그러면 봇이 이 대화 ID를 사용하여 대화 내에서 사용자에게 메시지를 보낼 수 있습니다.Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

추가 리소스Additional resources