Отправка и получение сообщений с помощью API соединителя Bot
Служба Bot Connector позволяет боту взаимодействовать через различные каналы связи, такие как электронная почта, Slack и др. Она обеспечивает обмен данными между ботом и пользователем, ретранслируя действия между ботом и каналом в двустороннем порядке. Каждое действие содержит сведения, используемые для маршрутизации сообщения в соответствующее место назначения, а также сведения о создателе, контексте и получателе сообщения. В этой статье описывается, как использовать службу Bot Connector для обмена действиями сообщений между ботом и пользователем через канал.
Ответ на сообщение
Создание ответа
Когда пользователь отправляет боту сообщение, этот бот получает сообщение в виде объекта Действие с типом message. Чтобы создать ответ на сообщение пользователя, создайте объект Activity и задайте ему следующие свойства:
| Свойство | Значение |
|---|---|
| диалог | Присвойте этому свойству значение свойства conversation из сообщения пользователя. |
| из | Присвойте этому свойству значение свойства recipient из сообщения пользователя. |
| локаль | Присвойте этому свойству значение свойства locale из сообщения пользователя, если оно указано. |
| recipient | Присвойте этому свойству значение свойства from из сообщения пользователя. |
| replyToId | Присвойте этому свойству значение свойства id из сообщения пользователя. |
| type | Присвойте этому свойству значение message. |
Затем задайте свойства, которые определяют передаваемую пользователю информацию. Например, свойство text позволяет указать текст, отображаемый в сообщении, свойство speak — произносимый ботом текст, а свойство attachments — включаемые в сообщение вложения мультимедиа или расширенные карточки. Дополнительные сведения о часто используемых свойствах сообщения см. в руководстве по созданию сообщений.
Отправка отчета
Используйте свойство serviceUrl во входящем действии, чтобы определить базовый URI, который бот будет применять для отправки ответа.
Чтобы отправить ответ, выполните такой запрос:
POST /v3/conversations/{conversationId}/activities/{activityId}
В URI этого запроса замените {conversationId} значением id из объекта conversation для действия (ответа), а также замените {activityId} значением свойства replyToId для действия (ответа). В текст запроса поместите объект Действие, созданный для представления ответа.
Следующий пример демонстрирует запрос, который отправляет простой текстовый ответ на сообщение пользователя. В этом примере запрос https://smba.trafficmanager.net/teams представляет базовый URI. Базовый URI для запросов, отправляемых вашим ботом, может отличаться. Дополнительные сведения о настройке базового URI см. в статье Справочник по 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"
}
Отправка сообщения (не ответа)
Как правило, бот отправляет сообщения только в ответ на сообщения пользователя. Однако в некоторых случаях боту может потребоваться отправить сообщение в беседу, которое не является прямым ответом на какое-либо сообщение от пользователя. Например, бот может начать беседу на новую тему или попрощаться с пользователем в конце беседы.
Чтобы отправить сообщение в беседу, которое не является прямым ответом на любое сообщение от пользователя, выполните следующий запрос:
POST /v3/conversations/{conversationId}/activities
В URI запроса замените {conversationId} значением идентификатора беседы.
В текст запроса поместите объект Действие, созданный для представления сообщения.
Примечание
Bot Framework не накладывает никаких ограничений на количество сообщений, которые может отправлять бот. Тем не менее большинство каналов принудительно применяет ограничения регулирования, запрещая ботам отправлять большое число сообщений за короткий период времени. Кроме того, если бот отправляет несколько сообщений за короткий промежуток времени, канал не всегда может обрабатывать сообщения в правильной последовательности.
Начало общения
Возможны ситуации, когда боту требуется инициировать беседу с одним или несколькими пользователями. Чтобы начать беседу с пользователем по определенному каналу, бот должен иметь сведения о своей учетной записи и об учетной записи пользователя в соответствующем канале.
Совет
Если в будущем боту может потребоваться снова начать беседу с пользователями, сохраните в кэш данные о соответствующих учетных записях и другие важные сведения, например персональные настройки и языковой стандарт, а также URL-адрес службы (чтобы создать базовый URI для запроса на создание беседы).
Чтобы начать беседу, выполните такой запрос:
POST /v3/conversations
В текст запроса поместите объект ConversationParameters, содержащий сведения об учетной записи бота и учетной записи пользователя или пользователей, которых нужно включить в беседу.
Примечание
Не все каналы поддерживают групповые беседы. Изучите документацию по используемому каналу, чтобы узнать о поддержке групповых бесед и ограничениях на число участников в них.
В следующем примере показан запрос, который начинает беседу: В этом примере запрос https://smba.trafficmanager.net/teams представляет базовый URI. Базовый URI для запросов, отправляемых вашим ботом, может отличаться. Дополнительные сведения о настройке базового URI см. в статье Справочник по 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"
}
Если беседа с указанными пользователями создана, ответ будет содержать идентификатор этой беседы.
{
"id": "abcd1234"
}
Теперь бот может использовать идентификатор беседы для отправки сообщений пользователям в этой беседе.