Bot Framework 连接器服务的 API 参考

注释

REST API 不等效于 SDK。 提供 REST API 以允许标准 REST 通信，但与 Bot Framework 交互的首选方法是 SDK。

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

基 URI

当用户向机器人发送消息时，传入请求包含一个 Activity 对象，该对象包含一个 serviceUrl 属性，该对象指定机器人应向其发送其响应的终结点。 若要访问 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 状态代码。 通道会生成一些错误。 有关详细信息，可能需要阅读通道的开发人员文档。

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

Errors

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

对话操作

使用这些操作可以创建对话、发送消息（活动）和管理对话的内容。

Important

并非所有通道都支持所有终结点。 但是，所有通道都应支持 对活动终结点的回复 。

例如，仅Direct Line和Web 聊天支持 get conversations 终结点。

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

创建对话

创建新对话。

POST /v3/conversations

Content	Description
请求正文	ConversationParameters 对象
返回	ConversationResourceResponse 对象

删除活动

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

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

Content	Description
请求正文	n/a
返回	指示操作结果的 HTTP 状态代码。 响应正文中未指定任何内容。

删除对话成员

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

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

Content	Description
请求正文	n/a
返回	指示操作结果的 HTTP 状态代码。 响应正文中未指定任何内容。

获取活动成员

获取指定会话中指定活动的成员。

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

Content	Description
请求正文	n/a
返回	ChannelAccount 对象的数组

获取对话

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

GET /v3/conversations?continuationToken={continuationToken}

Content	Description
请求正文	n/a
返回	ConversationsResult 对象

获取对话成员

获取有关特定对话的特定成员的详细信息。

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

Content	Description
请求正文	n/a
返回	成员的 ChannelAccount 对象。

获取对话成员

获取指定会话的成员。

GET /v3/conversations/{conversationId}/members

Content	Description
请求正文	n/a
返回	会话成员的 ChannelAccount 对象的数组。

获取对话分页成员

获取指定对话的成员一次一页。

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

Content	Description
请求正文	n/a
返回	PagedMembersResult 对象

答复活动

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

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

Content	Description
请求正文	活动对象
返回	ResourceResponse 对象

发送对话历史记录

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

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

Content	Description
请求正文	脚本对象。
返回	ResourceResponse 对象。

发送到对话

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

POST /v3/conversations/{conversationId}/activities

Content	Description
请求正文	活动对象
返回	ResourceResponse 对象

更新活动

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

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

Content	Description
请求正文	活动对象
返回	ResourceResponse 对象

将附件上传到频道

将指定会话的附件直接上传到通道的 Blob 存储中。 这样，便可以将数据存储在合规的存储中。

POST /v3/conversations/{conversationId}/attachments

Content	Description
请求正文	AttachmentData 对象。
返回	ResourceResponse 对象。 ID 属性指定可与“获取附件信息”操作和“获取附件”操作一起使用的附件 ID。

附件操作

使用这些操作检索有关附件的信息以及文件本身的二进制数据。

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

获取附件信息

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

GET /v3/attachments/{attachmentId}

Content	Description
请求正文	n/a
返回	AttachmentInfo 对象

获取附件

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

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

Content	Description
请求正文	n/a
返回	表示指定附件的指定视图的二进制内容

状态操作（已弃用）

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

Operation	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	删除以前为用户存储的状态数据。

Schema

Bot Framework 架构定义机器人可用于与用户通信的对象及其属性。

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

活动对象

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

财产	类型	Description
action	String	要应用或已应用的操作。 使用 type 属性确定操作的上下文。 例如，如果类型为 contactRelationUpdate，则当用户将机器人添加到其联系人列表中时，将添加操作属性的值，或者如果用户从联系人列表中删除了机器人，则会将其删除。
attachmentLayout	String	邮件包含的富卡 附件 的布局。 其中一个值： 轮播、 列表。 有关富卡附件的详细信息，请参阅 向邮件添加富卡附件。
附件	Attachment[]	用于定义要包含在邮件中的其他信息的 Attachment 对象的数组。 每个附件可以是文件（例如音频、视频、图像）或富卡。
callerId	String	包含标识机器人调用方 IRI 的字符串。 此字段不打算通过网络传输，而是由机器人和客户端根据断言调用方标识（例如令牌）的可加密验证数据填充。
通道数据	对象	一个包含特定于通道的内容的对象。 某些通道提供的功能需要其他无法使用附件架构表示的信息。 对于这些情况，请将此属性设置为通道文档中定义的特定于通道的内容。 有关详细信息，请参阅 “实现通道特定的功能”。
channelId	String	一个唯一标识通道的ID。 由通道设置。
代码	String	指示会话结束原因的代码。
conversation	ConversationAccount	一个 ConversationAccount 对象，用于定义活动所属的对话。
deliveryMode	String	用于向收件人发出活动备用传递路径的信号的传递提示。 以下值之一： 普通值、 通知。
实体	object[]	表示消息中提到的实体的对象数组。 此数组中的对象可以是任何 Schema.org 对象。 例如，数组可能包括 “提及 ”对象，这些对象标识对话中提及的人员，以及标识对话中提及的位置的 Place 对象。
expiration	String	活动被视为“已过期”的时间，不应提供给收件人。
from	ChannelAccount	指定邮件发送方的 ChannelAccount 对象。
historyDisclosed	布尔	指示是否披露历史记录的标志。 默认值为 false。
id	String	唯一标识通道上的活动的 ID。
importance	String	定义活动的重要性。 以下值之一： 低、 正常、 高。
inputHint	String	指示将消息传递到客户端后机器人是接受、期望还是忽略用户输入的值。 以下值之一： acceptingInput、 expectingInput、 ignoringInput。
label	String	活动的描述性标签。
listenFor	字符串数组[]	语音和语言启动系统应侦听的短语和引用列表。
区域设置	String	应用于在消息中显示文本的语言的区域设置，格式 <language>-<country>。 通道使用此属性来指示用户的语言，以便机器人可以指定该语言中的显示字符串。 默认值 为en-US。
localTimestamp	String	邮件以 ISO-8601 格式表示的本地时区发送的日期和时间。
localTimezone	String	包含以 IANA 时区数据库格式表示的消息本地时区的名称。 例如，美国/Los_Angeles。
membersAdded	ChannelAccount[]	ChannelAccount 对象的数组，这些对象表示加入会话的用户列表。 仅当活动 类型 为“conversationUpdate”且用户已加入对话时显示。
membersRemoved	ChannelAccount[]	ChannelAccount 对象的数组，这些对象表示离开会话的用户列表。 仅当活动 类型 为“conversationUpdate”且用户离开对话时显示。
name	String	要调用的操作的名称或事件的名称。
reactionsAdded	MessageReaction[]	添加到对话中的反应集合。
reactionsRemoved	MessageReaction[]	从对话中删除的反应集合。
recipient	ChannelAccount	指定邮件收件人的 ChannelAccount 对象。
relatesTo	ConversationReference	一个 ConversationReference 对象，用于定义会话中的特定点。
replyToId	String	此消息答复的消息的 ID。 若要答复用户发送的消息，请将此属性设置为用户消息的 ID。 并非所有通道都支持线程回复。 在这些情况下，通道将忽略此属性，并使用时间排序的语义（时间戳）将消息追加到会话。
semanticAction	SemanticAction	表示对编程操作的引用的 SemanticAction 对象。
serviceUrl	String	指定通道的服务终结点的 URL。 由通道设置。
语音	String	机器人在启用了语音的通道上朗读的文本。 若要控制机器人语音的各种特征，例如语音、速率、音量、发音和音调，请在 语音合成标记语言（SSML） 格式中指定此属性。
suggestedActions	SuggestedActions	一个 SuggestedActions 对象，用于定义用户可以从中选择的选项。
summary	String	消息包含的信息摘要。 例如，对于在电子邮件通道上发送的邮件，此属性可以指定电子邮件的前 50 个字符。
text	String	从用户发送到机器人或机器人到用户的消息的文本。 有关此属性内容的限制，请参阅通道的文档。
textFormat	String	邮件 文本的格式。 以下值之一： markdown、 plain、 xml。 有关文本格式的详细信息，请参阅 “创建消息”。
textHighlights	TextHighlight[]	活动包含 replyToId 值时要突出显示的文本片段集合。
timestamp	String	消息以 ISO-8601 格式表示的 UTC 时区发送的日期和时间。
topicName	String	活动所属的对话的主题。
type	String	活动的类型。 以下值之一： message、 contactRelationUpdate、 conversationUpdate、 type、 endOfConversation、 event、 invoke、 deleteUserData、 messageUpdate、 messageDelete、 installationUpdate、 messageReaction、 suggestion、 trace、 handoff。 有关活动类型的详细信息，请参阅 活动协议规范。
价值	对象	无拘限值。
valueType	String	活动值对象的类型。

返回架构表

AnimationCard 对象

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

财产	类型	Description
aspect	布尔	缩略图/媒体占位符的纵横比。 允许的值为“16：9”和“4：3”。
autoloop	布尔	指示是否在最后一个结束时重播动画 GIF 列表的标志。 将此属性设置为 true 以自动重播动画;否则为 false。 默认值为 true。
autostart	布尔	指示是否在显示卡片时自动播放动画的标志。 将此属性设置为 true 以自动播放动画;否则为 false。 默认值为 true。
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
duration	String	媒体内容的长度（ 采用 ISO 8601 持续时间格式）。
image	ThumbnailUrl	指定要在卡片上显示的图像的 ThumbnailUrl 对象。
media	MediaUrl[]	MediaUrl 对象的数组。 当此字段包含多个 URL 时，每个 URL 都是相同内容的替代格式。
可共享	布尔	指示动画是否可与其他人共享的标志。 如果可以共享动画，请将此属性设置为 true ;否则为 false。 默认值为 true。
副标题	String	要显示在卡片标题下的副标题。
text	String	说明或提示在卡片的标题或副标题下显示。
标题	String	卡片的标题。
价值	对象	此卡的补充参数。

返回架构表

Attachment 对象

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

财产	类型	Description
内容	对象	附件的内容。 如果附件是富卡，请将此属性设置为富卡对象。 此属性和 contentUrl 属性互斥。
contentType	String	附件中内容的媒体类型。 对于媒体文件，请将此属性设置为已知的媒体类型，例如 image/png、 audio/wav 和 video/mp4。 对于富卡，请将此属性设置为以下特定于供应商的类型之一： application/vnd.microsoft.card.adaptive：可以包含文本、语音、图像、按钮和输入字段的任意组合的富卡。 将 内容 属性设置为 AdaptiveCard 对象。 application/vnd.microsoft.card.animation：播放动画的丰富卡片。 将 内容 属性设置为 AnimationCard 对象。 application/vnd.microsoft.card.audio：播放音频文件的丰富卡片。 将 内容 属性设置为 AudioCard 对象。 application/vnd.microsoft.card.hero：Hero 卡。 将 内容 属性设置为 HeroCard 对象。 application/vnd.microsoft.card.receipt：收据卡。 将 内容 属性设置为 ReceiptCard 对象。 application/vnd.microsoft.card.signin：用户登录卡。 将 内容 属性设置为 SignInCard 对象。 application/vnd.microsoft.card.thumbnail：缩略图卡。 将 内容 属性设置为 ThumbnailCard 对象。 application/vnd.microsoft.card.video：播放视频的丰富卡片。 将 内容 属性设置为 VideoCard 对象。
contentUrl	String	附件内容的 URL。 例如，如果附件是图像，则可以将 contentUrl 设置为表示图像位置的 URL。 支持的协议包括：HTTP、HTTPS、文件和数据。
name	String	附件名称。
thumbnailUrl	String	如果通道支持使用另一种较小的内容或 contentUrl 形式，则通道可以使用的缩略图的 URL。 例如，如果将 contentType 设置为 application/word并将 contentUrl 设置为Word文档的位置，则可以包含表示文档的缩略图。 频道可以显示缩略图而不是文档。 当用户单击图像时，通道将打开该文档。

返回架构表

AttachmentData 对象

描述附件的数据。

财产	类型	Description
name	String	附件名称。
originalBase64	String	附件内容。
thumbnailBase64	String	附件缩略图内容。
type	String	附件的内容类型。

返回架构表

AttachmentInfo 对象

附件的元数据。

财产	类型	Description
name	String	附件名称。
type	String	附件的内容类型。
views	AttachmentView[]	表示附件可用视图的 AttachmentView 对象的数组。

返回架构表

AttachmentView 对象

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

财产	类型	Description
大小	编号	文件的大小。
viewId	String	视图 ID。

返回架构表

AudioCard 对象

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

财产	类型	Description
aspect	String	图像属性中指定的缩略图的纵横比。 有效值为 16：9 和 4：3。
autoloop	布尔	指示是否在最后一个音频文件结束时重播音频文件的列表的标志。 将此属性设置为 true 以自动重播音频文件;否则为 false。 默认值为 true。
autostart	布尔	指示在显示卡片时是否自动播放音频的标志。 将此属性设置为 true 以自动播放音频;否则为 false。 默认值为 true。
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
duration	String	媒体内容的长度（ 采用 ISO 8601 持续时间格式）。
image	ThumbnailUrl	指定要在卡片上显示的图像的 ThumbnailUrl 对象。
media	MediaUrl[]	MediaUrl 对象的数组。 当此字段包含多个 URL 时，每个 URL 都是相同内容的替代格式。
可共享	布尔	指示是否与他人共享音频文件的标志。 如果音频可以共享，请将此属性设置为 true ;否则为 false。 默认值为 true。
副标题	String	要显示在卡片标题下的副标题。
text	String	说明或提示在卡片的标题或副标题下显示。
标题	String	卡片的标题。
价值	对象	此卡的补充参数。

返回架构表

CardAction 对象

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

财产	类型	Description
通道数据	String	与此操作相关的特定通道数据。
displayText	String	单击按钮时显示在聊天源中的文本。
image	String	将在文本标签旁边的按钮上显示的图像 URL。
text	String	操作的文本。
标题	String	按钮上显示的文本说明。
type	String	要执行的操作的类型。 有关有效值的列表，请参阅 向邮件添加富卡附件。
价值	对象	操作的补充参数。 此属性的行为将因操作 类型而异。 有关详细信息，请参阅 向邮件添加富卡附件。

返回架构表

CardImage 对象

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

财产	类型	Description
alt	String	图像的描述。 应包含支持辅助功能的说明。
点击	CardAction	一个 CardAction 对象，指定在用户点击或单击图像时要执行的操作。
url	String	图像源或图像的 base64 二进制文件的 URL（例如）。 data:image/png;base64,iVBORw0KGgo...

返回架构表

ChannelAccount 对象

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

财产	类型	Description
aadObjectId	String	此帐户的对象 ID 在Microsoft Entra ID。
id	String	此通道上用户或机器人的唯一 ID。
name	String	机器人或用户的显示友好名称。
角色	String	帐户后面的实体的角色。 用户或机器人。

返回架构表

ConversationAccount 对象

定义通道中的对话。

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

返回架构表

ConversationMembers 对象

定义聊天的成员。

财产	类型	Description
id	String	对话 ID。
members	ChannelAccount[]	此对话中的成员列表。

返回架构表

ConversationParameters 对象

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

财产	类型	Description
活动	Activity	创建会话时要发送到对话的初始消息。
Bot	ChannelAccount	将消息路由到机器人所需的通道帐户信息。
通道数据	对象	用于创建聊天的通道特定的有效负载。
isGroup	布尔	指示这是否为组对话。
members	ChannelAccount[]	将消息路由到每个用户所需的频道帐户信息。
tenantId	String	应在其中创建聊天的租户 ID。
topicName	String	对话的主题。 仅当通道支持此属性时，才使用此属性。

返回架构表

ConversationReference 对象

定义对话中的特定点。

财产	类型	Description
activityId	String	唯一标识此对象引用的活动的 ID。
Bot	ChannelAccount	一个 ChannelAccount 对象，用于标识此对象引用的对话中的机器人。
channelId	String	唯一标识此对象引用的对话中的通道的 ID。
conversation	ConversationAccount	定义此对象引用的会话的 ConversationAccount 对象。
serviceUrl	String	指定此对象引用的会话中的通道服务终结点的 URL。
user	ChannelAccount	一个 ChannelAccount 对象，用于标识此对象引用的对话中的用户。

返回架构表

ConversationResourceResponse 对象

定义 对创建对话的响应。

财产	类型	Description
activityId	String	活动的 ID（如果已发送）。
id	String	资源的 ID。
serviceUrl	String	服务端点，可用于执行与对话相关的操作。

返回架构表

ConversationsResult 对象

定义 “获取对话”的结果。

财产	类型	Description
对话	ConversationMembers[]	每个对话中的成员。
continuationToken	String	可在后续调用 “获取对话”中使用的延续标记。

返回架构表

Entity 对象

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

财产	类型	Description
type	String	此实体的类型（RFC 3987 IRI）。

返回架构表

错误对象

表示错误信息的对象。

财产	类型	Description
代码	String	错误代码。
innerHttpError	InnerHttpError	表示内部 HTTP 错误的对象。
消息	String	对错误的说明。

返回架构表

ErrorResponse 对象

定义 HTTP API 响应。

财产	类型	Description
error	Error	包含有关错误的信息的 Error 对象。

返回架构表

Fact 对象

定义包含事实的键值对。

财产	类型	Description
键	String	事实的名称。 例如， 签入。 显示事实值时，该键用作标签。
价值	String	事实的值。 例如， 2016 年 10 月 10 日。

返回架构表

GeoCoordinates 对象

使用 World Geodetic System （WSG84） 坐标定义地理位置。

财产	类型	Description
提升	编号	位置的提升。
latitude	编号	位置的纬度。
longitude	编号	位置的经度。
name	String	位置的名称。
type	String	此对象的类型。 始终设置为 GeoCoordinates。

返回架构表

HeroCard 对象

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

财产	类型	Description
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
图像	CardImage[]	CardImage 对象的数组，指定要在卡片上显示的图像。 Hero 卡仅包含一个图像。
副标题	String	要显示在卡片标题下的副标题。
点击	CardAction	一个 CardAction 对象，指定当用户点击或单击卡片时要执行的操作。 这可以是与其中一个按钮或另一个操作相同的操作。
text	String	说明或提示在卡片的标题或副标题下显示。
标题	String	卡片的标题。

返回架构表

InnerHttpError 对象

表示内部 HTTP 错误的对象。

财产	类型	Description
statusCode	编号	失败请求中的 HTTP 状态代码。
正文	对象	失败请求中的正文。

返回架构表

MediaEventValue 对象

媒体事件的补充参数。

财产	类型	Description
cardValue	对象	在发起此事件的媒体卡 的值 字段中指定的回调参数。

返回架构表

MediaUrl 对象

定义媒体文件的源的 URL。

财产	类型	Description
profile	String	描述媒体内容的提示。
url	String	媒体文件的源的 URL。

返回架构表

Mention 对象

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

财产	类型	Description
提及	ChannelAccount	一个 ChannelAccount 对象，指定所提及的用户或机器人。 某些通道（如 Slack）为每个对话分配名称，因此机器人的提及名称（在消息 的收件人 属性中）可能与 注册 机器人时指定的句柄不同。 但是，两者的帐户 ID 相同。
text	String	聊天中提到的用户或机器人。 例如，如果消息为“@ColorBot选取新颜色”，则此属性将设置为 @ColorBot。 并非所有通道都设置此属性。
type	String	此对象的类型。 始终设置为 “提及”。

返回架构表

MessageReaction 对象

定义对消息的反应。

财产	类型	Description
type	String	反应类型。 例如或 plusOne。

返回架构表

PagedMembersResult 对象

获取对话分页成员返回的成员的页面。

财产	类型	Description
continuationToken	String	后续调用中可用于 获取对话分页成员的延续标记。
members	ChannelAccount[]	会话成员数组。

返回架构表

放置对象

定义对话中提及的位置。

财产	类型	Description
address	对象	地点的地址。 此属性可以是 PostalAddress 类型的字符串或复杂对象。
geo	GeoCoordinates	一个 GeoCoordinates 对象，该对象指定位置的地理坐标。
hasMap	对象	映射到该位置。 此属性可以是 字符串 （URL）或 Map 类型的复杂对象。
name	String	位置的名称。
type	String	此对象的类型。 始终设置为 Place。

返回架构表

ReceiptCard 对象

定义包含购买收据的卡。

财产	类型	Description
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
事实	Fact[]	指定有关购买的信息 的事实 对象的数组。 例如，酒店住宿收据的事实列表可能包括签入日期和签出日期。 通道确定可指定的事实数。
物品	ReceiptItem[]	指定已购买项的 ReceiptItem 对象的数组
点击	CardAction	一个 CardAction 对象，指定当用户点击或单击卡片时要执行的操作。 这可以是与其中一个按钮或另一个操作相同的操作。
税	String	一个货币格式的字符串，指定应用于购买的税款金额。
标题	String	在收据顶部显示的标题。
total	String	一个货币格式的字符串，指定总购买价格，包括所有适用的税款。
vat	String	一个货币格式的字符串，指定应用于购买价格的增值税（VAT）金额。

返回架构表

ReceiptItem 对象

定义收据中的行项。

财产	类型	Description
image	CardImage	一个 CardImage 对象，该对象指定要在行项旁边显示的缩略图。
价格	String	一个货币格式的字符串，指定购买的所有单位的总价格。
数量	String	一个数值字符串，指定购买的单位数。
副标题	String	要在行项标题下显示的副标题。
点击	CardAction	一个 CardAction 对象，指定当用户点击或单击行项时要执行的操作。
text	String	行项的说明。
标题	String	行项的标题。

返回架构表

ResourceResponse 对象

定义包含资源 ID 的响应。

财产	类型	Description
id	String	唯一标识资源的 ID。

返回架构表

SemanticAction 对象

定义对编程操作的引用。

财产	类型	Description
实体	对象	一个对象，其中每个属性的值是 一个 Entity 对象。
id	String	此操作的 ID。
状态	String	此操作的状态。 允许的值： 开始、 继续、 完成。

返回架构表

SignInCard 对象

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

财产	类型	Description
buttons	CardAction[]	允许用户登录到服务的 CardAction 对象的数组。 通道确定可以指定的按钮数。
text	String	登录卡中包含说明或提示。

返回架构表

SuggestedActions 对象

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

财产	类型	Description
行动	CardAction[]	用于定义建议操作的 CardAction 对象的数组。
to	字符串数组[]	包含应向其显示建议操作的收件人 ID 的字符串数组。

返回架构表

TextHighlight 对象

指另一个字段中的内容子字符串。

财产	类型	Description
occurrence	编号	引用文本中的文本字段出现（如果存在多个）。
text	String	定义要突出显示的文本片段。

返回架构表

ThumbnailCard 对象

使用缩略图、标题、文本和操作按钮定义卡片。

财产	类型	Description
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
图像	CardImage[]	指定要在卡片上显示的缩略图图像的 CardImage 对象的数组。 通道确定可以指定的缩略图图像数。
副标题	String	要显示在卡片标题下的副标题。
点击	CardAction	一个 CardAction 对象，指定当用户点击或单击卡片时要执行的操作。 这可以是与其中一个按钮或另一个操作相同的操作。
text	String	说明或提示在卡片的标题或副标题下显示。
标题	String	卡片的标题。

返回架构表

ThumbnailUrl 对象

定义图像源的 URL。

财产	类型	Description
alt	String	图像的描述。 应包含支持辅助功能的说明。
url	String	图像源或图像的 base64 二进制文件的 URL（例如）。 data:image/png;base64,iVBORw0KGgo...

返回架构表

脚本对象

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

财产	类型	Description
活动	数组	Activity 对象的数组。 它们应具有唯一的 ID 和时间戳。

返回架构表

VideoCard 对象

定义可播放视频的卡片。

财产	类型	Description
aspect	String	视频的纵横比。 16：9 或 4：3。
autoloop	布尔	指示是否在最后一个视频结束时重播视频列表的标志。 将此属性设置为 true 以自动重播视频;否则为 false。 默认值为 true。
autostart	布尔	指示在显示卡片时是否自动播放视频的标志。 将此属性设置为 true 以自动播放视频;否则为 false。 默认值为 true。
buttons	CardAction[]	使用户能够执行一个或多个操作的 CardAction 对象的数组。 通道确定可以指定的按钮数。
duration	String	媒体内容的长度（ 采用 ISO 8601 持续时间格式）。
image	ThumbnailUrl	指定要在卡片上显示的图像的 ThumbnailUrl 对象。
media	MediaUrl[]	MediaUrl 数组。 当此字段包含多个 URL 时，每个 URL 都是相同内容的替代格式。
可共享	布尔	指示视频是否可与其他人共享的标志。 如果视频可以共享，请将此属性设置为 true ;否则为 false。 默认值为 true。
副标题	String	要显示在卡片标题下的副标题。
text	String	说明或提示在卡片的标题或副标题下显示。
标题	String	卡片的标题。
价值	对象	此卡的补充参数

返回架构表