Bot Framework Connector 服务的 API 参考

在 Bot Framework 中，Bot Connector 服务使机器人能够与 Bot Framework 门户中配置的通道中的用户交换消息。 该服务通过 HTTPS 使用行业标准 REST 和 JSON。

基本 URI

当用户向机器人发送消息时，传入请求包含一个具有 serviceUrl 属性的 Activity 对象，该属性指定机器人应将其响应发送到的终结点。 若要访问 Bot Connector 服务，请使用 serviceUrl 值作为 API 请求的基本 URI。

如果还没有通道的服务 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

有关如何获取机器人访问令牌的详细信息，请参阅验证机器人向 Bot Connector 服务发出的请求。

响应标头

除了标准 HTTP 响应标头，每个响应还包含一个 X-Correlating-OperationId 标头。 此标头的值是与 Bot Framework 日志条目（其中包含有关请求的详细信息）对应的 ID。 当收到错误响应时，都应捕获此标头的值。 如果无法独立解决问题，请在报告问题时将此值包含在向支持团队提供的信息中。

HTTP 状态代码

随每个响应返回的 HTTP 状态代码指示相应请求的结果。

HTTP 状态代码	含义
200	请求成功。
201	请求成功。
202	已接受请求，正在处理。
204	请求成功，但未返回任何内容。
400	请求格式不正确或者其他方面不正确。
401	机器人尚未进行身份验证。
403	机器人无权执行请求的操作。
404	找不到请求的资源。
405	通道不支持请求的操作。
500	发生了内部服务器错误。
503	该服务暂时不可用。

错误

指定 4xx 范围或 5xx 范围内的 HTTP 状态代码的任何响应都将在响应正文中包含 ErrorResponse 对象，该对象提供错误相关信息。 如果收到 4xx 范围内的错误响应，请检查 ErrorResponse 对象以确定错误原因，并在重新提交请求之前解决问题。

聊天操作

以下操作可用于创建聊天、发送消息（活动）和管理聊天内容。

操作	说明
创建聊天	创建新的聊天。
Delete 活动	删除现有活动。
删除对话成员	从对话中删除成员。
获取活动成员	获取指定聊天中指定活动的成员。
获取对话成员	获取有关聊天成员的详细信息。
获取对话成员	获取指定聊天的成员。
获取对话分页成员	获取指定聊天的成员，一次一页。
获取对话	获取机器人参与的对话列表。
回复活动	将活动（消息）发送到指定聊天，作为对指定活动的回复。
发送对话历史记录	将过去活动的脚本上传到对话中。
发送到对话	将活动（消息）发送到指定聊天的末尾。
更新活动	更新现有活动。
将附件上传到通道	将附件直接上传到通道的 blob 存储中。

创建对话

创建新的聊天。

POST /v3/conversations

内容	说明
请求正文	ConversationParameters 对象
返回	ConversationResourceResponse 对象

Delete 活动

某些通道允许删除现有活动。 如果成功，此操作会从指定聊天中删除指定活动。

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

内容	说明
请求正文	不适用
返回	指示操作结果的 HTTP 状态代码。 响应正文中未指定任何内容。

删除对话成员

从对话中删除成员。 如果该成员是对话中最后一个成员，则删除对话。

DELETE /v3/conversations/{conversationId}/members/{memberId}

内容	说明
请求正文	不适用
返回	指示操作结果的 HTTP 状态代码。 响应正文中未指定任何内容。

获取活动成员

获取指定聊天中指定活动的成员。

GET /v3/conversations/{conversationId}/activities/{activityId}/members

内容	说明
请求正文	不适用
返回	ChannelAccount 对象数组

获取对话

获取机器人参与的对话列表。

GET /v3/conversations?continuationToken={continuationToken}

内容	说明
请求正文	不适用
返回	ConversationsResult 对象

获取对话成员

获取有关特定聊天的特定成员的详细信息。

GET /v3/conversations/{conversationId}/members/{memberId}

内容	说明
请求正文	不适用
返回	成员的 ChannelAccount 对象。

获取对话成员

获取指定聊天的成员。

GET /v3/conversations/{conversationId}/members

内容	说明
请求正文	不适用
返回	聊天成员的 ChannelAccount 对象的数组。

获取对话分页成员

获取指定聊天的成员，一次一页。

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}

内容	说明
请求正文	不适用
返回	一个 PagedMembersResult 对象

回复活动

将活动（消息）发送到指定聊天，作为对指定活动的回复。 如果通道支持，将添加该活动作为对另一个活动的回复。 如果通道不支持嵌套回复，则此操作的行为类似于发送到对话。

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

内容	说明
请求正文	Activity 对象
返回	ResourceResponse 对象

发送对话历史记录

将过去活动的脚本上传到对话中，使客户端可以呈现它们。

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

内容	说明
请求正文	脚本对象。
返回	ResourceResponse 对象。

发送到对话

将活动（消息）发送到指定的聊天。 活动将根据通道的时间戳或语义追加到聊天的末尾。 若要回复聊天中的特定消息，请改用回复活动。

POST /v3/conversations/{conversationId}/activities

内容	说明
请求正文	Activity 对象
返回	ResourceResponse 对象

更新活动

某些通道允许编辑现有活动，以反映机器人聊天的新状态。 例如，可以在用户单击某个按钮后从聊天消息中删除按钮。 如果成功，此操作会更新指定聊天中的指定活动。

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

内容	说明
请求正文	Activity 对象
返回	ResourceResponse 对象

将附件上传到通道

将指定聊天的附件直接上传到通道的 blob 存储中。 这样就可以将数据存储在兼容的存储中。

POST /v3/conversations/{conversationId}/attachments

内容	说明
请求正文	一个 AttachmentData 对象。
返回	ResourceResponse 对象。 id 属性指定可与获取附件信息操作和获取附件操作一起使用的附件 ID。

附件操作

以下操作可用于检索附件相关信息以及文件本身的二进制数据。

Operation	说明
获取附件信息	获取有关指定附件的信息，包括文件名、文件类型和可用视图（例如，原始视图或缩略图）。
获取附件	获取指定附件的指定视图作为二进制内容。

获取附件信息

获取有关指定附件的信息，包括文件名、类型和可用视图（例如，原始视图或缩略图）。

GET /v3/attachments/{attachmentId}

内容	说明
请求正文	不适用
返回	AttachmentInfo 对象

获取附件

获取指定附件的指定视图作为二进制内容。

GET /v3/attachments/{attachmentId}/views/{viewId}

内容	说明
请求正文	不适用
返回	二进制内容，表示指定附件的指定视图

状态操作（已弃用）

Microsoft Bot Framework State 服务已于 2018 年 3 月 30 日停用。 以前，在 Azure AI 机器人服务或 Bot Builder SDK 上构建的机器人可以默认连接到此服务。此服务由 Microsoft 托管，用于存储机器人状态数据。 机器人需要更新才能使用其自己的状态存储。

Operation	说明
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 架构定义可由机器人用来与用户通信的对象及其属性。

对象	说明
Activity 对象	定义在机器人与用户之间交换的消息。
AnimationCard 对象	定义可播放动态 GIF 或短视频的卡。
Attachment 对象	定义要包含在消息中的其他信息。 附件可以是媒体文件（例如，音频、视频、图像、文件）或资讯卡。
AttachmentData 对象	描述附件数据。
AttachmentInfo 对象	描述附件。
AttachmentView 对象	定义一个表示附件可用视图的对象。
AudioCard 对象	定义可播放音频文件的卡。
CardAction 对象	定义要执行的操作。
CardImage 对象	定义要在卡上显示的图像。
ChannelAccount 对象	定义通道上的机器人或用户帐户。
ConversationAccount 对象	定义通道中的聊天。
ConversationMembers 对象	定义对话的成员。
ConversationParameters 对象	定义用于创建新聊天的参数
ConversationReference 对象	定义聊天中的特定点。
ConversationResourceResponse 对象	定义创建对话的响应。
ConversationsResult 对象	定义调用获取对话的结果。
Entity 对象	定义实体对象。
Error 对象	定义错误。
ErrorResponse 对象	定义 HTTP API 响应。
Fact 对象	定义包含事实的键值对。
Geocoordinates 对象	使用世界测地系统 (WSG84) 坐标定义地理位置。
HeroCard 对象	定义具有大图像、标题、文本和操作按钮的卡。
InnerHttpError 对象	表示内部 HTTP 错误的对象。
MediaEventValue 对象	媒体事件的补充参数。
MediaUrl 对象	定义媒体文件源的 URL。
Mention 对象	定义聊天中提到的用户或机器人。
MessageReaction 对象	定义对消息的回应。
PagedMembersResult 对象	获取聊天分页成员返回的成员页。
Place 对象	定义聊天中提到的位置。
ReceiptCard 对象	定义包含购买收据的卡。
ReceiptItem 对象	定义收据中的订单项。
ResourceResponse 对象	定义资源。
SemanticAction 对象	定义对编程操作的引用。
SignInCard 对象	定义允许用户登录服务的卡。
SuggestedActions 对象	定义用户可以选择的选项。
TextHighlight 对象	引用另一字段中的内容的子字符串。
ThumbnailCard 对象	定义具有缩略图、标题、文本和操作按钮的卡。
ThumbnailUrl 对象	定义图像源的 URL。
脚本对象	使用发送对话历史记录上传的活动集合。
VideoCard 对象	定义可播放视频的卡。

Activity 对象

定义在机器人与用户之间交换的消息。

properties	类型​​	说明
action	字符串	要应用或已应用的操作。 使用 type 属性确定操作的上下文。 例如，当 type 为 contactRelationUpdate 时，如果用户将机器人添加到其联系人列表中，则 action 属性的值为 add，如果他们从联系人列表中删除机器人，则该属性的值为 remove。
attachmentLayout	字符串	消息中包含的资讯卡附件的布局。 下列值之一：carousel、list。 有关资讯卡附件的详细信息，请参阅向消息添加资讯卡附件。
attachments	Attachment[]	一个 Attachment 对象数组，用于定义要包含在消息中的其他信息。 每个附件可以是一个文件（例如音频、视频、图像）或资讯卡。
callerId	字符串	一个字符串，其中包含用于标识机器人调用方的 IRI。 此字段不旨在通过网络传输，而是由机器人和客户端根据断言调用方标识的、可通过密码方式验证的数据（例如令牌）填充。
channelData	Object	一个包含特定于通道的内容的对象。 某些通道提供的功能需要其他信息，而这些信息不能使用附件架构来表示。 对于此类情况，请按通道文档中的定义将此属性设置为特定于通道的内容。 有关详细信息，请参阅实现特定于通道的功能。
channelId	字符串	用于唯一标识通道的 ID。 由通道设置。
code	字符串	指示聊天结束原因的代码。
对话	ConversationAccount	一个 ConversationAccount 对象，用于定义活动所属的聊天。
deliveryMode	字符串	一个传递提示，向接收方指示活动的备用传递路径。 值为下列其中一项：normal、notification。
entities	对象[]	一个对象数组，表示消息中提到的实体。 此数组中的对象可以是任何 Schema.org 对象。 例如，此数组可能包含 Mention 对象，用于标识聊天中提到的某人，以及 Place 对象，用于标识聊天中提到的某个位置。
expiration	字符串	应将活动视为“过期”且不将其发送给接收方的时间。
from	ChannelAccount	一个 ChannelAccount 对象，用于指定消息的发送者。
historyDisclosed	布尔	一个标志，指示是否公开历史记录。 默认值为“false” 。
id	字符串	一个 ID，用于唯一标识通道上的活动。
importance	字符串	定义活动的重要性。 值为下列其中一项：low、normal、high。
inputHint	字符串	一个值，指示在将消息传送到客户端后，机器人是接受、预期还是忽略用户输入。 下列值之一：acceptingInput、expectingInput、ignoringInput。
label	字符串	活动的描述性标签。
listenFor	String[]	语音和语言预载系统应侦听的短语和参考列表。
locale	字符串	应该用于在消息中显示文本的语言的区域设置，格式为 <language>-<country>。 通道使用此属性指示用户的语言，以便机器人可以指定该语言的显示字符串。 默认值为 en-US。
localTimestamp	字符串	在本地时区发送消息的日期和时间，以 ISO-8601 格式表示。
localTimezone	字符串	包含消息的本地时区名称（以 IANA 时区数据库格式表示）。 例如 America/Los_Angeles。
membersAdded	ChannelAccount[]	一个 ChannelAccount 对象数组，表示已加入聊天的用户的列表。 仅当活动 type 为“conversationUpdate”且用户已加入聊天时才会显示。
membersRemoved	ChannelAccount[]	一个 ChannelAccount 对象数组，表示已离开聊天的用户的列表。 仅当活动 type 为“conversationUpdate”且用户已离开聊天时才会显示。
name	字符串	要调用的操作的名称或事件的名称。
reactionsAdded	MessageReaction[]	添加到聊天中的回应集合。
reactionsRemoved	MessageReaction[]	从聊天中删除的回应集合。
recipient	ChannelAccount	一个 ChannelAccount 对象，用于指定消息的接收者。
relatesTo	ConversationReference	一个 ConversationReference 对象，用于定义聊天中的特定点。
replyToId	字符串	此消息回复的消息的 ID。 若要回复用户发送的消息，请将此属性设置为用户消息的 ID。 并非所有通道都支持线程回复。 在这些情况下，通道将忽略此属性并使用时间时间排序语义（时间戳）将消息追加到聊天。
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。 有关活动类型的详细信息，请参阅活动概述。
value	Object	开放式值。
valueType	字符串	活动值对象的类型。

返回到架构表

AnimationCard 对象

定义可播放动态 GIF 或短视频的卡。

properties	类型​​	说明
aspect	布尔	缩略图/媒体占位符的纵横比。 允许的值为“16:9”和“4:3”。
autoloop	布尔	一个标志，指示在最后一个动态 GIF 结束后是否重播动态 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	字符串	卡的标题。
value	Object	此卡的补充参数。

返回到架构表

Attachment 对象

定义要包含在消息中的其他信息。 附件可以是文件（例如图像、音频或视频）或资讯卡。

properties	类型​​	描述
content	Object	附件的内容。 如果附件是资讯卡，请将此属性设置为资讯卡对象。 此属性与 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.card.receipt：收据卡。 将 content 属性设置为 ReceiptCard 对象。 application/vnd.microsoft.card.signin：用户登录卡。 将 content 属性设置为 SignInCard 对象。 application/vnd.microsoft.card.thumbnail：缩略图卡。 将 content 属性设置为 ThumbnailCard 对象。 application/vnd.microsoft.card.video：一种播放视频的资讯卡。 将 content 属性设置为 VideoCard 对象。
contentUrl	字符串	附件内容的 URL。 例如，如果附件是图像，则可将 contentUrl 设置为表示图像位置的 URL。 支持的协议为：HTTP、HTTPS、文件和数据。
name	字符串	附件的名称。
thumbnailUrl	字符串	通道可以使用的缩略图的 URL，但前提是它支持使用 content 或 contentUrl 的较小替代形式。 例如，如果将 contentType 设置为 application/word，将 contentUrl 设置为 Word 文档的位置，则可以包含表示文档的缩略图。 通道可以显示缩略图而不是文档。 当用户单击图像时，通道将打开文档。

返回到架构表

AttachmentData 对象

描述附件的数据。

properties	类型​​	说明
name	字符串	附件的名称。
originalBase64	字符串	附件内容。
thumbnailBase64	字符串	附件缩略图的内容。
type	字符串	附件的内容类型。

返回到架构表

AttachmentInfo 对象

附件的元数据。

properties	类型​​	说明
name	字符串	附件的名称。
type	字符串	附件的内容类型。
视图	AttachmentView[]	一个 AttachmentView 对象数组，表示附件的可用视图。

返回到架构表

AttachmentView 对象

定义一个表示附件可用视图的对象。

properties	类型​​	说明
size	Number	文件大小。
viewId	字符串	视图 ID。

返回到架构表

AudioCard 对象

定义可播放音频文件的卡。

properties	类型​​	说明
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	字符串	卡的标题。
value	Object	此卡的补充参数。

返回到架构表

CardAction 对象

使用按钮定义可单击的操作。

properties	类型​​	说明
channelData	字符串	与此操作关联的通道特定数据。
displayText	字符串	单击该按钮时要在聊天源中显示的文本。
图像	字符串	要显示在按钮上的图像 URL，位于文本标签旁边。
text	字符串	操作的文本。
title	字符串	显示在按钮上的文本说明。
type	字符串	要执行的操作类型。 有关有效值的列表，请参阅向消息添加资讯卡附件。
value	Object	操作的补充参数。 此属性的行为因操作 type 而异。 有关详细信息，请参阅向消息添加资讯卡附件。

返回到架构表

CardImage 对象

定义要在卡上显示的图像。

properties	类型​​	说明
alt	字符串	图像描述。 应包含描述以支持可访问性。
tap	CardAction	一个 CardAction 对象，用于指定用户单击或单击图像时要执行的操作。
url	字符串	图像源或图像的 base64 二进制文件的 URL（例如，data:image/png;base64,iVBORw0KGgo...）。

返回到架构表

ChannelAccount 对象

定义通道上的机器人或用户帐户。

properties	类型​​	说明
aadObjectId	字符串	此帐户的对象 ID 在 Microsoft Entra ID 中。
id	字符串	此通道上用户或机器人的唯一 ID。
name	字符串	机器人或用户的易于显示的名称。
role	字符串	帐户后的实体的角色。 user 或 bot。

返回到架构表

ConversationAccount 对象

定义通道中的聊天。

properties	类型​​	说明
aadObjectId	字符串	此帐户的对象 ID 在 Microsoft Entra ID 中。
conversationType	字符串	指示用于区分对话类型（例如组或个人）的通道中的对话类型。
id	字符串	用于标识聊天的 ID。 每个通道的 ID 都是唯一的。 如果通道启动聊天，它将设置此 ID；否则，机器人会将此属性设置为启动聊天时在响应中返回的 ID（请参阅创建聊天）。
isGroup	布尔	一个标志，指示聊天在活动生成时是否包含两个以上的参与者。 如果这是群组聊天，则设置为 true；否则设置为 false。 默认值为 false。
name	字符串	可用于标识聊天的显示名称。
role	字符串	帐户后的实体的角色。 user 或 bot。
tenantId	字符串	此聊天的租户 ID。

返回到架构表

ConversationMembers 对象

定义对话的成员。

properties	类型​​	描述
id	字符串	对话 ID。
members	ChannelAccount[]	此聊天中的成员列表。

返回到架构表

ConversationParameters 对象

定义用于创建新对话的参数。

properties	类型​​	说明
activity	活动	创建对话后发送到对话的初始消息。
bot	ChannelAccount	将消息路由到机器人所需的通道帐户信息。
channelData	Object	特定于通道的有效负载，用于创建聊天。
isGroup	布尔	指示这是否是群组聊天。
members	ChannelAccount[]	将消息路由到每个用户所需的通道帐户信息。
tenantId	字符串	要在其中创建聊天的租户 ID。
topicName	字符串	聊天的主题。 仅在通道支持时才使用此属性。

返回到架构表

ConversationReference 对象

定义聊天中的特定点。

properties	类型​​	说明
activityId	字符串	一个 ID，用于唯一标识此对象引用的活动。
bot	ChannelAccount	一个 ChannelAccount 对象，用于标识此对象引用的聊天中的机器人。
channelId	字符串	一个 ID，用于唯一标识此对象引用的聊天中的通道。
对话	ConversationAccount	一个 ConversationAccount 对象，用于定义此对象引用的聊天。
serviceUrl	字符串	一个 URL，用于指定此对象引用的聊天中的通道服务终结点。
user	ChannelAccount	一个 ChannelAccount 对象，用于标识此对象引用的聊天中的用户。

返回到架构表

ConversationResourceResponse 对象

定义创建对话的响应。

properties	类型​​	说明
activityId	字符串	活动的 ID（如果已发送）。
id	字符串	资源的 ID。
serviceUrl	字符串	服务终结点，可以在其中执行有关聊天的操作。

返回到架构表

ConversationsResult 对象

定义调用获取对话的结果。

properties	类型​​	说明
聊天	ConversationMembers[]	每个聊天中的成员。
continuationToken	字符串	对获取会话的后续调用中使用的继续标记。

返回到架构表

Entity 对象

与活动相关的元数据对象。

properties	类型​​	说明
type	字符串	此实体的类型 (RFC 3987 IRI)。

返回到架构表

错误对象

表示错误信息的对象。

properties	类型​​	说明
code	字符串	错误代码。
innerHttpError	InnerHttpError	表示内部 HTTP 错误的对象。
message	字符串	对错误的说明。

返回到架构表

ErrorResponse 对象

定义 HTTP API 响应。

properties	类型​​	说明
error	错误	一个包含错误相关信息的 Error 对象。

返回到架构表

Fact 对象

定义包含事实的键值对。

properties	类型​​	描述
键	字符串	事实的名称。 例如，Check-in。 在显示事实值时，该键用作标签。
value	字符串	事实的值。 例如，10 October 2016。

返回到架构表

GeoCoordinates 对象

使用世界测地系统 (WSG84) 坐标定义地理位置。

properties	类型​​	说明
elevation	Number	位置的海拔高度。
latitude	Number	位置的纬度。
longitude	Number	位置的经度。
name	字符串	位置的名称。
type	字符串	此对象的类型。 始终设置为 GeoCoordinates。

返回到架构表

HeroCard 对象

定义具有大图像、标题、文本和操作按钮的卡。

properties	类型​​	说明
buttons	CardAction[]	一个 CardAction 对象数组，允许用户执行一项或多项操作。 通道决定了可指定的按钮数。
images	CardImage[]	一个 CardImage 对象数组，用于指定要在卡上显示的图像。 英雄卡仅包含一个图像。
subtitle	字符串	要在卡标题下显示的副标题。
tap	CardAction	一个 CardAction 对象，用于指定用户单击或单击卡时要执行的操作。 它可以是与其中一个按钮相同的操作，也可以是不同的操作。
text	字符串	要在卡的标题或副标题下显示的描述或提示。
title	字符串	卡的标题。

返回到架构表

InnerHttpError 对象

表示内部 HTTP 错误的对象。

properties	类型​​	说明
statusCode	Number	来自失败请求的 HTTP 状态代码。
body	Object	来自失败请求的正文。

返回到架构表

MediaEventValue 对象

媒体事件的补充参数。

properties	类型​​	说明
cardValue	Object	在发出此事件的媒体卡的 value 字段中指定的回调参数。

返回到架构表

MediaUrl 对象

定义媒体文件源的 URL。

properties	类型​​	说明
profile	字符串	用于描述媒体内容的提示。
url	字符串	媒体文件源的 URL。

返回到架构表

Mention 对象

定义聊天中提到的用户或机器人。

properties	类型​​	说明
mentioned	ChannelAccount	一个 ChannelAccount 对象，用于指定所提到的用户或机器人。 某些通道（如 Slack）按对话分配名称，因此，所提到的机器人名称（在消息的 recipient 属性中）可能与你在注册机器人时指定的句柄不同。 但是，两者的帐户 ID 相同。
text	字符串	聊天中提到的用户或机器人。 例如，如果消息为“@ColorBot pick me a new color”，则此属性将设置为 @ColorBot。 并非所有通道都设置此属性。
type	字符串	此对象的类型。 始终设置为 Mention。

返回到架构表

MessageReaction 对象

定义对消息的回应。

properties	类型​​	说明
type	字符串	回应的类型。 like 或 plusOne。

返回到架构表

PagedMembersResult 对象

获取聊天分页成员返回的成员页。

properties	类型​​	说明
continuationToken	字符串	在获取对话分页成员的后续调用中使用的继续标记。
members	ChannelAccount[]	聊天成员的数组。

返回到架构表

Place 对象

定义聊天中提到的位置。

properties	类型​​	说明
address	Object	某个位置的地址。 此属性可以是一个字符串，或者 PostalAddress 类型的复杂对象。
geo	GeoCoordinates	一个 GeoCoordinates 对象，用于指定该位置的地理坐标。
hasMap	Object	该位置的地图。 此属性可以是一个字符串 (URL)，或 Map 类型的复杂对象。
name	字符串	该位置的名称。
type	字符串	此对象的类型。 始终设置为 Place。

返回到架构表

ReceiptCard 对象

定义包含购买收据的卡。

properties	类型​​	说明
buttons	CardAction[]	一个 CardAction 对象数组，允许用户执行一项或多项操作。 通道决定了可指定的按钮数。
facts	Fact[]	一个 Fact 对象数组，用于指定有关购买的信息。 例如，酒店住宿收据的事实列表可能包括登记入住日期和退房日期。 通道决定了可指定的事实数量。
items	ReceiptItem[]	一个 ReceiptItem 对象数组，用于指定已购买的商品
tap	CardAction	一个 CardAction 对象，用于指定用户单击或单击卡时要执行的操作。 它可以是与其中一个按钮相同的操作，也可以是不同的操作。
tax	字符串	一个货币格式的字符串，用于指定应用于所购商品的税额。
title	字符串	显示在收据顶部的标题。
total	字符串	一个货币格式的字符串，用于指定总购买价格，包括所有适用的税费。
vat	字符串	一个货币格式的字符串，用于指定应用于购买价格的增值税 (VAT) 金额。

返回到架构表

ReceiptItem 对象

定义收据中的订单项。

properties	类型​​	描述
图像	CardImage	一个 CardImage 对象，用于指定要在订单项旁边显示的缩略图。
price	字符串	一个货币格式的字符串，用于指定所有已购单位的总价。
quantity	字符串	一个数字字符串，用于指定已购单位的数量。
subtitle	字符串	要在行项标题下显示的副标题。
tap	CardAction	一个 CardAction 对象，用于指定用户单击或单击订单项时要执行的操作。
text	字符串	订单项描述。
title	字符串	订单项的标题。

返回到架构表

ResourceResponse 对象

定义包含资源 ID 的响应。

properties	类型​​	描述
id	字符串	用于唯一标识资源的 ID。

返回到架构表

SemanticAction 对象

定义对编程操作的引用。

properties	类型​​	说明
entities	Object	一个对象，其中每个属性的值是一个 Entity 对象。
id	字符串	此操作的 ID。
State	字符串	此操作的状态。 允许的值：start、continue、done。

返回到架构表

SignInCard 对象

定义允许用户登录服务的卡。

properties	类型​​	说明
buttons	CardAction[]	一个 CardAction 对象数组，允许用户登录到服务。 通道决定了可指定的按钮数。
text	字符串	要在登录卡上包含的描述或提示。

返回到架构表

SuggestedActions 对象

定义用户可以选择的选项。

properties	类型​​	说明
actions	CardAction[]	一个 CardAction 对象数组，用于定义建议的操作。
to	String[]	一个字符串数组，包含应向其显示建议操作的接收者的 ID。

返回到架构表

TextHighlight 对象

引用另一字段中的内容的子字符串。

properties	类型​​	说明
occurrence	Number	引用的文本中文本字段的出现次数（如果有多个）。
text	字符串	定义要突出显示的文本片段。

返回到架构表

ThumbnailCard 对象

定义具有缩略图、标题、文本和操作按钮的卡。

properties	类型​​	说明
buttons	CardAction[]	一个 CardAction 对象数组，允许用户执行一项或多项操作。 通道决定了可指定的按钮数。
images	CardImage[]	一个 CardImage 对象数组，用于指定要在卡上显示的缩略图。 通道决定了可指定的缩略图数量。
subtitle	字符串	要在卡标题下显示的副标题。
tap	CardAction	一个 CardAction 对象，用于指定用户单击或单击卡时要执行的操作。 它可以是与其中一个按钮相同的操作，也可以是不同的操作。
text	字符串	要在卡的标题或副标题下显示的描述或提示。
title	字符串	卡的标题。

返回到架构表

ThumbnailUrl 对象

定义图像源的 URL。

properties	类型​​	说明
alt	字符串	图像描述。 应包含描述以支持可访问性。
url	字符串	图像源或图像的 base64 二进制文件的 URL（例如，data:image/png;base64,iVBORw0KGgo...）。

返回到架构表

脚本对象

使用发送对话历史记录上传的活动集合。

properties	类型​​	说明
activities	array	Activity 对象数组。 它们每个都应该有唯一的 ID 和时间戳。

返回到架构表

VideoCard 对象

定义可播放视频的卡。

properties	类型​​	说明
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	字符串	卡的标题。
value	Object	此卡的补充参数

返回到架构表