Поделиться через

Справочник по API для службы Подключение Bot Framework

  • Статья

Примечание.

REST API не эквивалентен пакету SDK. REST API позволяет установить стандартную связь REST, однако предпочтительный способ взаимодействия с Bot Framework — это SDK.

На платформе Bot Framework есть служба Bot Connector, которая позволяет боту обмениваться сообщениями с каналами, настроенными на портале Bot Framework. Эта служба использует стандартные отраслевые протоколы REST и JSON через HTTPS.

Базовый универсальный код ресурса (URI)

Когда пользователь отправляет сообщение боту, входящий запрос содержит объект Activity со свойством serviceUrl, которое указывает конечную точку, в которую бот должен отправить ответ. Для доступа к службе Bot Connector используйте значение serviceUrl как базовый URI для запросов API.

Если у вас еще нет URL-адреса службы для канала, используйте https://smba.trafficmanager.net/teams/ его в качестве URL-адреса службы. Дополнительные сведения см. в статье о создании беседы и упреждающего сообщения в Teams.

Например, предположим, что бот получает следующее действие, когда пользователь отправляет сообщение боту.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

Свойство serviceUrl в сообщении пользователя указывает, что бот должен отправить свой ответ в конечную точку https://smba.trafficmanager.net/teams/. URL-адрес службы будет базовым универсальным кодом ресурса (URI) для всех последующих запросов, которые бот выдает в контексте этой беседы. Если боту будет необходимо отправить пользователю упреждающее сообщение, не забудьте сохранить значение serviceUrl.

В следующем примере показан запрос, который бот выдает в ответ на сообщение пользователя.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

Заголовки

Заголовки запросов

Помимо стандартных заголовков HTTP-запроса каждый выдаваемый запрос API должен включать заголовок Authorization, который указывает маркер доступа для проверки подлинности бота. Используйте для заголовка Authorization следующий формат:

Authorization: Bearer ACCESS_TOKEN

Дополнительные сведения о том, как получить маркер доступа для бота, см. в разделе Authenticate requests from your bot to the Bot Connector service (Проверка подлинности запросов от бота в службу Bot Connector).

Заголовки ответа

Помимо стандартных заголовков HTTP-ответа каждый ответ будет содержать заголовок X-Correlating-OperationId. Значение этого заголовка — это идентификатор, соответствующий записи журнала Bot Framework, которая содержит сведения о запросе. При получении ответа об ошибке необходимо записать значение этого заголовка. Если вы не сможете самостоятельно устранить проблему, включите это значение в сведения, предоставленные группе поддержки при отправке сообщения о проблеме.

Коды состояния HTTP

Код состояния HTTP, который возвращается с каждым ответом, указывает результат соответствующего запроса.

Примечание.

В следующей таблице описываются наиболее распространенные коды состояния HTTP. Некоторые ошибки создаются каналом. Для получения дополнительных сведений может потребоваться ознакомиться с документацией разработчика канала.

Код состояния HTTP Значение
200 Запрос выполнен успешно.
201 Запрос выполнен успешно.
202 Запрос был принят для обработки.
204 Запрос успешно выполнен, но содержимое не было возвращено.
400 Запрос неправильный или имеет недопустимый формат.
401 Бот еще не прошел проверку подлинности.
403 Бот не авторизован для выполнения запрошенной операции.
404 Запрошенный ресурс не найден.
405 Канал не поддерживает запрошенную операцию.
500 Произошла внутренняя ошибка сервера.
503 Служба временно недоступна.

ошибки

Любой ответ, указывающий код состояния HTTP в диапазоне 4xx или 5xx, будет содержать в тексте ответа объект ErrorResponse, который предоставляет сведения об ошибке. Если вы получите сообщение об ошибке в диапазоне 4xx, проверьте объект ErrorResponse, чтобы определить причину ошибки и устранить проблему, прежде чем повторно отправлять запрос.

Операции диалога

Используйте следующие операции для создания общения, отправки сообщений (действий) и управления содержимым общения.

Важно!

Не все каналы поддерживают все конечные точки. Однако все каналы должны поддерживать ответ на конечную точку действия .

Например, только Direct Line и Веб-чат поддерживают конечную точку получения бесед.

Операция Description
Создать общение Создает новое общение.
Действие удаления Удаляет существующее действие.
Удаление члена беседы Удаляет участника из диалога.
Получение членов действия Возвращает участников указанного действия в указанном общении.
Получение участника беседы Возвращает сведения об участнике диалога.
Получение участников беседы Возвращает участников указанного общения.
Получение участников беседы Возвращает участников указанной беседы по одной странице за раз.
Получение бесед Получает список диалогов, в которых бот принимал участие.
Ответ на действие Отправляет действие (сообщение) в указанное общение как ответ на указанное действие.
Отправить журнал бесед Отправляет расшифровку последних действий в диалог.
Отправка в беседу Отправляет действие (сообщение) в конец указанного общения.
Обновление действия Обновляет существующее действие.
Отправка вложения в канал Передает вложение непосредственно в хранилище BLOB-объектов канала.

Создание беседы

Создает новое общение.

POST /v3/conversations
Содержимое Description
Текст запроса Объект ConversationParameters
Возвраты Объект ConversationResourceResponse

Действие удаления

Некоторые каналы позволяют удалить существующее действие. При успешном выполнении эта операция удаляет указанное действие из указанного общения.

DELETE /v3/conversations/{conversationId}/activities/{activityId}
Содержимое Description
Текст запроса Н/Д
Возвраты Код состояния HTTP, который указывает результат операции. В тексте ответа ничего не указано.

Удаление члена беседы

Удаляет участника из диалога. Если этот участник был последним в диалоге, диалог также будет удален.

DELETE /v3/conversations/{conversationId}/members/{memberId}
Содержимое Description
Текст запроса Н/Д
Возвраты Код состояния HTTP, который указывает результат операции. В тексте ответа ничего не указано.

Получение элементов действия

Возвращает участников указанного действия в указанном общении.

GET /v3/conversations/{conversationId}/activities/{activityId}/members
Содержимое Description
Текст запроса Н/Д
Возвраты Массив объектов ChannelAccount

Получение бесед

Получает список диалогов, в которых бот принимал участие.

GET /v3/conversations?continuationToken={continuationToken}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект ConversationsResult

Получение участника беседы

Возвращает сведения об определенном участнике определенного диалога.

GET /v3/conversations/{conversationId}/members/{memberId}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект ChannelAccount для участника.

Получение участников беседы

Возвращает участников указанного общения.

GET /v3/conversations/{conversationId}/members
Содержимое Description
Текст запроса Н/Д
Возвраты Массив объектов ChannelAccount для участников диалога.

Получение участников беседы

Возвращает участников указанной беседы по одной странице за раз.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект PagedMembersResult

Ответ на действие

Отправляет действие (сообщение) в указанное общение как ответ на указанное действие. Действие добавляется в качестве ответа на другое действие, если канал это поддерживает. Если канал не поддерживает вложенные ответы, эта операция ведет себя как отправка в беседу.

POST /v3/conversations/{conversationId}/activities/{activityId}
Содержимое Description
Текст запроса Объект Activity
Возвраты Объект ResourceResponse

Отправка журнала бесед

Отправляет расшифровку последних действий в диалог, поэтому клиент может преобразовать их для просмотра.

POST /v3/conversations/{conversationId}/activities/history
Содержимое Description
Текст запроса Объект Transcript.
Возвраты Объект ResourceResponse.

Отправка в беседу

Отправляет действие (сообщение) в указанное общение. Действие будет добавлено в конец общения в соответствии с меткой времени или семантикой канала. Чтобы ответить на конкретное сообщение внутри общения, вместо этого используйте Ответить на действие.

POST /v3/conversations/{conversationId}/activities
Содержимое Description
Текст запроса Объект Activity
Возвраты Объект ResourceResponse

Обновление действия

Некоторые каналы позволяют изменить существующее действие, чтобы отразить новое состояние общения бота. Например, можно удалять кнопки из сообщения в общении после того, как пользователь нажмет одну из кнопок. При успешном выполнении эта операция обновляет указанное действие в рамках указанного общения.

PUT /v3/conversations/{conversationId}/activities/{activityId}
Содержимое Description
Текст запроса Объект Activity
Возвраты Объект ResourceResponse

Отправка вложения в канал

Передает вложение указанного общения непосредственно в хранилище BLOB-объектов канала. Это позволяет хранить данные в соответствующем хранилище.

POST /v3/conversations/{conversationId}/attachments
Содержимое Description
Текст запроса Объект AttachmentData.
Возвраты Объект ResourceResponse. Свойство идентификатора указывает идентификатор вложения, который можно использовать с операцией получения сведений о вложениях и операцией Получения вложений .

Операции вложения

Используйте следующие операции для получения сведений о вложениях и двоичных данных для самого файла.

Операция Description
Получить сведения о вложениях Получает сведения об указанном вложениях, включая имя файла, тип файла и доступные представления (например, исходный или эскиз).
Получить вложение Получает указанное представление указанного вложения как двоичное содержимое.

Получение сведений о вложении

Получает сведения об указанном вложениях, включая имя файла, тип и доступные представления (например, исходный или эскиз).

GET /v3/attachments/{attachmentId}
Содержимое Description
Текст запроса Н/Д
Возвраты Объект AttachmentInfo

Получение вложения

Получает указанное представление указанного вложения как двоичное содержимое.

GET /v3/attachments/{attachmentId}/views/{viewId}
Содержимое Description
Текст запроса Н/Д
Возвраты Двоичное содержимое, отображающее указанное представление указанного вложения

Операции состояния (нерекомендуемые)

Служба состояний Microsoft Bot Framework устарела с 30 марта 2018 г. Ранее боты, созданные на основе azure AI Служба Bot или пакета SDK Bot Builder, имели подключение по умолчанию к этой службе, размещенной корпорацией Майкрософт для хранения данных о состоянии бота. Теперь эти боты нужно обновить, чтобы они использовали собственное хранилище состояний.

Операция Description
Set User Data Сохраняет данные состояния для конкретного пользователя на канале.
Set Conversation Data Сохраняет данные состояния для конкретного общения на канале.
Set Private Conversation Data Сохраняет данные состояния для конкретного пользователя в контексте указанного общения на канале.
Get User Data Извлекает данные состояния, сохраненные ранее для конкретного пользователя во всех сеансах общения на канале.
Get Conversation Data Извлекает данные состояния, сохраненные ранее для конкретного общения на канале.
Get Private Conversation Data Извлекает данные состояния, сохраненные ранее для конкретного пользователя в контексте указанного общения на канале.
Delete State For User Удаляет данные состояния, сохраненные ранее для конкретного пользователя.

Схема

Схема действия Bot Framework определяет объекты и свойства, которые бот может использовать для взаимодействия с пользователем.

Объект Description
Объект Activity Определяет сообщения, которыми обмениваются бот и пользователь.
Объект AnimationCard Определяет карту, которая может воспроизводить файлы GIF с анимацией или короткие видео.
Объект Attachment Определяет дополнительные сведения для включения в сообщение. Вложение может быть файлом мультимедиа (например, аудио, видео, изображением, файлом) или богатым карта.
Объект AttachmentData Описывает данные вложения.
Объект AttachmentInfo Описывает вложение.
Объект AttachmentView Определяет объект, представляющий доступное представление для вложения.
Объект AudioCard Определяет карту, которая может воспроизводить звуковые файлы.
Объект CardAction Определяет действие для выполнения.
Объект CardImage Определяет изображение для отображения на карте.
Объект ChannelAccount Определяет бота или учетную запись пользователя на канале.
Объект ConversationAccount Определяет общение на канале.
Объект ConversationMembers Определяет участников беседы.
Объект ConversationParameters Определяет параметры для создания нового общения.
Объект ConversationReference Определяет конкретный момент в общении.
Объект ConversationResourceResponse Определяет ответ на операцию Создать диалог.
Объект ConversationsResult Определяет результат вызова операции Получить диалоги.
Объект Entity Определяет объект сущности.
Объект Error Определяет ошибку.
Объект ErrorResponse Определяет ответ API HTTP.
Объект Fact Определяет пару "ключ — значение", содержащую факт.
Объект GeoСoordinates Определяет географическое расположение с помощью координат всемирной геодезической системы (WSG84).
Объект HeroCard Определяет карту с большим изображением, заголовком, текстом и командной кнопкой.
Объект InnerHttpError Объект, представляющий внутреннюю ошибку HTTP.
Объект MediaEventValue Дополнительный параметр для событий мультимедиа.
Объект MediaUrl Определяет URL-адрес источника файла мультимедиа.
Объект Mention Определяет пользователя или бота, упомянутого в общении.
Объект MessageReaction Определяет ответную реакцию на сообщение.
Объект PagedMembersResult Страница участников, возвращаемая операцией получения участников диалога по страницам.
Объект Place Определяет место, упомянутое в общении.
Объект ReceiptCard Определяет карту, которая содержит квитанцию о покупке.
Объект ReceiptItem Определяет элемент строки в квитанции.
Объект ResourceResponse Определяет ресурс.
Объект SemanticAction Определяет ссылку на программное действие.
Объект SignInCard Определяет карту, которая позволяет пользователю выполнить вход в службу.
Объект SuggestedActions Определяет варианты действий, из которых пользователь может выбирать.
Объект TextHighlight Ссылается на подстроку содержимого в другом поле.
Объект ThumbnailCard Определяет карту с эскизом изображения, заголовком, текстом и командной кнопкой.
Объект ThumbnailUrl Определяет URL-адрес источника изображения.
Объект Transcript Коллекция действий, отправляемых с помощью операции Отправить журнал бесед.
Объект VideoCard Определяет карту, которая может воспроизводить видео.

Объект Activity

Определяет сообщения, которыми обмениваются бот и пользователь.

Свойство Тип Описание
action Строка Действие для применения или уже примененное. Используйте свойство type, чтобы определить контекст для действия. Например, если свойству type задано contactRelationUpdate, значение свойства action будет равняться add, если пользователь добавил бота в список контактов, или remove, если пользователь удалил бота из списка контактов.
attachmentLayout Строка Макет вложенных форматированных карточек, включенных в сообщение. Одно из следующих значений: carousel, list. Дополнительные сведения о форматированных карточках см. в статье Добавление форматированных карточек как вложения к сообщениям.
attachments Attachment[] Массив объектов Attachment, который определяет дополнительные сведения для включения в сообщение. Каждое вложение может быть либо файлом (например, аудио, видео, изображением), либо богатым карта.
callerId Строка Строка, содержащая IRI для идентификации объекта, который вызывает бота. Это поле не предназначено для передачи по проводу, но вместо этого заполняется ботами и клиентами на основе криптографически проверяемых данных, которые утверждают удостоверение вызывающих лиц (например, токены).
channelData Объект Объект, содержащий определяемое каналом содержимое. Некоторые каналы предоставляют функции, требующие дополнительных сведений, которые не могут быть представлены с помощью схемы вложения. В таких случаях для этого свойства задается определяемое каналом содержимое, как указано в документации канала. Дополнительные сведения см. в статье Реализация функциональных возможностей канала.
channelId Строка Идентификатор, однозначно определяющий канал. Задается каналом.
code Строка Код, указывающий причину завершения общения.
беседа ConversationAccount Объект ConversationAccount, определяющий общение, к которому относится действие.
deliveryMode Строка Указание, определяющее альтернативные пути доставки действия получателю. Одно из следующих значений: normal, notification.
entities object[] Массив объектов, представляющих сущности, которые были упомянуты в сообщении. Объекты в этом массиве могут быть любыми объектами из Schema.org. Например, массив может содержать объекты Mention, определяющие пользователя, который был упомянут в общении, и объекты Place, определяющие место, которое было упомянуто в общении.
expiration Строка Время, в течение которого действие должно считаться "истекшим сроком действия" и не должно быть представлено получателю.
from ChannelAccount Объект ChannelAccount, указывающий отправителя сообщения.
historyDisclosed Логическое значение Флаг, указывающий, раскрывается ли журнал. По умолчанию используется значение false.
id Строка Идентификатор, однозначно идентифицирующий действие на канале.
importance Строка Определяет важность действия. Одно из следующих значений: low, normal, high.
inputHint Строка Значение, указывающее, принимает, ожидает или игнорирует бот входные данные пользователя после доставки сообщения клиенту. Одно из следующих значений: acceptingInput, expectingInput или ignoringInput.
метка Строка Описательная метка для действия.
listenFor String[] Список фраз и ссылок, которые должны прослушиваться в системах подготовки речи и языка.
локаль Строка Языковой стандарт для языка, который должен использоваться для отображения текста в сообщении, в формате <language>-<country>. Канал использует это свойство для указания языка пользователя, чтобы бот мог указывать отображаемые строки на этом языке. Значение по умолчанию — en-US.
localTimestamp Строка Дата и время отправки сообщения по местному часовому поясу, выраженные в формате ISO-8601.
localTimezone Строка Содержит имя локального часового пояса сообщения, представленного в формате базы данных часового пояса IANA. Например, America/Los_Angeles.
membersAdded ChannelAccount[] Массив объектов ChannelAccount, представляющий список пользователей, которые присоединились к общению. Присутствует, только когда тип действия равен conversationUpdate и пользователи присоединились к общению.
membersRemoved ChannelAccount[] Массив объектов ChannelAccount, представляющий список пользователей, которые вышли из общения. Присутствует, только когда тип действия — conversationUpdate и пользователи вышли из общения.
имя Строка Имя операции для вызова или имя события.
reactionsAdded MessageReaction[] Коллекция реакций, добавленных в диалог.
reactionsRemoved MessageReaction[] Коллекция реакций, удаленных из диалога.
recipient ChannelAccount Объект ChannelAccount, указывающий получателя сообщения.
relatesTo ConversationReference Объект ConversationReference, который определяет конкретный момент в общении.
replyToId Строка Идентификатор сообщения, ответом на которое является это сообщение. Чтобы ответить на сообщение, отправленное пользователем, присвойте этому свойству значение идентификатора сообщения пользователя. Не все каналы поддерживают цепочки ответов. В таких случаях канал игнорирует это свойство и использует упорядоченную по времени семантику (метку времени) для добавления сообщения в диалог.
semanticAction SemanticAction Объект SemanticAction, представляющий ссылку на программное действие.
serviceUrl Строка URL-адрес, указывающий конечную точку службы канала. Задается каналом.
speak Строка Текст, который боту требуется произнести на канале с поддержкой речевых функций. Чтобы контролировать различные характеристики речи бота, такие как голос, скорость, громкость, произношение и тон, укажите это свойство в формате языка разметки синтеза речи (SSML).
suggestedActions SuggestedActions Объект SuggestedActions, определяющий варианты действий, из которых пользователь может выбирать.
summary Строка Сводка данных, которая содержит сообщение. Например, для сообщения, которое отправляется на канал электронной почты, это свойство может указывать первые 50 символов электронного сообщения.
text Строка Текст сообщения, отправляемого от пользователя к боту или от бота к пользователю. См. документацию канала по ограничениям, накладываемым на содержимое этого свойства.
textFormat Строка Формат текста сообщения. Одно из следующих значений: markdown, plain или xml. Дополнительные сведения о формате текста см. в статье Создание сообщений.
textHighlights TextHighlight[] Коллекция фрагментов текста для выделения, если действие содержит значение replyToId.
timestamp Строка Дата и время отправки сообщения в часовом поясе UTC, выраженные в формате ISO-8601.
topicName Строка Раздел общения, к которому относится действие.
type Строка Тип действия. Одно из следующих значений: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Дополнительные сведения о типах действий см. в статье Общие сведения о действиях.
значение Объект Открытое значение.
valueType Строка Тип объекта значения действия.

Вернуться к таблице "Схема"

Объект AnimationCard

Определяет карту, которая может воспроизводить файлы GIF с анимацией или короткие видео.

Свойство Тип Описание
aspect Логическое значение Пропорции эскиза или заполнителя мультимедиа. Допустимые значения: 16:9 и 4:3.
autoloop Логическое значение Флаг, указывающий, следует ли повторять воспроизведение списка анимированных изображений в формате GIF при завершении последнего. Для автоматического повтора воспроизведения анимации присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
autostart Логическое значение Флаг, указывающий, следует ли автоматически воспроизводить анимацию при отображении карты. Для автоматического воспроизведения анимации присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
duration Строка Длина мультимедийных данных в формате длительности ISO 8601.
Изображение ThumbnailUrl Объект ThumbnailUrl, указывающий изображение, отображаемое на карте.
media MediaUrl[] Массив объектов MediaUrl. Если это поле содержит более одного URL-адреса, это значит, что каждый URL-адрес представляет альтернативный формат одного содержимого.
shareable Логическое значение Флаг, указывающий, может ли анимации быть предоставлен общий доступ. Если анимация может находиться в общем доступе, присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
subtitle Строка Подзаголовок для отображения под заголовком карты.
text Строка Описание или запрос для отображения под заголовком или подзаголовком карты.
title Строка Заголовок карты.
значение Объект Дополнительный параметр для этой карты.

Вернуться к таблице "Схема"

Объект Attachment

Определяет дополнительные сведения для включения в сообщение. Вложение может быть файлом (например, изображением, аудио или видео) или форматированной карточкой.

Свойство Тип Описание
content Объект Содержимое вложения. Если вложение — это форматированная карточка, укажите для этого свойства объект форматированной карты. Это свойство и свойство contentUrl являются взаимоисключающими.
contentType Строка Тип мультимедиа содержимого во вложении. Для файлов мультимедиа задайте этому свойству значение известных типов мультимедиа, например image/png, audio/wav или video/mp4. Для форматированных карточек задайте этому свойству один из следующих типов, определяемых поставщиком:
  • application/vnd.microsoft.card.adaptive. Форматированная карточка, которая может содержать любое сочетание текста, речи, изображений, кнопок и полей ввода. Для свойства content укажите объект AdaptiveCard.
  • application/vnd.microsoft.card.animation. Форматированная карточка для воспроизведения анимации. Для свойства content укажите объект AnimationCard.
  • application/vnd.microsoft.card.audio. Форматированная карточка для воспроизведения аудиофайлов. Для свойства content укажите объект AudioCard.
  • application/vnd.microsoft.card.hero. Карта для имиджевого баннера. Для свойства content укажите объект HeroCard.
  • application/vnd.microsoft. карта.receipt: карта квитанции. Для свойства content укажите объект ReceiptCard.
  • application/vnd.microsoft. карта.signin: карта входа пользователя. Для свойства content укажите объект SignInCard.
  • application/vnd.microsoft.card.thumbnail. Карта эскиза. Для свойства content укажите объект ThumbnailCard.
  • application/vnd.microsoft.card.video. Форматированная карточка для воспроизведения видео. Для свойства content укажите объект VideoCard.
contentUrl Строка URL-адрес для содержимого вложения. Например, если вложение — это изображение, укажите для свойства contentUrl URL-адрес, представляющий расположение этого изображения. Поддерживаются протоколы HTTP, HTTPS, файловый протокол и протокол передачи данных.
имя Строка Имя вложения.
thumbnailUrl Строка URL-адрес эскиза, который канал может использовать, если поддерживает использование альтернативных, меньших форм свойств content или contentUrl. Например, если задать свойству contentType значение application/word, а свойству contentUrl — расположение документа Word, можно включить эскиз изображения, представляющего документ. Канал будет отображать эскиз изображения вместо документа. При щелчке изображения канал откроет документ.

Вернуться к таблице "Схема"

Объект AttachmentData

Описывает данные вложения.

Свойство Тип Description
имя Строка Имя вложения.
originalBase64 Строка Содержимое вложения.
thumbnailBase64 Строка Содержимое эскиза вложения.
type Строка Тип содержимого вложения.

Вернуться к таблице "Схема"

Объект AttachmentInfo

Метаданные для вложения.

Свойство Тип Description
имя Строка Имя вложения.
type Строка Тип содержимого вложения.
представления; AttachmentView[] Массив объектов AttachmentView, представляющий доступные представления для вложения.

Вернуться к таблице "Схема"

Объект AttachmentView

Определяет объект, представляющий доступное представление для вложения.

Свойство Тип Описание
size Число Размер файла.
viewId Строка Идентификатор представления.

Вернуться к таблице "Схема"

Объект AudioCard

Определяет карту, которая может воспроизводить звуковые файлы.

Свойство Тип Описание
aspect Строка Пропорции эскиза, указанные в свойстве image. Допустимые значения: 16:9 и 4:3.
autoloop Логическое значение Флаг, указывающий, следует ли повторять воспроизведение списка аудиофайлов при завершении последнего. Для автоматического повторного воспроизведения аудиофайлов присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
autostart Логическое значение Флаг, указывающий, следует ли автоматически воспроизводить звук при отображении карты. Для автоматического воспроизведения звука присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
duration Строка Длина мультимедийных данных в формате длительности ISO 8601.
Изображение ThumbnailUrl Объект ThumbnailUrl, указывающий изображение, отображаемое на карте.
media MediaUrl[] Массив объектов MediaUrl. Если это поле содержит более одного URL-адреса, это значит, что каждый URL-адрес представляет альтернативный формат одного содержимого.
shareable Логическое значение Флаг, указывающий, может ли быть предоставлен общий доступ к аудиофайлам. Если аудиофайлы могут находиться в общем доступе, присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
subtitle Строка Подзаголовок для отображения под заголовком карты.
text Строка Описание или запрос для отображения под заголовком или подзаголовком карты.
title Строка Заголовок карты.
значение Объект Дополнительный параметр для этой карты.

Вернуться к таблице "Схема"

Объект CardAction

Определяет доступное для щелчка действие с кнопкой.

Свойство Тип Описание
channelData Строка Относящиеся к каналу данные, связанные с этим действием.
displayText Строка Текст, отображаемый в канале чата при нажатии кнопки.
Изображение Строка URL-адрес изображения, который появится на кнопке рядом с текстовой меткой.
text Строка Текст для действия.
title Строка Текстовое описание, отображаемое на кнопке.
type Строка Тип действия для выполнения. Список допустимых значений см. в статье Добавление форматированных карточек как вложения к сообщениям.
значение Объект Дополнительный параметр для этого действия. Поведение этого свойства будет меняться в зависимости от типа действия. Дополнительные сведения см. в статье Добавление форматированных карточек как вложения к сообщениям.

Вернуться к таблице "Схема"

Объект CardImage

Определяет изображение для отображения на карте.

Свойство Тип Описание
alt Строка Описание изображения. Следует включить описание для поддержки специальных возможностей.
tap CardAction Объект CardAction, указывающий действие, выполняемое при нажатии или щелчке изображения.
url Строка URL-адрес источника изображения или двоичный код base64 изображения (например, data:image/png;base64,iVBORw0KGgo...).

Вернуться к таблице "Схема"

Объект ChannelAccount

Определяет бота или учетную запись пользователя на канале.

Свойство Тип Описание
aadObjectId Строка Идентификатор объекта этой учетной записи в идентификаторе Microsoft Entra.
id Строка Уникальный идентификатор пользователя или бота в этом канале.
имя Строка Понятное имя бота или пользователя.
role Строка Роль сущности, которая находится за учетной записью. user или bot.

Вернуться к таблице "Схема"

Объект ConversationAccount

Определяет общение на канале.

Свойство Тип Описание
aadObjectId Строка Идентификатор объекта этой учетной записи в идентификаторе Microsoft Entra.
conversationType Строка Указывает тип беседы в каналах, которые различают типы бесед (например, группу или личную).
id Строка Идентификатор, определяющий общение. Идентификатор является уникальным для каждого канала. Если в канале начинается диалог, канал определяет этот идентификатор. В противном случае бот присваивает этому свойству идентификатор, который получает в ответе при запуске диалога (см. инструкции по началу диалога).
isGroup Логическое значение Флаг, указывающий, содержит ли общение более двух участников во время создания действия. Задайте значение true, если это групповой общение, в противном случае — false. Значение по умолчанию — false.
имя Строка Отображаемое имя, которое может использоваться для идентификации общения.
role Строка Роль сущности, которая находится за учетной записью. user или bot.
tenantId Строка Идентификатор клиента диалога.

Вернуться к таблице "Схема"

Объект ConversationMembers

Определяет участников беседы.

Свойство Тип Описание
id Строка Идентификатор разговора.
members ChannelAccount[] Список участников в этом диалоге.

Вернуться к таблице "Схема"

Объект ConversationParameters

Определяет параметры для создания диалога.

Свойство Тип Описание
activity Деятельность Первоначальное сообщение для отправки в беседу при его создании.
bot ChannelAccount Сведения об учетной записи канала, требуемые для отправки сообщения в бот.
channelData Объект Связанные с каналом полезные данные для создания диалога.
isGroup Логическое значение Указывает, является ли диалог групповым.
members ChannelAccount[] Сведения об учетной записи канала, требуемые для отправки сообщения каждому пользователю.
tenantId Строка Идентификатор клиента, в котором создается диалог.
topicName Строка Тема диалога. Это свойство используется только в том случае, если канал его поддерживает.

Вернуться к таблице "Схема"

Объект ConversationReference

Определяет конкретный момент в общении.

Свойство Тип Описание
activityId Строка Идентификатор, однозначно определяющий действие, на которое ссылается данный объект.
bot ChannelAccount Объект ChannelAccount, идентифицирующий бота в общении, на который ссылается данный объект.
channelId Строка Идентификатор, однозначно определяющий канал в общении, на которое ссылается данный объект.
беседа ConversationAccount Объект ConversationAccount, определяющий общение, на которое ссылается данный объект.
serviceUrl Строка URL-адрес, указывающий конечную точку службы канала в общении, на которое ссылается данный объект.
user ChannelAccount Объект ChannelAccount, идентифицирующий пользователя в общении, на которое ссылается данный объект.

Вернуться к таблице "Схема"

Объект ConversationResourceResponse

Определяет ответ на операцию Создать диалог.

Свойство Тип Описание
activityId Строка Идентификатор действия (при его отправке).
id Строка Идентификатор ресурса.
serviceUrl Строка Конечная точка службы, в которой могут выполняться операции, связанные с диалогом.

Вернуться к таблице "Схема"

Объект ConversationsResult

Определяет результат операции Получить диалоги.

Свойство Тип Описание
Беседы ConversationMembers[] Участники каждого диалога.
continuationToken Строка Токен продолжения, который может использоваться в дальнейших вызовах операции Получить диалоги.

Вернуться к таблице "Схема"

Объект Entity

Объект метаданных, относящийся к действию.

Свойство Тип Описание
type Строка Тип этой сущности (RFC 3987 IRI).

Вернуться к таблице "Схема"

Объект ошибки

Объект, представляющий сведения об ошибке.

Свойство Тип Описание
code Строка Код ошибки.
innerHttpError InnerHttpError Объект, представляющий внутреннюю ошибку HTTP.
message Строка Описание ошибки.

Вернуться к таблице "Схема"

Объект ErrorResponse

Определяет ответ API HTTP.

Свойство Тип Описание
error Ошибка Объект Error, содержащий сведения об ошибке.

Вернуться к таблице "Схема"

Объект Fact

Определяет пару "ключ — значение", содержащую факт.

Свойство Тип Описание
key Строка Имя факта. Например, Check-in. Ключ используется как метка при отображении значения факта.
значение Строка Значение факта. Например, 10 октября 2016 г.

Вернуться к таблице "Схема"

Объект GeoCoordinates

Определяет географическое расположение с помощью координат всемирной геодезической системы (WSG84).

Свойство Тип Описание
elevation Число Высота расположения.
latitude Число Широта расположения.
longitude Число Долгота расположения.
имя Строка Название расположения.
type Строка Тип этого объекта . Всегда имеет значение GeoCoordinates.

Вернуться к таблице "Схема"

Объект HeroCard

Определяет карту с большим изображением, заголовком, текстом и командной кнопкой.

Свойство Тип Описание
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
images CardImage[] Массив объектов CardImage, указывающий изображение для отображения на карте. Карта для имиджевого баннера содержит только одно изображение.
subtitle Строка Подзаголовок для отображения под заголовком карты.
tap CardAction Объект CardAction, указывающий действие, выполняемое при нажатии или щелчке карты. Это может быть то же действие, которое присвоено одной из кнопок, или другое действие.
text Строка Описание или запрос для отображения под заголовком или подзаголовком карты.
title Строка Заголовок карты.

Вернуться к таблице "Схема"

Объект InnerHttpError

Объект, представляющий внутреннюю ошибку HTTP.

Свойство Тип Описание
statusCode Число Код состояния HTTP из невыполненного запроса.
текст Объект Текст из невыполненного запроса.

Вернуться к таблице "Схема"

Объект MediaEventValue

Дополнительный параметр для событий мультимедиа.

Свойство Тип Описание
cardValue Объект Параметр обратного вызова, указанный в поле value карты мультимедиа, являющийся источником этого события.

Вернуться к таблице "Схема"

Объект MediaUrl

Определяет URL-адрес источника файла мультимедиа.

Свойство Тип Описание
profile Строка Указание, описывающее содержимое мультимедиа.
url Строка URL-адрес источника файла мультимедиа.

Вернуться к таблице "Схема"

Объект Mention

Определяет пользователя или бота, упомянутого в общении.

Свойство Тип Описание
mentioned ChannelAccount Объект ChannelAccount, указывающий пользователя или бота, который ранее был упомянут. Некоторые каналы, такие как Slack, назначают имена для беседы, поэтому возможно, что упоминание имя бота (в свойстве получателя сообщения) может отличаться от дескриптора, указанного при регистрации бота. Тем не менее идентификаторы учетных записей как для нового, так и для указанного имени бота будут совпадать.
text Строка Пользователь или бот, упомянутый в общении. Например, если сообщение "@ColorBot выбрать новый цвет", это свойство будет иметь значение @ColorBot. Не все каналы устанавливают это свойство.
type Строка Тип этого объекта. Всегда имеет значение Mention.

Вернуться к таблице "Схема"

Объект MessageReaction

Определяет ответную реакцию на сообщение.

Свойство Тип Описание
type Строка Тип реакции. like или plusOne.

Вернуться к таблице "Схема"

Объект PagedMembersResult

Страница участников, возвращаемая операцией получения участников диалога по страницам.

Свойство Тип Описание
continuationToken Строка Маркер продолжения, который можно использовать в дальнейших вызовах операции получения участников диалога по страницам.
members ChannelAccount[] Массив участников диалога.

Вернуться к таблице "Схема"

Объект Place

Определяет место, упомянутое в общении.

Свойство Тип Описание
address Объект Адрес места. Это свойство может иметь тип string или быть сложным объектом типа PostalAddress.
geo GeoCoordinates Объект GeoCoordinates, указывающий координаты географического расположения.
hasMap Объект Карта места. Это свойство может иметь тип string (URL-адрес) или быть сложным объектом типа Map.
имя Строка Название места.
type Строка Тип этого объекта. Всегда имеет значение Place.

Вернуться к таблице "Схема"

Объект ReceiptCard

Определяет карту, которая содержит квитанцию о покупке.

Свойство Тип Описание
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
facts Fact[] Массив объектов Fact, указывающий данные о покупке. Например, в списке фактов квитанции о пребывании в гостинице могут быть дата заселения и дата выселения. Канал определяет количество фактов, которые можно указать.
items ReceiptItem[] Массив объектов ReceiptItem, указывающий приобретенные единицы.
tap CardAction Объект CardAction, указывающий действие, выполняемое при нажатии или щелчке карты. Это может быть то же действие, которое присвоено одной из кнопок, или другое действие.
tax Строка Строка в валютном формате, указывающая величину налога, накладываемого на покупку.
title Строка Заголовок, отображаемый в верхней части уведомления.
итог Строка Строка в формате валюты, указывающая общую стоимость покупки, включая все соответствующие налоги.
vat Строка Строка в формате валюты, которая определяет величину налога на добавленную стоимость (НДС) со стоимости покупки.

Вернуться к таблице "Схема"

Объект ReceiptItem

Определяет элемент строки в квитанции.

Свойство Тип Описание
Изображение CardImage Объект CardImage, указывающий эскиз изображения для отображения рядом с элементом строки.
price Строка Строка в формате валюты, указывающая общую стоимость всех приобретенных единиц.
quantity Строка Числовая строка, указывающая количество приобретенных единиц.
subtitle Строка Подзаголовок, отображаемый под заголовком элемента строки.
tap CardAction Объект CardAction, указывающий действие, выполняемое при нажатии или щелчке элемента строки.
text Строка Описание элемента строки.
title Строка Название элемента строки.

Вернуться к таблице "Схема"

Объект ResourceResponse

Определяет ответ, содержащий идентификатор ресурса.

Свойство Тип Описание
id Строка Идентификатор, уникально идентифицирующий ресурс.

Вернуться к таблице "Схема"

Объект SemanticAction

Определяет ссылку на программное действие.

Свойство Тип Описание
entities Объект Объект, где значение каждого свойства является объектом Entity.
id Строка Идентификатор этого действия.
state Строка Состояние этого действия. Допустимые значения: start, continue, done.

Вернуться к таблице "Схема"

Объект SignInCard

Определяет карту, которая позволяет пользователю выполнить вход в службу.

Свойство Тип Описание
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю войти в службу. Канал определяет количество кнопок, которые можно указать.
text Строка Описание или запрос на включение в карта входа.

Вернуться к таблице "Схема"

Объект SuggestedActions

Определяет варианты действий, из которых пользователь может выбирать.

Свойство Тип Описание
actions CardAction[] Массив объектов CardAction, определяющий предлагаемые действия.
to String[] Массив строк, содержащий идентификаторы получателей, которым должны отображаться предлагаемые действия.

Вернуться к таблице "Схема"

Объект TextHighlight

Ссылается на подстроку содержимого в другом поле.

Свойство Тип Описание
occurrence Число Вхождение текстового поля в тексте, на который указывает ссылка (при наличии повторов).
text Строка Определяет фрагмент текста для выделения.

Вернуться к таблице "Схема"

Объект ThumbnailCard

Определяет карту с эскизом изображения, заголовком, текстом и командной кнопкой.

Свойство Тип Описание
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
images CardImage[] Массив объектов CardImage, указывающий эскизы изображений для отображения на карте. Канал определяет количество эскизов изображений, которые можно указать.
subtitle Строка Подзаголовок для отображения под заголовком карты.
tap CardAction Объект CardAction, указывающий действие, выполняемое при нажатии или щелчке карты. Это может быть то же действие, которое присвоено одной из кнопок, или другое действие.
text Строка Описание или запрос для отображения под заголовком или подзаголовком карты.
title Строка Заголовок карты.

Вернуться к таблице "Схема"

Объект ThumbnailUrl

Определяет URL-адрес источника изображения.

Свойство Тип Описание
alt Строка Описание изображения. Следует включить описание для поддержки специальных возможностей.
url Строка URL-адрес источника изображения или двоичный код base64 изображения (например, data:image/png;base64,iVBORw0KGgo...).

Вернуться к таблице "Схема"

Объект Transcript

Коллекция действий, отправляемых с помощью операции Отправить журнал бесед.

Свойство Тип Описание
действия array Массив объектов Activity. Необходимо, чтобы у них был уникальный идентификатор и метка времени.

Вернуться к таблице "Схема"

Объект VideoCard

Определяет карту, которая может воспроизводить видео.

Свойство Тип Описание
aspect Строка Пропорции видео. Например, 16:9 или 4:3.
autoloop Логическое значение Флаг, указывающий, следует ли повторять воспроизведение списка видео при завершении последнего. Для автоматического повторного воспроизведения видео присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
autostart Логическое значение Флаг, указывающий, следует ли автоматически воспроизводить видео при отображении карты. Для автоматического воспроизведения видео присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
buttons CardAction[] Массив объектов CardAction, позволяющий пользователю выполнять одно или несколько действий. Канал определяет количество кнопок, которые можно указать.
duration Строка Длина мультимедийных данных в формате длительности ISO 8601.
Изображение ThumbnailUrl Объект ThumbnailUrl, указывающий изображение, отображаемое на карте.
media MediaUrl[] Массив MediaUrl. Если это поле содержит более одного URL-адреса, это значит, что каждый URL-адрес представляет альтернативный формат одного содержимого.
shareable Логическое значение Флаг, указывающий, предоставлен ли видео общий доступ. Если видео могут находиться в общем доступе, присвойте этому свойству значение true, в противном случае — false. Значение по умолчанию — true
subtitle Строка Подзаголовок для отображения под заголовком карты.
text Строка Описание или запрос для отображения под заголовком или подзаголовком карты.
title Строка Заголовок карты.
значение Объект Дополнительный параметр для этой карты.

Вернуться к таблице "Схема"