API 參考-Bot 連接器API reference - Bot Connector

注意

REST API 不等同於 SDK。The REST API is not equivalent to the SDK. REST API 是為了支援標準 REST 通訊,而 SDK 則是與 Bot Framework 通訊的慣用方法。The REST API is provided to allow standard REST communication, however the preferred method of interacting with the Bot Framework is the SDK.

在 Bot Framework 內,Bot 連接器服務可讓您的 Bot 透過在 Bot Framework 入口網站中設定的通道與使用者交換訊息。Within the Bot Framework, the Bot Connector service enables your bot to exchange messages with users on channels that are configured in the Bot Framework Portal. 此服務會透過 HTTPS 使用業界標準的 REST 和 JSON。The service uses industry-standard REST and JSON over HTTPS.

基底 URIBase URI

使用者傳送訊息給 Bot 時,傳入要求將包含一個活動物件,以及一個用於指定端點以接收 Bot 回應的 serviceUrl 屬性。When a user sends a message to your bot, the incoming request contains an Activity object with a serviceUrl property that specifies the endpoint to which your bot should send its response. 若要存取 Bot 連接器服務,請將 serviceUrl 值作為 API 要求的基底 URI。To access the Bot Connector service, use the serviceUrl value as the base URI for API requests.

例如,假設使用者傳送訊息給您的 Bot 時,Bot 收到了下列活動。For example, assume that your bot receives the following activity when the user sends a message to the bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/apis",
    "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 屬性指出 Bot 應將回應傳送至端點 https://smba.trafficmanager.net/apis;而這就會是 Bot 在該交談內容中發出任何後續要求時所用的基底 URI。The serviceUrl property within the user's message indicates that the bot should send its response to the endpoint https://smba.trafficmanager.net/apis; this will be the base URI for any subsequent requests that the bot issues in the context of this conversation. 如果您的 Bot 需要傳送主動式訊息給使用者,請務必儲存 serviceUrl 的值。If your bot will need to send a proactive message to the user, be sure to save the value of serviceUrl.

下列範例說明由 Bot 發出的要求,該要求乃是用於回應使用者訊息。The following example shows the request that the bot issues to respond to the user's message.

POST https://smba.trafficmanager.net/apis/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..."
}

headersHeaders

要求標頭Request headers

除了標準的 HTTP 要求標頭,您發出的每個 API 要求都必須包含指定存取權杖的 Authorization 標頭以驗證您的 Bot。In addition to the standard HTTP request headers, every API request that you issue must include an Authorization header that specifies an access token to authenticate your bot. 使用此格式指定 Authorization 標頭:Specify the Authorization header using this format:

Authorization: Bearer ACCESS_TOKEN

如需有關如何取得 Bot 存取權杖的詳細資料,請參閱驗證 Bot 向 Bot 連接器服務提出的要求For details about how to obtain an access token for your bot, see Authenticate requests from your bot to the Bot Connector service.

回應標頭Response headers

除了標準的 HTTP 回應標頭,每個回應都將包含 X-Correlating-OperationId 標頭。In addition to the standard HTTP response headers, every response will contain an X-Correlating-OperationId header. 此標頭的值即為對應於 Bot Framework 記錄項目的識別碼,其中包含有關要求的詳細資料。The value of this header is an ID that corresponds to the Bot Framework log entry which contains details about the request. 每次您收到錯誤訊息時,都應擷取該標頭的值。Any time that you receive an error response, you should capture the value of this header. 如果您無法獨立解決問題,回報時請將此值和相關資訊一併提供給支援小組。If you are not able to independently resolve the issue, include this value in the information that you provide to the Support team when you report the issue.

HTTP 狀態碼HTTP status codes

與每個回應一併傳回的 HTTP 狀態碼會指出對應要求的結果。The HTTP status code that is returned with each response indicates the outcome of the corresponding request.

注意

下表說明最常見的 HTTP 狀態碼。The following table describes the most common HTTP status codes. 某些錯誤是由通道產生。Some errors are generated by the channel. 如需詳細資訊,您可能需要閱讀通道的開發人員檔。For more information, you may need to read the channel's developer documentation.

HTTP 狀態碼HTTP status code 意義Meaning
200200 要求成功。The request succeeded.
201201 要求成功。The request succeeded.
202202 已接受要求以進行處理。The request was accepted for processing.
204204 要求成功,但未傳回任何內容。The request succeeded but no content was returned.
400400 要求的格式不正確或有其他錯誤。The request was malformed or otherwise incorrect.
401401 Bot 尚未經過驗證。The bot is not yet authenticated.
403403 Bot 未獲授權執行要求的操作。The bot is not authorized to perform the requested operation.
404404 找不到要求的資源。The requested resource was not found.
405405 通道不支援要求的作業。The channel does not support the requested operation.
500500 發生內部伺服器錯誤。An internal server error occurred.
503503 服務暫時無法使用。The service is temporarily unavailable.

ErrorsErrors

若回應顯示的 HTTP 狀態碼位於 4xx 或 5xx 範圍內,則會在提供錯誤相關資訊的回應本文中加入 ErrorResponse 物件。Any response that specifies an HTTP status code in the 4xx range or 5xx range will include an ErrorResponse object in the body of the response that provides information about the error. 如果您收到 4xx 範圍的錯誤訊息,請檢查 ErrorResponse 物件以找出錯誤原因,並在重新提交要求之前先解決問題。If you receive an error response in the 4xx range, inspect the ErrorResponse object to identify the cause of the error and resolve your issue prior to resubmitting the request.

交談作業Conversation operations

透過這些作業建立交談、傳送訊息 (活動),以及管理交談內容。Use these operations to create conversations, send messages (activities), and manage the contents of conversations.

作業Operation 描述Description
建立交談Create Conversation 建立新交談。Creates a new conversation.
刪除活動Delete Activity 刪除現有活動。Deletes an existing activity.
刪除交談成員Delete Conversation Member 從交談中移除成員。Removes a member from a conversation.
取得活動成員Get Activity Members 取得指定交談中指定活動的成員。Gets the members of the specified activity within the specified conversation.
取得交談成員Get Conversation Member 取得交談成員的相關詳細資料。Gets details about a member of a conversation.
取得交談成員Get Conversation Members 取得指定交談的成員。Gets the members of the specified conversation.
取得對話分頁成員Get Conversation Paged Members 取得指定對話的成員 (一次一頁)。Gets the members of the specified conversation one page at a time.
取得交談Get Conversations 取得聊天機器人所參與的交談清單。Gets a list of conversations the bot has participated in.
回覆活動Reply to Activity 將活動 (訊息) 傳送至指定交談,以回覆指定活動。Sends an activity (message) to the specified conversation, as a reply to the specified activity.
傳送交談記錄Send Conversation History 將過往活動的文字記錄上傳至交談。Uploads a transcript of past activities to the conversation.
傳送至交談Send to Conversation 將活動 (訊息) 傳送至指定交談的結尾處。Sends an activity (message) to the end of the specified conversation.
更新活動Update Activity 更新現有作業。Updates an existing activity.
將附件上傳至通道Upload Attachment to Channel 將附件直接上傳到通道的 Blob 儲存體。Uploads an attachment directly into a channel's blob storage.

建立交談Create Conversation

建立新交談。Creates a new conversation.

POST /v3/conversations
內容Content 描述Description
要求本文Request body ConversationParameters 物件A ConversationParameters object
傳回Returns ConversationResourceResponse 物件A ConversationResourceResponse object

刪除活動Delete Activity

部分通道可讓您刪除現有活動。Some channels allow you to delete an existing activity. 若成功執行此作業,指定活動將會從指定交談移除。If successful, this operation removes the specified activity from the specified conversation.

DELETE /v3/conversations/{conversationId}/activities/{activityId}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns 用於指出作業結果的 HTTP 狀態碼。An HTTP Status code that indicates the outcome of the operation. 回應本文中未指定任何項目。Nothing is specified in the body of the response.

刪除交談成員Delete Conversation Member

從交談中移除成員。Removes a member from a conversation. 如果該成員是交談內的最後一個成員,則該交談也會遭到刪除。If that member was the last member of the conversation, the conversation will also be deleted.

DELETE /v3/conversations/{conversationId}/members/{memberId}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns 用於指出作業結果的 HTTP 狀態碼。An HTTP Status code that indicates the outcome of the operation. 回應本文中未指定任何項目。Nothing is specified in the body of the response.

取得活動成員Get Activity Members

取得指定交談中指定活動的成員。Gets the members of the specified activity within the specified conversation.

GET /v3/conversations/{conversationId}/activities/{activityId}/members
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns ChannelAccount 物件陣列An array of ChannelAccount objects

取得交談Get Conversations

取得聊天機器人所參與的交談清單。Gets a list of conversations the bot has participated in.

GET /v3/conversations?continuationToken={continuationToken}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns ConversationsResult 物件A ConversationsResult object

取得交談成員Get Conversation Member

取得特定交談之特定成員的相關詳細資料。Gets details about a specific member of a specific conversation.

GET /v3/conversations/{conversationId}/members/{memberId}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns 成員的 ChannelAccount 物件。A ChannelAccount object for the member.

取得交談成員Get Conversation Members

取得指定交談的成員。Gets the members of the specified conversation.

GET /v3/conversations/{conversationId}/members
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns 交談成員的 ChannelAccount 物件陣列。An array of ChannelAccount objects for the members of the conversation.

取得對話分頁成員Get Conversation Paged Members

取得指定對話的成員 (一次一頁)。Gets the members of the specified conversation one page at a time.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns PagedMembersResult 物件A PagedMembersResult object

回覆活動Reply to Activity

將活動 (訊息) 傳送至指定交談,以回覆指定活動。Sends an activity (message) to the specified conversation, as a reply to the specified activity. 若通道支援,則系統會新增活動以回覆其他活動。The activity will be added as a reply to another activity, if the channel supports it. 若通道不支援巢狀回覆,則此作業將以傳送至交談的方式進行。If the channel does not support nested replies, then this operation behaves like Send to Conversation.

POST /v3/conversations/{conversationId}/activities/{activityId}
內容Content 描述Description
要求本文Request body Activity 物件An Activity object
傳回Returns ResourceResponse 物件A ResourceResponse object

傳送交談記錄Send Conversation History

將過往活動的文字記錄上傳至交談,以供用戶端呈現。Uploads a transcript of past activities to the conversation so that the client can render them.

POST /v3/conversations/{conversationId}/activities/history
內容Content 描述Description
要求本文Request body Transcript 物件。A Transcript object.
傳回Returns ResourceResponse 物件。A ResourceResponse object.

傳送至交談Send to Conversation

將活動 (訊息) 傳送至指定交談。Sends an activity (message) to the specified conversation. 系統將根據時間戳記或通道的語意,將活動附加至交談的結尾處。The activity will be appended to the end of the conversation according to the timestamp or semantics of the channel. 若要回應交談內的特定訊息,請改為使用回覆活動To reply to a specific message within the conversation, use Reply to Activity instead.

POST /v3/conversations/{conversationId}/activities
內容Content 描述Description
要求本文Request body Activity 物件An Activity object
傳回Returns ResourceResponse 物件A ResourceResponse object

更新活動Update Activity

部分通道可讓您編輯現有活動,以反映 Bot 交談的新狀態。Some channels allow you to edit an existing activity to reflect the new state of a bot conversation. 例如,使用者按下其中一個按鈕後,您或許會將按鈕從交談訊息中移除。For example, you might remove buttons from a message in the conversation after the user has clicked one of the buttons. 若成功執行此作業,指定交談內的指定活動將會更新。If successful, this operation updates the specified activity within the specified conversation.

PUT /v3/conversations/{conversationId}/activities/{activityId}
內容Content 描述Description
要求本文Request body Activity 物件An Activity object
傳回Returns ResourceResponse 物件A ResourceResponse object

將附件上傳至通道Upload Attachment to Channel

將指定交談的附件直接上傳至通道的 Blob 儲存體。Uploads an attachment for the specified conversation directly into a channel's blob storage. 如此一來,可讓您將資料儲存在相容的存放區。This enables you to store data in a compliant store.

POST /v3/conversations/{conversationId}/attachments
內容Content 描述Description
要求本文Request body AttachmentData 物件。An AttachmentData object.
傳回Returns ResourceResponse 物件。A ResourceResponse object. 識別碼 屬性會指定可用於 取得附件資訊作業和 取得附件作業的附件識別碼。The id property specifies the attachment ID that can be used with the Get Attachment Info operation and the Get Attachment operation.

附件作業Attachment operations

利用這些作業擷取附件相關資訊,以及該檔案本身的二進位資料。Use these operations to retrieve information about an attachment as well the binary data for the file itself.

作業Operation 描述Description
取得附件資訊Get Attachment Info 取得有關指定附件的資訊,包括檔案名稱、檔案類型及可用檢視 (例如:原稿或縮圖)。Gets information about the specified attachment, including file name, file type, and the available views (e.g. original or thumbnail).
取得附件Get Attachment 取得指定附件的指定檢視做為二進位內容。Gets the specified view of the specified attachment as binary content.

取得附件資訊Get Attachment Info

取得有關指定附件的資訊,包括檔案名稱、類型及可用檢視 (例如:原稿或縮圖)。Gets information about the specified attachment, including file name, type, and the available views (e.g. original or thumbnail).

GET /v3/attachments/{attachmentId}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns AttachmentInfo 物件An AttachmentInfo object

取得附件Get Attachment

取得指定附件的指定檢視做為二進位內容。Gets the specified view of the specified attachment as binary content.

GET /v3/attachments/{attachmentId}/views/{viewId}
內容Content 描述Description
要求本文Request body n/an/a
傳回Returns 代表指定附件之指定檢視的二進位內容Binary content that represents the specified view of the specified attachment

狀態作業 (已淘汰)State operations (deprecated)

Microsoft Bot Framework 狀態服務已於 2018 年 3 月 30 日淘汰。The Microsoft Bot Framework State service is retired as of March 30, 2018. 之前,建置於 Azure Bot 服務或 Bot Builder SDK 的 Bot 可依預設連線至 Microsoft 所裝載的這項服務,以儲存 Bot 狀態資料。Previously, bots built on the Azure Bot Service or the Bot Builder SDK had a default connection to this service hosted by Microsoft to store bot state data. Bot 將需要更新才能使用其本身的狀態儲存體。Bots will need to be updated to use their own state storage.

作業Operation 描述Description
Set User Data 儲存通道上特定使用者的狀態資料。Stores state data for a specific user on a channel.
Set Conversation Data 儲存某通道上特定交談的狀態資料。Stores state data for a specific conversation on a channel.
Set Private Conversation Data 儲存通道上特定交談內容中特定使用者的狀態資料。Stores state data for a specific user within the context of a specific conversation on a channel.
Get User Data 擷取先前為通道上所有交談的特定使用者儲存的狀態資料。Retrieves state data that has previously been stored for a specific user across all conversations on a channel.
Get Conversation Data 擷取先前為通道上的特定交談儲存的狀態資料。Retrieves state data that has previously been stored for a specific conversation on a channel.
Get Private Conversation Data 擷取先前為通道上特定交談內容中特定使用者儲存的狀態資料。Retrieves state data that has previously been stored for a specific user within the context of a specific conversation on a channel.
Delete State For User 刪除先前為使用者儲存的狀態資料。Deletes state data that has previously been stored for a user.

結構描述Schema

Bot Framework 活動結構描述會定義您的 Bot 可用來與使用者通訊的物件及其屬性。The Bot Framework schema defines the objects and their properties that your bot can use to communicate with a user.

ObjectObject 描述Description
Activity 物件Activity object 定義 Bot 和使用者之間交換的訊息。Defines a message that is exchanged between bot and user.
AnimationCard 物件AnimationCard object 定義可播放動畫 GIF 或短片的資訊卡。Defines a card that can play animated GIFs or short videos.
Attachment 物件Attachment object 定義要包含在訊息中的其他資訊。Defines additional information to include in the message. 附件可能是媒體檔案 (例如:音訊、影片、影像、檔案) 或複合式資訊卡。An attachment may be a media file (e.g. audio, video, image, file) or a rich card.
AttachmentData 物件AttachmentData object 描述附件資料。Describes an attachment data.
AttachmentInfo 物件AttachmentInfo object 描述附件。Describes an attachment.
AttachmentView 物件AttachmentView object 定義附件檢視。Defines a attachment view.
AudioCard 物件AudioCard object 定義可播放音訊檔案的資訊卡。Defines a card that can play an audio file.
CardAction 物件CardAction object 定義要執行的動作。Defines an action to perform.
CardImage 物件CardImage object 定義要在資訊卡上顯示的影像。Defines an image to display on a card.
ChannelAccount 物件ChannelAccount object 定義通道上的 Bot 或使用者帳戶。Defines a bot or user account on the channel.
ConversationAccount 物件ConversationAccount object 定義通道中的交談。Defines a conversation in a channel.
ConversationMembers 物件ConversationMembers object 定義交談的成員。Defines the members of a conversation.
ConversationParameters 物件ConversationParameters object 定義用來建立新交談的參數Define parameters for creating a new conversation
ConversationReference 物件ConversationReference object 定義交談中的特定要點。Defines a particular point in a conversation.
ConversationResourceResponse 物件ConversationResourceResponse object 定義建立交談的回應。Defines a response to Create Conversation.
ConversationsResult 物件ConversationsResult object 定義取得交談呼叫的結果。Defines the result of a call to Get Conversations.
Entity 物件Entity object 定義實體物件。Defines an entity object.
Error 物件Error object 定義錯誤。Defines an error.
ErrorResponse 物件ErrorResponse object 定義 HTTP API 回應。Defines an HTTP API response.
Fact 物件Fact object 定義包含事實的機碼值組。Defines a key-value pair that contains a fact.
GeoCoordinates 物件GeoCoordinates object 定義採用「世界大地坐標系統 (WSG84)」座標的地理位置。Defines a geographical location using World Geodetic System (WSG84) coordinates.
HeroCard 物件HeroCard object 定義具有大型影像、標題、文字及動作按鈕的資訊卡。Defines a card with a large image, title, text, and action buttons.
InnerHttpError 物件InnerHttpError object 代表內部 HTTP 錯誤的物件。Object representing an inner HTTP error.
MediaEventValue 物件MediaEventValue object 媒體事件的增補參數。Supplementary parameter for media events.
MediaUrl 物件MediaUrl object 定義媒體檔案來源的 URL。Defines the URL to a media file's source.
Mention 物件Mention object 定義在交談中提及的使用者或 Bot。Defines a user or bot that was mentioned in the conversation.
MessageReaction 物件MessageReaction object 定義對訊息的回應。Defines a reaction to a message.
PagedMembersResult 物件PagedMembersResult object 取得交談分頁成員所傳回的成員頁面。Page of members returned by Get Conversation Paged Members.
Place 物件Place object 定義在交談中提及的地點。Defines a place that was mentioned in the conversation.
ReceiptCard 物件ReceiptCard object 定義內含購買收據的資訊卡。Defines a card that contains a receipt for a purchase.
ReceiptItem 物件ReceiptItem object 定義收據內的明細項目。Defines a line item within a receipt.
ResourceResponse 物件ResourceResponse object 定義資源。Defines a resource.
SemanticAction 物件SemanticAction object 定義程式設計動作的參考。Defines a reference to a programmatic action.
SignInCard 物件SignInCard object 定義可讓使用者登入至服務的資訊卡。Defines a card that lets a user sign in to a service.
SuggestedActions 物件SuggestedActions object 定義可讓使用者從中選擇的選項。Defines the options from which a user can choose.
TextHighlight 物件TextHighlight object 參照其他欄位內的內容子字串。Refers to a substring of content within another field.
ThumbnailCard 物件ThumbnailCard object 定義具有縮圖影像、標題、文字和動作按鈕的資訊卡。Defines a card with a thumbnail image, title, text, and action buttons.
ThumbnailUrl 物件ThumbnailUrl object 定義影像來源的 URL。Defines the URL to an image's source.
Transcript 物件Transcript object 要使用傳送交談記錄上傳的活動集合。A collection of activities to be uploaded using Send Conversation History.
VideoCard 物件VideoCard object 定義可播放影片的資訊卡。Defines a card that can play videos.

活動物件Activity object

定義 Bot 和使用者之間交換的訊息。Defines a message that is exchanged between bot and user.

屬性Property 類型Type 描述Description
actionaction 字串string 要套用的動作或是已套用的動作。The action to apply or that was applied. 使用 類型 屬性判斷動作的內容。Use the type property to determine context for the action. 例如,在 類型contactRelationUpdate 的情況下,若使用者將 Bot 新增至其連絡人清單,則 action 屬性的值會是 add;而若使用者將 Bot 從連絡人清單中移除,其值則為 removeFor example, if type is contactRelationUpdate, the value of the action property would be add if the user added your bot to their contacts list, or remove if they removed your bot from their contacts list.
attachmentLayoutattachmentLayout 字串string 包含在訊息中的豐富資訊卡 附件 的版面配置。Layout of the rich card attachments that the message includes. 下列任一值:carousellistOne of these values: carousel, list. 如需有關豐富資訊卡附件的詳細資訊,請參閱將豐富資訊卡附件新增至訊息For more information about rich card attachments, see Add rich card attachments to messages.
attachmentsattachments Attachment[]Attachment[] Attachment 物件陣列,用於定義要加入訊息的其他資訊。Array of Attachment objects that defines additional information to include in the message. 各個附件可能是檔案 (例如:音訊、影片、影像) 或複合式資訊卡。Each attachment may be either a file (e.g. audio, video, image) or a rich card.
callerIdcallerId 字串string 一個包含 IRI 用以識別 Bot 呼叫端的字串。A string containing an IRI identifying the caller of a bot. 此欄位並非透過線路傳輸,而是由 Bot 和用戶端填入;他們會依據可經由密碼編譯驗證、對呼叫端的身分識別 (例如權杖) 進行判斷提示的資料來執行。This field is not intended to be transmitted over the wire, but is instead populated by bots and clients based on cryptographically verifiable data that asserts the identity of the callers (e.g. tokens).
channelDatachannelData 物件 (object)object 包含通道專用內容的物件。An object that contains channel-specific content. 某些通道提供的功能,需要使用無法以附件結構描述來呈現的其他資訊。Some channels provide features that require additional information that cannot be represented using the attachment schema. 在該等情況下,請將此屬性設定為通道文件中所定義的通道專用內容。For those cases, set this property to the channel-specific content as defined in the channel's documentation. 如需詳細資訊,請參閱實作通道專屬功能For more information, see Implement channel-specific functionality.
channelIdchannelId 字串string 可唯一識別通道的識別碼。An ID that uniquely identifies the channel. 由通道設定。Set by the channel.
codecode 字串string 指出交談終止原因的代碼。Code indicating why the conversation has ended.
交談 conversation ConversationAccountConversationAccount 定義活動所屬交談的 ConversationAccount 物件。A ConversationAccount object that defines the conversation to which the activity belongs.
deliveryModedeliveryMode 字串string 一個傳遞提示,用來將活動的替代傳遞路徑告知收件者。A delivery hint to signal to the recipient alternate delivery paths for the activity. 下列任一值:normalnotificationOne of these values: normal, notification.
entitiesentities object[]object[] 代表訊息中提及之實體的物件陣列。Array of objects that represents the entities that were mentioned in the message. 此陣列中的物件可能是任何 Schema.org 物件。Objects in this array may be any Schema.org object. 例如,陣列可能包含 Mention 物件,可識別交談中提及的使用者;而 Place 物件則可識別交談中提及的地點。For example, the array may include Mention objects that identify someone who was mentioned in the conversation and Place objects that identify a place that was mentioned in the conversation.
expirationexpiration 字串string 應將活動視為「過期」而不向收件者顯示的時間。The time at which the activity should be considered to be "expired" and should not be presented to the recipient.
fromfrom ChannelAccountChannelAccount 用於指出訊息傳送者的 ChannelAccount 物件。A ChannelAccount object that specifies the sender of the message.
historyDisclosedhistoryDisclosed booleanboolean 用於指出是否公開歷程記錄的旗標。Flag that indicates whether or not history is disclosed. 預設值為 falseDefault value is false.
idid 字串string 可唯一識別通道活動的識別碼。ID that uniquely identifies the activity on the channel.
importanceimportance 字串string 定義活動的重要性。Defines the importance of an Activity. 下列任一值:lownormalhighOne of these values: low, normal, high.
inputHintinputHint 字串string 此值指出您的 Bot 在訊息傳遞給用戶端之後是否要接受、等候或忽略使用者輸入。Value that indicates whether your bot is accepting, expecting, or ignoring user input after the message is delivered to the client. 下列任一值:acceptingInputexpectingInputignoringInputOne of these values: acceptingInput, expectingInput, ignoringInput.
labellabel 字串string 活動的描述性標籤。A descriptive label for the activity.
listenForlistenFor string[]string[] 語音和語言預備系統所應聽取的片語和參考清單。List of phrases and references that speech and language priming systems should listen for.
localelocale 字串string 訊息內顯示文字所使用之語言的地區設定 (格式為:<language>-<country>)。Locale of the language that should be used to display text within the message, in the format <language>-<country>. 通道使用此屬性指出使用者語言,如此 Bot 即可以該語言指定顯示字串。The channel uses this property to indicate the user's language, so that your bot may specify display strings in that language. 預設值為 en-USDefault value is en-US.
localTimestamplocalTimestamp 字串string 訊息傳送時的當地時區日期及時間,以 ISO-8601 格式表示。Date and time that the message was sent in the local time zone, expressed in ISO-8601 format.
localTimezonelocalTimezone 字串string 包含訊息的當地時區名稱,以 IANA 時區資料庫格式表示。Contains the name of the local timezone of the message, expressed in IANA Time Zone database format. 例如 America/Los_Angeles。For example, America/Los_Angeles.
membersAddedmembersAdded ChannelAccount[]ChannelAccount[] 代表已加入交談之使用者清單的 ChannelAccount 物件陣列。Array of ChannelAccount objects that represents the list of users that joined the conversation. 僅在活動 類型 為「conversationUpdate」,且使用者已加入交談的情況下才會顯示。Present only if activity type is "conversationUpdate" and users joined the conversation.
membersRemovedmembersRemoved ChannelAccount[]ChannelAccount[] 代表已離開交談之使用者清單的 ChannelAccount 物件陣列。Array of ChannelAccount objects that represents the list of users that left the conversation. 僅在活動 類型 為「conversationUpdate」,且使用者已離開交談的情況下才會顯示。Present only if activity type is "conversationUpdate" and users left the conversation.
namename 字串string 要叫用之作業的名稱或事件的名稱。Name of the operation to invoke or the name of the event.
reactionsAddedreactionsAdded MessageReaction[]MessageReaction[] 新增至交談的回應集合。The collection of reactions added to the conversation.
reactionsRemovedreactionsRemoved MessageReaction[]MessageReaction[] 從交談中移除的回應集合。The collection of reactions removed from the conversation.
recipientrecipient ChannelAccountChannelAccount 用於指出訊息收件者的 ChannelAccount 物件。A ChannelAccount object that specifies the recipient of the message.
relatesTorelatesTo ConversationReferenceConversationReference 用於定義交談中特定要點的 ConversationReference 物件。A ConversationReference object that defines a particular point in a conversation.
replyToIdreplyToId 字串string 此訊息要回覆之訊息的識別碼。The ID of the message to which this message replies. 若要回覆使用者傳送的訊息,請將此屬性設為該使用者訊息的識別碼。To reply to a message that the user sent, set this property to the ID of the user's message. 並非所有通道皆支援執行緒回覆。Not all channels support threaded replies. 在這些情況下,通道會忽略此屬性,並使用依照時間排序的語意 (時間戳記),將訊息附加至交談。In these cases, the channel will ignore this property and use time ordered semantics (timestamp) to append the message to the conversation.
semanticActionsemanticAction SemanticActionSemanticAction SemanticAction 物件,代表程式設計動作的參考。A SemanticAction object that represents a reference to a programmatic action.
serviceUrlserviceUrl 字串string 用於指定通道服務端點的 URL。URL that specifies the channel's service endpoint. 由通道設定。Set by the channel.
speakspeak 字串string 要讓 Bot 在支援語音功能的通道上以語音讀出的文字。Text to be spoken by your bot on a speech-enabled channel. 若要控制 Bot 語音的聲音、速率、音量、發音和音高等各種特性,請以語音合成標記語言 (SSML) 格式指定此屬性。To control various characteristics of your bot's speech such as voice, rate, volume, pronunciation, and pitch, specify this property in Speech Synthesis Markup Language (SSML) format.
suggestedActionssuggestedActions SuggestedActionsSuggestedActions 用於定義選項以讓使用者從中選擇的 SuggestedActions 物件。A SuggestedActions object that defines the options from which the user can choose.
summarysummary 字串string 訊息包含的資訊摘要。Summary of the information that the message contains. 例如,若是透過電子郵件通道傳送的訊息,此屬性可指定電子郵件訊息的前 50 個字元。For example, for a message that is sent on an email channel, this property may specify the first 50 characters of the email message.
texttext 字串string Bot 與使用者之間傳送的訊息文字。Text of the message that is sent from user to bot or bot to user. 請參閱通道文件,以了解加諸於此屬性內容的限制。See the channel's documentation for limits imposed upon the contents of this property.
textFormattextFormat 字串string 訊息 文字 的格式。Format of the message's text. 下列任一值:markdownplainxmlOne of these values: markdown, plain, xml. 如需有關文字格式的詳細資料,請參閱建立訊息For details about text format, see Create messages.
textHighlightstextHighlights TextHighlight[]TextHighlight[] 在活動包含 replyToId 值時會醒目提示的文字片段集合。The collection of text fragments to highlight when the activity contains a replyToId value.
timestamptimestamp 字串string 訊息傳送時的 UTC 時區日期及時間,以 ISO-8601 格式表示。Date and time that the message was sent in the UTC time zone, expressed in ISO-8601 format.
topicNametopicName 字串string 活動所屬交談的主題。Topic of the conversation to which the activity belongs.
typetype 字串string 活動的類型。Type of activity. 下列任一值:messagecontactRelationUpdateconversationUpdatetypingendOfConversationeventinvokedeleteUserDatamessageUpdatemessageDeleteinstallationUpdatemessageReactionsuggestiontracehandoffOne of these values: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. 如需有關活動類型的詳細資料,請參閱活動概觀For details about activity types, see Activities overview.
valuevalue 物件 (object)object 開放端點的值。Open-ended value.
valueTypevalueType 字串string 活動的值物件類型。The type of the activity's value object.

回到結構描述資料表Back to Schema table

AnimationCard 物件AnimationCard object

定義可播放動畫 GIF 或短片的資訊卡。Defines a card that can play animated GIFs or short videos.

屬性Property 類型Type 描述Description
aspectaspect booleanboolean 縮圖/媒體預留位置的外觀比例。Aspect ratio of thumbnail/media placeholder. 允許的值為 "16:9" 和 "4:3"。Allowed values are "16:9" and "4:3".
autoloopautoloop booleanboolean 用於指出最後一個動畫 GIF 播放完畢後是否要重播動畫 GIF 清單的旗標。Flag that indicates whether to replay the list of animated GIFs when the last one ends. 將此屬性設為 true 可自動重播動畫;如不重播則設為 falseSet this property to true to automatically replay the animation; otherwise, false. 預設值為 trueThe default value is true.
autostartautostart booleanboolean 用於指出資訊卡顯示時是否要自動播放動畫的旗標。Flag that indicates whether to automatically play the animation when the card is displayed. 將此屬性設為 true 可自動播放動畫;如不播放則設為 falseSet this property to true to automatically play the animation; otherwise, false. 預設值為 trueThe default value is true.
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
durationduration 字串string 媒體內容的長度,採用 ISO 8601 持續時間格式The length of the media content, in ISO 8601 duration format.
imageimage ThumbnailUrlThumbnailUrl 可指定要在資訊卡上顯示之影像的 ThumbnailUrl 物件。A ThumbnailUrl object that specifies the image to display on the card.
mediamedia MediaUrl[]MediaUrl[] MediaUrl 物件的陣列。Array of MediaUrl objects. 此欄位包含多個 URL 時,每個 URL 都會是相同內容的替代格式。When this field contains more than one URL, each URL is an alternative format of the same content.
shareableshareable booleanboolean 用於指出是否要與他人共用動畫的旗標。Flag that indicates whether the animation may be shared with others. 將此屬性設為 true 可與他人共用動畫;如不共用則設為 falseSet this property to true if the animation may be shared; otherwise, false. 預設值為 trueThe default value is true.
subtitlesubtitle 字串string 顯示在資訊卡標題下方的子標題。Subtitle to display under the card's title.
texttext 字串string 顯示在資訊卡標題或子標題下方的描述或提示。Description or prompt to display under the card's title or subtitle.
titletitle 字串string 資訊卡的標題。Title of the card.
valuevalue 物件 (object)object 此資訊卡的增補參數。Supplementary parameter for this card.

回到結構描述資料表Back to Schema table

Attachment 物件Attachment object

定義要包含在訊息中的其他資訊。Defines additional information to include in the message. 附件可能是檔案 (例如影像、音訊或影片) 或複合式資訊卡。An attachment may be a file (such as an image, audio, or video) or a rich card.

屬性Property 類型Type 描述Description
contentcontent 物件 (object)object 附加檔案的內容。The content of the attachment. 若附件是豐富資訊卡,則將此屬性設為豐富資訊卡物件。If the attachment is a rich card, set this property to the rich card object. 此屬性與 contentUrl 屬性互斥。This property and the contentUrl property are mutually exclusive.
contentTypecontentType 字串string 附件中內容的媒體類型。The media type of the content in the attachment. 若為媒體檔案,請將此屬性設為已知的媒體類型如:image/pngaudio/wavvideo/mp4For media files, set this property to known media types such as image/png, audio/wav, and video/mp4. 若為豐富資訊卡,請將此屬性設為下列任一個廠商特有類型:For rich cards, set this property to one of these vendor-specific types:
  • application/vnd.microsoft.card.adaptive:豐富卡片可包含文字、語音、影像、按鈕和輸入欄位的任何組合。application/vnd.microsoft.card.adaptive: A rich card that can contain any combination of text, speech, images, buttons, and input fields. 內容 屬性設為 AdaptiveCard 物件。Set the content property to an AdaptiveCard object.
  • application/vnd.microsoft.card.animation:可播放動畫的豐富介面卡。application/vnd.microsoft.card.animation: A rich card that plays animation. 內容 屬性設為 AnimationCard 物件。Set the content property to an AnimationCard object.
  • application/vnd.microsoft.card.audio:可播放音訊檔案的豐富介面卡。application/vnd.microsoft.card.audio: A rich card that plays audio files. 內容 屬性設為 AudioCard 物件。Set the content property to an AudioCard object.
  • application/vnd.microsoft.card.hero:主圖卡片。application/vnd.microsoft.card.hero: A Hero card. 內容 屬性設為 HeroCard 物件。Set the content property to a HeroCard object.
  • application/vnd.microsoft.card.receipt:收據卡片。application/vnd.microsoft.card.receipt: A Receipt card. 內容 屬性設為 ReceiptCard 物件。Set the content property to a ReceiptCard object.
  • application/vnd.microsoft.card.signin:使用者登入卡片。application/vnd.microsoft.card.signin: A user Sign In card. 內容 屬性設為 SignInCard 物件。Set the content property to a SignInCard object.
  • application/vnd.microsoft.card.thumbnail:縮圖卡片。application/vnd.microsoft.card.thumbnail: A Thumbnail card. 內容 屬性設為 ThumbnailCard 物件。Set the content property to a ThumbnailCard object.
  • application/vnd.microsoft.card.video:可播放影片的豐富介面卡。application/vnd.microsoft.card.video: A rich card that plays videos. 內容 屬性設為 VideoCard 物件。Set the content property to a VideoCard object.
contentUrlcontentUrl 字串string 附件內容的 URL。URL for the content of the attachment. 例如,如果附件是影像,您可以將 contentUrl 設為代表該影像位置的 URL。For example, if the attachment is an image, you can set contentUrl to the URL that represents the location of the image. 支援的通訊協定:HTTP、HTTPS、檔案和資料。Supported protocols are: HTTP, HTTPS, File, and Data.
namename 字串string 附件的名稱。Name of the attachment.
thumbnailUrlthumbnailUrl 字串string 若通道支援使用小型的 內容contentUrl,通道可使用之縮圖影像的 URL。URL to a thumbnail image that the channel can use if it supports using an alternative, smaller form of content or contentUrl. 例如,若您將 contentType 設為 application/word,並且將 contentUrl 設為 Word 文件的位置,則可加入代表該文件的縮圖影像。For example, if you set contentType to application/word and set contentUrl to the location of the Word document, you might include a thumbnail image that represents the document. 通道會顯示縮圖影像而非該文件。The channel could display the thumbnail image instead of the document. 只要使用者按一下影像,通道便會開啟該文件。When the user clicks the image, the channel would open the document.

回到結構描述資料表Back to Schema table

AttachmentData 物件AttachmentData object

說明附件的資料。Describes an attachment's data.

屬性Property 類型Type 描述Description
namename 字串string 附件的名稱。Name of the attachment.
originalBase64originalBase64 字串string 附件內容。Attachment content.
thumbnailBase64thumbnailBase64 字串string 附件縮圖內容。Attachment thumbnail content.
typetype 字串string 附件的內容類型。Content type of the attachment.

回到結構描述資料表Back to Schema table

AttachmentInfo 物件AttachmentInfo object

附件的中繼資料。Metadata for an attachment.

屬性Property 類型Type 描述Description
namename 字串string 附件的名稱。Name of the attachment.
typetype 字串string 附件的內容類型。Content type of the attachment.
檢視views AttachmentView[]AttachmentView[] 表示附件可用檢視的 AttachmentView 物件陣列。Array of AttachmentView objects that represent the available views for the attachment.

回到結構描述資料表Back to Schema table

AttachmentView 物件AttachmentView object

定義附件檢視。Defines a attachment view.

屬性Property 類型Type 描述Description
sizesize numbernumber 檔案的大小。Size of the file.
viewIdviewId 字串string 檢視識別碼。View ID.

回到結構描述資料表Back to Schema table

AudioCard 物件AudioCard object

定義可播放音訊檔案的資訊卡。Defines a card that can play an audio file.

屬性Property 類型Type 描述Description
aspectaspect 字串string image 屬性中指定之縮圖的外觀比例。Aspect ratio of the thumbnail that is specified in the image property. 有效值為 16:94:3Valid values are 16:9 and 4:3.
autoloopautoloop booleanboolean 用於指出最後一個音訊檔案播放完畢後是否要重播音訊清單的旗標。Flag that indicates whether to replay the list of audio files when the last one ends. 將此屬性設為 true 可自動重播音訊檔案;如不重播則設為 falseSet this property to true to automatically replay the audio files; otherwise, false. 預設值為 trueThe default value is true.
autostartautostart booleanboolean 用於指出資訊卡顯示時是否要自動播放音訊的旗標。Flag that indicates whether to automatically play the audio when the card is displayed. 將此屬性設為 true 可自動播放音訊;如不播放則設為 falseSet this property to true to automatically play the audio; otherwise, false. 預設值為 trueThe default value is true.
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
durationduration 字串string 媒體內容的長度,採用 ISO 8601 持續時間格式The length of the media content, in ISO 8601 duration format.
imageimage ThumbnailUrlThumbnailUrl 可指定要在資訊卡上顯示之影像的 ThumbnailUrl 物件。A ThumbnailUrl object that specifies the image to display on the card.
mediamedia MediaUrl[]MediaUrl[] MediaUrl 物件的陣列。Array of MediaUrl objects. 此欄位包含多個 URL 時,每個 URL 都會是相同內容的替代格式。When this field contains more than one URL, each URL is an alternative format of the same content.
shareableshareable booleanboolean 用於指出是否要與他人共用音訊檔案的旗標。Flag that indicates whether the audio files may be shared with others. 將此屬性設為 true 可與他人共用音訊;如不共用則設為 falseSet this property to true if the audio may be shared; otherwise, false. 預設值為 trueThe default value is true.
subtitlesubtitle 字串string 顯示在資訊卡標題下方的子標題。Subtitle to display under the card's title.
texttext 字串string 顯示在資訊卡標題或子標題下方的描述或提示。Description or prompt to display under the card's title or subtitle.
titletitle 字串string 資訊卡的標題。Title of the card.
valuevalue 物件 (object)object 此資訊卡的增補參數。Supplementary parameter for this card.

回到結構描述資料表Back to Schema table

CardAction 物件CardAction object

定義按鈕的可點選動作。Defines a clickable action with a button.

屬性Property 類型Type 描述Description
channelDatachannelData 字串string 與此動作相關聯的通道特定資料。Channel-specific data associated with this action.
displayTextdisplayText 字串string 在點選按鈕後要顯示在聊天動態中的文字。Text to display in the chat feed if the button is clicked.
imageimage 字串string 將在按鈕上顯示於文字標籤旁的影像 URL。Image URL which will appear on the button, next to the text label.
texttext 字串string 動作的文字。Text for the action.
titletitle 字串string 顯示在按鈕上的文字說明。Text description which appears on the button.
typetype 字串string 要執行之動作的類型。Type of action to perform. 如需有效值的清單,請參閱將豐富資訊卡附件新增至訊息For a list of valid values, see Add rich card attachments to messages.
valuevalue 物件 (object)object 動作的增補參數。Supplementary parameter for the action. 此屬性的行為會隨著動作 類型 而有所不同。The behavior of this property will vary according to the action type. 如需詳細資訊,請參閱將豐富資訊卡附件新增至訊息For more information, see Add rich card attachments to messages.

回到結構描述資料表Back to Schema table

CardImage 物件CardImage object

定義要在資訊卡上顯示的影像。Defines an image to display on a card.

屬性Property 類型Type 描述Description
altalt 字串string 影像的描述。Description of the image. 您應加入描述以支援可存取性。You should include the description to support accessibility.
點選tap CardActionCardAction 用於指定使用者點選或按一下影像後要執行之動作的 CardAction 物件。A CardAction object that specifies the action to perform if the user taps or clicks the image.
urlurl 字串string 影像來源的 URL 或影像的 base64 二進位 (例如:data:image/png;base64,iVBORw0KGgo...)。URL to the source of the image or the base64 binary of the image (for example, data:image/png;base64,iVBORw0KGgo...).

回到結構描述資料表Back to Schema table

ChannelAccount 物件ChannelAccount object

定義通道上的 Bot 或使用者帳戶。Defines a bot or user account on the channel.

屬性Property 類型Type 描述Description
aadObjectIdaadObjectId 字串string 此帳戶在 Azure Active Directory 內的物件識別碼。This account's object ID within Azure Active Directory.
idid 字串string 此通道上使用者或聊天機器人的唯一識別碼。Unique ID for the user or bot on this channel.
namename 字串string 聊天機器人或使用者的易記顯示名稱。Display-friendly name of the bot or user.
rolerole 字串string 帳戶背後實體的角色。Role of the entity behind the account. 可以是 使用者BotEither user or bot.

回到結構描述資料表Back to Schema table

ConversationAccount 物件ConversationAccount object

定義通道中的交談。Defines a conversation in a channel.

屬性Property 類型Type 描述Description
aadObjectIdaadObjectId 字串string 此帳戶在 Azure Active Directory (AAD) 內的物件識別碼。This account's object ID within Azure Active Directory (AAD).
conversationTypeconversationType 字串string 指出可區別交談類型 (例如群組或私人) 之通道中的交談類型。Indicates the type of the conversation in channels that distinguish between conversation types (e.g. group, personal).
idid 字串string 可識別交談的識別碼。The ID that identifies the conversation. 此識別碼在每個通道均不重複。The ID is unique per channel. 通道開啟交談時便會設定此識別碼;反之,則由 Bot 將此屬性設為其開啟交談時,Bot 從回應中取回的識別碼 (請參閱建立交談)。If the channel starts the conversation, it sets this ID; otherwise, the bot sets this property to the ID that it gets back in the response when it starts the conversation (see Create Conversation).
isGroupisGroup booleanboolean 用於指出活動產生時交談是否要包含兩位以上參與者的旗標。Flag to indicate whether the conversation contains more than two participants at the time the activity was generated. 設為 true 代表此為群組交談,反之則設為 falseSet to true if this is a group conversation; otherwise, false. 預設值為 falseThe default is false.
namename 字串string 可用來識別交談的顯示名稱。A display name that can be used to identify the conversation.
rolerole 字串string 帳戶背後實體的角色。Role of the entity behind the account. 可以是 使用者BotEither user or bot.
tenantId tenantId 字串string 此交談的租用戶識別碼。This conversation's tenant ID.

回到結構描述資料表Back to Schema table

ConversationMembers 物件ConversationMembers object

定義交談的成員。Defines the members of a conversation.

屬性Property 類型Type 描述Description
idid 字串string 交談識別碼。The conversation ID.
membersmembers ChannelAccount[]ChannelAccount[] 此交談中的成員清單。List of members in this conversation.

回到結構描述資料表Back to Schema table

ConversationParameters 物件ConversationParameters object

定義用來建立新交談的參數。Defines parameters for creating a new conversation.

屬性Property 類型Type 描述Description
activityactivity 活動Activity 交談建立完成時要對其傳送的初始訊息。The initial message to send to the conversation when it is created.
Botbot ChannelAccountChannelAccount 要將訊息路由傳送至聊天機器人所需的通道帳戶資訊。Channel account information needed to route a message to the bot.
channelDatachannelData 物件 (object)object 用於建立交談的通道特定酬載。Channel-specific payload for creating the conversation.
isGroupisGroup booleanboolean 指出此項目是否為群組交談。Indicates whether this is a group conversation.
membersmembers ChannelAccount[]ChannelAccount[] 要將訊息路由傳送給每個使用者所需的通道帳戶資訊。Channel account information needed to route a message to each user.
tenantId tenantId 字串string 應在其中建立交談的租用戶識別碼。The tenant ID in which the conversation should be created.
topicNametopicName 字串string 交談的主題。Topic of the conversation. 僅在通道提供支援時,才可使用此屬性。This property is only used if a channel supports it.

回到結構描述資料表Back to Schema table

ConversationReference 物件ConversationReference object

定義交談中的特定要點。Defines a particular point in a conversation.

屬性Property 類型Type 描述Description
activityIdactivityId 字串string 可唯一識別此物件參照之活動的識別碼。ID that uniquely identifies the activity that this object references.
Botbot ChannelAccountChannelAccount 用於識別此物件參照之交談內 Bot 的 ChannelAccount 物件。A ChannelAccount object that identifies the bot in the conversation that this object references.
channelIdchannelId 字串string 可唯一識別此物件參照之交談內通道的識別碼。An ID that uniquely identifies the channel in the conversation that this object references.
交談 conversation ConversationAccountConversationAccount 用於定義此物件參照之交談的 ChannelAccount 物件。A ConversationAccount object that defines the conversation that this object references.
serviceUrlserviceUrl 字串string 用於指定此物件參照之交談中通道服務端點的 URL。URL that specifies the channel's service endpoint in the conversation that this object references.
useruser ChannelAccountChannelAccount 用於指出此物件參照之交談內使用者的 ChannelAccount 物件。A ChannelAccount object that identifies the user in the conversation that this object references.

回到結構描述資料表Back to Schema table

ConversationResourceResponse 物件ConversationResourceResponse object

定義建立交談的回應。Defines a response to Create Conversation.

屬性Property 類型Type 描述Description
activityIdactivityId 字串string 活動的識別碼 (如果有傳送)。ID of the activity, if sent.
idid 字串string 資源的識別碼。ID of the resource.
serviceUrlserviceUrl 字串string 可能會執行交談相關作業的服務端點。Service endpoint where operations concerning the conversation may be performed.

回到結構描述資料表Back to Schema table

ConversationsResult 物件ConversationsResult object

定義取得交談的結果。Defines the result of Get Conversations.

屬性Property 類型Type 描述Description
交談conversations ConversationMembers[]ConversationMembers[] 每個交談中的成員。The members in each of the conversations.
continuationTokencontinuationToken 字串string 可在取得交談的後續呼叫中使用的接續權杖。The continuation token that can be used in subsequent calls to Get Conversations.

回到結構描述資料表Back to Schema table

實體物件Entity object

關於活動的中繼資料物件。Metadata object pertaining to an activity.

屬性Property 類型Type 描述Description
typetype 字串string 此實體的類型 (RFC 3987 IRI)。Type of this entity (RFC 3987 IRI).

回到結構描述資料表Back to Schema table

Error 物件Error object

代表錯誤資訊的物件。Object representing error information.

屬性Property 類型Type 描述Description
codecode 字串string 錯誤碼。Error code.
innerHttpErrorinnerHttpError InnerHttpErrorInnerHttpError 代表內部 HTTP 錯誤的物件。Object representing the inner HTTP error.
messagemessage 字串string 錯誤的描述。A description of the error.

回到結構描述資料表Back to Schema table

ErrorResponse 物件ErrorResponse object

定義 HTTP API 回應。Defines an HTTP API response.

屬性Property 類型Type 描述Description
errorerror 錯誤Error 含有錯誤相關資訊的 Error 物件。An Error object that contains information about the error.

回到結構描述資料表Back to Schema table

Fact 物件Fact object

定義包含事實的機碼值組。Defines a key-value pair that contains a fact.

屬性Property 類型Type 描述Description
keykey 字串string 事實的名稱。Name of the fact. 例如:簽入For example, Check-in. 此索引鍵在顯示事實的值時做為標籤使用。The key is used as a label when displaying the fact's value.
valuevalue 字串string 事實的值。Value of the fact. 例如:2016 年 10 月 10 日For example, 10 October 2016.

回到結構描述資料表Back to Schema table

GeoCoordinates 物件GeoCoordinates object

定義採用「世界大地坐標系統 (WSG84)」座標的地理位置。Defines a geographical location using World Geodetic System (WSG84) coordinates.

屬性Property 類型Type 描述Description
海拔elevation numbernumber 位置的海拔。Elevation of the location.
緯度latitude numbernumber 位置的緯度。Latitude of the location.
經度longitude numbernumber 位置的經度。Longitude of the location.
namename 字串string 位置的名稱。Name of the location.
typetype 字串string 此物件的類型。The type of this object. 一律設為 GeoCoordinatesAlways set to GeoCoordinates.

回到結構描述資料表Back to Schema table

HeroCard 物件HeroCard object

定義具有大型影像、標題、文字及動作按鈕的資訊卡。Defines a card with a large image, title, text, and action buttons.

屬性Property 類型Type 描述Description
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
imagesimages CardImage[]CardImage[] 用於指定要在資訊卡上顯示之影像的 CardImage 物件陣列。Array of CardImage objects that specifies the image to display on the card. 主圖卡僅包含一個影像。A Hero card contains only one image.
subtitlesubtitle 字串string 顯示在資訊卡標題下方的子標題。Subtitle to display under the card's title.
點選tap CardActionCardAction 用於指定使用者點選或按一下資訊卡後要執行之動作的 CardAction 物件。A CardAction object that specifies the action to perform if the user taps or clicks the card. 此值可與任一按鈕動作相同或選用其他動作。This can be the same action as one of the buttons or a different action.
texttext 字串string 顯示在資訊卡標題或子標題下方的描述或提示。Description or prompt to display under the card's title or subtitle.
titletitle 字串string 資訊卡的標題。Title of the card.

回到結構描述資料表Back to Schema table

InnerHttpError 物件InnerHttpError object

代表內部 HTTP 錯誤的物件。Object representing an inner HTTP error.

屬性Property 類型Type 描述Description
statusCodestatusCode numbernumber 失敗的要求傳回的 HTTP 狀態碼。HTTP status code from the failed request.
bodybody 物件 (object)object 失敗的要求包含的本文。Body from the failed request.

回到結構描述資料表Back to Schema table

MediaEventValue 物件MediaEventValue object

媒體事件的增補參數。Supplementary parameter for media events.

屬性Property 類型Type 描述Description
cardValuecardValue 物件 (object)object 在產生此事件的媒體卡上,於 [值] 欄位中指定的回呼參數。Callback parameter specified in the value field of the media card that originated this event.

回到結構描述資料表Back to Schema table

MediaUrl 物件MediaUrl object

定義媒體檔案來源的 URL。Defines the URL to a media file's source.

屬性Property 類型Type 描述Description
設定檔profile 字串string 用於描述媒體內容的提示。Hint that describes the media's content.
urlurl 字串string 媒體檔案來源的 URL。URL to the source of the media file.

回到結構描述資料表Back to Schema table

Mention 物件Mention object

定義在交談中提及的使用者或 Bot。Defines a user or bot that was mentioned in the conversation.

屬性Property 類型Type 描述Description
提及mentioned ChannelAccountChannelAccount 用於指定提及之使用者或 Bot 的 ChannelAccount 物件。A ChannelAccount object that specifies the user or the bot that was mentioned. 請注意,部分通道 (如 Slack) 會按交談指派名稱,因此在訊息 收件者 屬性中提及的 Bot 名稱,可能與您 註冊 Bot 時指定的控制代碼不同。Note that some channels such as Slack assign names per conversation, so it is possible that your bot's mentioned name (in the message's recipient property) may be different from the handle that you specified when you registered your bot. 不過,這兩者的帳戶識別碼是相同的。However, the account IDs for both would be the same.
texttext 字串string 在交談中提及的使用者或 Bot。The user or bot as mentioned in the conversation. 例如,如果訊息是「 @ColorBot 挑選我的新色彩」,則此屬性會設定為 @ ColorBotFor example, if the message is "@ColorBot pick me a new color," this property would be set to @ColorBot. 並非所有通道都能設定此屬性。Not all channels set this property.
typetype 字串string 此物件的類型。This object's type. 一律設為 提及Always set to Mention.

回到結構描述資料表Back to Schema table

MessageReaction 物件MessageReaction object

定義對訊息的回應。Defines a reaction to a message.

屬性Property 類型Type 描述Description
typetype 字串string 反應的類型。Type of reaction. 可以是 likeplusOneEither like or plusOne.

回到結構描述資料表Back to Schema table

PagedMembersResult 物件PagedMembersResult object

取得交談分頁成員所傳回的成員頁面。Page of members returned by Get Conversation Paged Members.

屬性Property 類型Type 描述Description
continuationTokencontinuationToken 字串string 可在取得交談分頁成員的後續呼叫中使用的接續權杖。The continuation token that can be used in subsequent calls to Get Conversation Paged Members.
membersmembers ChannelAccount[]ChannelAccount[] 交談成員的陣列。An array of conversation members.

回到結構描述資料表Back to Schema table

Place 物件Place object

定義在交談中提及的地點。Defines a place that was mentioned in the conversation.

屬性Property 類型Type 描述Description
addressaddress 物件 (object)object 地點的地址。Address of a place. 此屬性可以是 字串PostalAddress 類型的複雜物件。This property can be a string or a complex object of type PostalAddress.
地理區域geo GeoCoordinatesGeoCoordinates 用於指定地點之地理座標的 GeoCoordinates 物件。A GeoCoordinates object that specifies the geographical coordinates of the place.
hasMaphasMap 物件 (object)object 對應至地點。Map to the place. 此屬性可以是 字串Map 類型的複雜物件。This property can be a string (URL) or a complex object of type Map.
namename 字串string 地點的名稱。Name of the place.
typetype 字串string 此物件的類型。This object's type. 一律設為 地點Always set to Place.

回到結構描述資料表Back to Schema table

ReceiptCard 物件ReceiptCard object

定義內含購買收據的資訊卡。Defines a card that contains a receipt for a purchase.

屬性Property 類型Type 描述Description
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
factsfacts Fact[]Fact[] 用於指定購買相關資訊的 Fact 物件陣列。Array of Fact objects that specify information about the purchase. 例如,飯店住宿收據的明細清單將列出入住日期和退房日期。For example, the list of facts for a hotel stay receipt might include the check-in date and check-out date. 此通道可決定您能指定的事實數目。The channel determines the number of facts that you may specify.
itemsitems ReceiptItem[]ReceiptItem[] 用於指定已購項目的 ReceiptItem 物件陣列Array of ReceiptItem objects that specify the purchased items
點選tap CardActionCardAction 用於指定使用者點選或按一下資訊卡後要執行之動作的 CardAction 物件。A CardAction object that specifies the action to perform if the user taps or clicks the card. 此值可與任一按鈕動作相同或選用其他動作。This can be the same action as one of the buttons or a different action.
taxtax 字串string 用於指定該筆購買金額須支付之稅金的貨幣格式字串。A currency-formatted string that specifies the amount of tax applied to the purchase.
titletitle 字串string 顯示在收據頂端的標題。Title displayed at the top of the receipt.
totaltotal 字串string 用於指定購買總額 (包括適用稅金) 的貨幣格式字串。A currency-formatted string that specifies the total purchase price, including all applicable taxes.
vatvat 字串string 一個貨幣格式字串,用來指定購買價格須支付的加值稅 (VAT) 金額。A currency-formatted string that specifies the amount of value-added tax (VAT) applied to the purchase price.

回到結構描述資料表Back to Schema table

ReceiptItem 物件ReceiptItem object

定義收據內的明細項目。Defines a line item within a receipt.

屬性Property 類型Type 描述Description
imageimage CardImageCardImage 用於指定要顯示於明細項目旁之縮圖影像的 CardImage 物件。A CardImage object that specifies thumbnail image to display next to the line item.
priceprice 字串string 用於指定所有已購單位之總價的貨幣格式字串。A currency-formatted string that specifies the total price of all units purchased.
quantityquantity 字串string 用於指定已購單位數量的數值字串。A numeric string that specifies the number of units purchased.
subtitlesubtitle 字串string 顯示於明細項目標題下方的子標題。Subtitle to be displayed under the line item's title.
點選tap CardActionCardAction 用於指定使用者點選或按一下明細項目後要執行之動作的 CardAction 物件。A CardAction object that specifies the action to perform if the user taps or clicks the line item.
texttext 字串string 明細項目的描述。Description of the line item.
titletitle 字串string 明細項目的標題。Title of the line item.

回到結構描述資料表Back to Schema table

ResourceResponse 物件ResourceResponse object

定義包含資源識別碼的回應。Defines a response that contains a resource ID.

屬性Property 類型Type 描述Description
idid 字串string 可唯一識別資源的識別碼。ID that uniquely identifies the resource.

回到結構描述資料表Back to Schema table

SemanticAction 物件SemanticAction object

定義程式設計動作的參考。Defines a reference to a programmatic action.

屬性Property 類型Type 描述Description
entitiesentities 物件 (object)object 每個屬性的值皆為實體物件的物件。An object where the value of each property is an Entity object.
idid 字串string 此動作的識別碼。ID of this action.
statestate 字串string 此動作的狀態。State of this action. 允許的值:開始繼續完成Allowed values: start, continue, done.

回到結構描述資料表Back to Schema table

SignInCard 物件SignInCard object

定義可讓使用者登入至服務的資訊卡。Defines a card that lets a user sign in to a service.

屬性Property 類型Type 描述Description
buttonsbuttons CardAction[]CardAction[] 可讓使用者登入服務的 CardAction 物件。Array of CardAction objects that enable the user to sign in to a service. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
texttext 字串string 要加入登入卡的描述或提示。Description or prompt to include on the sign in card.

回到結構描述資料表Back to Schema table

SuggestedActions 物件SuggestedActions object

定義可讓使用者從中選擇的選項。Defines the options from which a user can choose.

屬性Property 類型Type 描述Description
actionsactions CardAction[]CardAction[] 用於定義建議動作的 CardAction 物件。Array of CardAction objects that define the suggested actions.
toto string[]string[] 此字串陣列包含可檢視建議動作之收件者的識別碼。Array of strings that contains the IDs of the recipients to whom the suggested actions should be displayed.

回到結構描述資料表Back to Schema table

TextHighlight 物件TextHighlight object

參照其他欄位內的內容子字串。Refers to a substring of content within another field.

屬性Property 類型Type 描述Description
occurrenceoccurrence numbernumber 文字欄位在參考的文字內出現的次數 (如果出現多次)。Occurrence of the text field within the referenced text, if multiple exist.
texttext 字串string 定義要醒目提示的文字片段。Defines the snippet of text to highlight.

回到結構描述資料表Back to Schema table

ThumbnailCard 物件ThumbnailCard object

定義具有縮圖影像、標題、文字和動作按鈕的資訊卡。Defines a card with a thumbnail image, title, text, and action buttons.

屬性Property 類型Type 描述Description
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
imagesimages CardImage[]CardImage[] 用於指定要在資訊卡上顯示之縮圖影像的 CardImage 物件。Array of CardImage objects that specify thumbnail images to display on the card. 此通道可決定您能指定的縮圖影像數目。The channel determines the number of thumbnail images that you may specify.
subtitlesubtitle 字串string 顯示在資訊卡標題下方的子標題。Subtitle to display under the card's title.
點選tap CardActionCardAction 用於指定使用者點選或按一下資訊卡後要執行之動作的 CardAction 物件。A CardAction object that specifies the action to perform if the user taps or clicks the card. 此值可與任一按鈕動作相同或選用其他動作。This can be the same action as one of the buttons or a different action.
texttext 字串string 顯示在資訊卡標題或子標題下方的描述或提示。Description or prompt to display under the card's title or subtitle.
titletitle 字串string 資訊卡的標題。Title of the card.

回到結構描述資料表Back to Schema table

ThumbnailUrl 物件ThumbnailUrl object

定義影像來源的 URL。Defines the URL to an image's source.

屬性Property 類型Type 描述Description
altalt 字串string 影像的描述。Description of the image. 您應加入描述以支援可存取性。You should include the description to support accessibility.
urlurl 字串string 影像來源的 URL 或影像的 base64 二進位 (例如:data:image/png;base64,iVBORw0KGgo...)。URL to the source of the image or the base64 binary of the image (for example, data:image/png;base64,iVBORw0KGgo...).

回到結構描述資料表Back to Schema table

Transcript 物件Transcript object

要使用傳送交談記錄上傳的活動集合。A collection of activities to be uploaded using Send Conversation History.

屬性Property 類型Type 描述Description
活動activities arrayarray Activity 物件的陣列。An array of Activity objects. 這些物件各自都應該擁有唯一的識別碼和時間戳記。They should each have a unique ID and timestamp.

回到結構描述資料表Back to Schema table

VideoCard 物件VideoCard object

定義可播放影片的資訊卡。Defines a card that can play videos.

屬性Property 類型Type 描述Description
aspectaspect 字串string 影片的外觀比例。Aspect ratio of the video. 可以是 16:94:3Either 16:9 or 4:3.
autoloopautoloop booleanboolean 用於指出最後一個影片播放完畢後是否要重播影片清單的旗標。Flag that indicates whether to replay the list of videos when the last one ends. 將此屬性設為 true 可自動重播影片;如不重播則設為 falseSet this property to true to automatically replay the videos; otherwise, false. 預設值為 trueThe default value is true.
autostartautostart booleanboolean 用於指出資訊卡顯示時是否要自動播放影片的旗標。Flag that indicates whether to automatically play the videos when the card is displayed. 將此屬性設為 true 可自動播放影片;如不播放則設為 falseSet this property to true to automatically play the videos; otherwise, false. 預設值為 trueThe default value is true.
buttonsbuttons CardAction[]CardAction[] 可讓使用者執行一或多個動作的 CardAction 物件陣列。Array of CardAction objects that enable the user to perform one or more actions. 此通道可決定您能指定的按鈕數目。The channel determines the number of buttons that you may specify.
durationduration 字串string 媒體內容的長度,採用 ISO 8601 持續時間格式The length of the media content, in ISO 8601 duration format.
imageimage ThumbnailUrlThumbnailUrl 可指定要在資訊卡上顯示之影像的 ThumbnailUrl 物件。A ThumbnailUrl object that specifies the image to display on the card.
mediamedia MediaUrl[]MediaUrl[] MediaUrl 的陣列。Array of MediaUrl. 此欄位包含多個 URL 時,每個 URL 都會是相同內容的替代格式。When this field contains more than one URL, each URL is an alternative format of the same content.
shareableshareable booleanboolean 用於指出是否要與他人共用影片的旗標。Flag that indicates whether the videos may be shared with others. 將此屬性設為 true 可與他人共用影片;如不共用則設為 falseSet this property to true if the videos may be shared; otherwise, false. 預設值為 trueThe default value is true.
subtitlesubtitle 字串string 顯示在資訊卡標題下方的子標題。Subtitle to display under the card's title.
texttext 字串string 顯示在資訊卡標題或子標題下方的描述或提示。Description or prompt to display under the card's title or subtitle.
titletitle 字串string 資訊卡的標題。Title of the card.
valuevalue 物件 (object)object 此資訊卡的增補參數Supplementary parameter for this card

回到結構描述資料表Back to Schema table