Skip to content

Commit 6d3ea9d

Browse files
author
Kyle Delaney
authored
Conversation operations in REST API reference
- add documentation for Get Conversations, Delete Conversation Member, and Send Conversation History - add documentation for their related objects in the schema section - fix miscellaneous errors in the document while leaving major fixes for other commits Fixes #1179
1 parent 8725085 commit 6d3ea9d

File tree

1 file changed

+113
-35
lines changed

1 file changed

+113
-35
lines changed

‎articles/rest-api/bot-framework-rest-connector-api-reference.md‎

Lines changed: 113 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -121,14 +121,17 @@ Use these operations to create conversations, send messages (activities), and ma
121121

122122
| Operation | Description |
123123
|----|----|
124-
| [Create Conversation](#create-conversation) | Creates a new conversation. |
125-
| [Send to Conversation](#send-to-conversation) | Sends an activity (message) to the end of the specified conversation. |
126-
| [Reply to Activity](#reply-to-activity) | Sends an activity (message) to the specified conversation, as a reply to the specified activity. |
124+
| [Create Conversation](#create-conversation) | Creates a new conversation. |
125+
| [Send to Conversation](#send-to-conversation) | Sends an activity (message) to the end of the specified conversation. |
126+
| [Reply to Activity](#reply-to-activity) | Sends an activity (message) to the specified conversation, as a reply to the specified activity. |
127+
| [Get Conversations](#get-conversations) | Gets a list of conversations the bot has participated in. |
127128
| [Get Conversation Members](#get-conversation-members) | Gets the members of the specified conversation. |
128129
| [Get Conversation Paged Members](#get-conversation-paged-members) | Gets the members of the specified conversation one page at a time. |
129-
| [Get Activity Members](#get-activity-members) | Gets the members of the specified activity within the specified conversation. |
130-
| [Update Activity](#update-activity) | Updates an existing activity. |
131-
| [Delete Activity](#delete-activity) | Deletes an existing activity. |
130+
| [Get Activity Members](#get-activity-members) | Gets the members of the specified activity within the specified conversation. |
131+
| [Update Activity](#update-activity) | Updates an existing activity. |
132+
| [Delete Activity](#delete-activity) | Deletes an existing activity. |
133+
| [Delete Conversation Member](#delete-conversation-member) | Removes a member from a conversation. |
134+
| [Send Conversation History](#send-conversation-history) | Uploads a transcript of past activities to the conversation. |
132135
| [Upload Attachment to Channel](#upload-attachment-to-channel) | Uploads an attachment directly into a channel's blob storage. |
133136

134137
### Create Conversation
@@ -140,7 +143,7 @@ POST /v3/conversations
140143
| | |
141144
|----|----|
142145
| **Request body** | A [Conversation](#conversation-object) object |
143-
| **Returns** | A [ResourceResponse](#resourceresponse-object) object |
146+
| **Returns** | A [ConversationResourceResponse](#conversationresourceresponse-object) object |
144147

145148
### Send to Conversation
146149
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](#reply-to-activity) instead.
@@ -164,6 +167,17 @@ POST /v3/conversations/{conversationId}/activities/{activityId}
164167
| **Request body** | An [Activity](#activity-object) object |
165168
| **Returns** | An [Identification](#identification-object) object |
166169

170+
### Get Conversations
171+
Gets a list of conversations the bot has participated in.
172+
```http
173+
GET /v3/conversations?continuationToken={continuationToken}
174+
```
175+
176+
| | |
177+
|----|----|
178+
| **Request body** | n/a |
179+
| **Returns** | A [ConversationsResult](#conversationsresult-object) object |
180+
167181
### Get Conversation Members
168182
Gets the members of the specified conversation.
169183
```http
@@ -178,13 +192,13 @@ GET /v3/conversations/{conversationId}/members
178192
### Get Conversation Paged Members
179193
Gets the members of the specified conversation one page at a time.
180194
```http
181-
GET /v3/conversations/{conversationId}/pagedmembers
195+
GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
182196
```
183197

184198
| | |
185199
|----|----|
186200
| **Request body** | n/a |
187-
| **Returns** | An array of [ChannelAccount](#channelaccount-object) objects and a continuation token that can be used to get more values|
201+
| **Returns** | An array of [ChannelAccount](#channelaccount-object) objects and a continuation token that can be used to get more values |
188202

189203
### Get Activity Members
190204
Gets the members of the specified activity within the specified conversation.
@@ -219,8 +233,30 @@ DELETE /v3/conversations/{conversationId}/activities/{activityId}
219233
| **Request body** | n/a |
220234
| **Returns** | An HTTP Status code that indicates the outcome of the operation. Nothing is specified in the body of the response. |
221235

236+
### Delete Conversation Member
237+
Removes a member from a conversation. If that member was the last member of the conversation, the conversation will also be deleted.
238+
```http
239+
DELETE /v3/conversations/{conversationId}/members/{memberId}
240+
```
241+
242+
| | |
243+
|----|----|
244+
| **Request body** | n/a |
245+
| **Returns** | An HTTP Status code that indicates the outcome of the operation. Nothing is specified in the body of the response. |
246+
247+
### Send Conversation History
248+
Uploads a transcript of past activities to the conversation so that the client can render them.
249+
```http
250+
POST /v3/conversations/{conversationId}/activities/history
251+
```
252+
253+
| | |
254+
|----|----|
255+
| **Request body** | A [Transcript](#transcript-object) object. |
256+
| **Returns** | A [ResourceResponse](#resourceresponse-object) object. |
257+
222258
### Upload Attachment to Channel
223-
Uploads an attachment for the specified conversation directly into a channel's blob storage. This enables you to store data in a compliant store.
259+
Uploads an attachment for the specified conversation directly into a channel's blob storage. This enables you to store data in a compliant store.
224260
```http
225261
POST /v3/conversations/{conversationId}/attachments
226262
```
@@ -359,7 +395,7 @@ Schema defines the object and its properties that your bot can use to communicat
359395
| [Activity object](#activity-object) | Defines a message that is exchanged between bot and user. |
360396
| [AnimationCard object](#animationcard-object) | Defines a card that can play animated GIFs or short videos. |
361397
| [Attachment object](#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. |
362-
| [AttachmentData object](#attachmentdata-object) |Describes an attachment data. |
398+
| [AttachmentData object](#attachmentdata-object) | Describes an attachment data. |
363399
| [AttachmentInfo object](#attachmentinfo-object) | Describes an attachment. |
364400
| [AttachmentView object](#attachmentview-object) | Defines a attachment view. |
365401
| [AttachmentUpload object](#attachmentupload-object) | Defines an attachment to be uploaded. |
@@ -370,30 +406,33 @@ Schema defines the object and its properties that your bot can use to communicat
370406
| [ChannelAccount object](#channelaccount-object) | Defines a bot or user account on the channel. |
371407
| [Conversation object](#conversation-object) | Defines a conversation, including the bot and users that are included within the conversation. |
372408
| [ConversationAccount object](#conversationaccount-object) | Defines a conversation in a channel. |
409+
| [ConversationMembers object](#conversationmembers-object) | Defines the members of a conversation. |
373410
| [ConversationParameters object](#conversationparameters-object) | Define parameters for creating a new conversation |
374411
| [ConversationReference object](#conversationreference-object) | Defines a particular point in a conversation. |
375-
| [ConversationResourceResponse object](#conversationresourceresponse-object) | "A response containing a resource |
412+
| [ConversationResourceResponse object](#conversationresourceresponse-object) | Defines a response to [Create Conversation](#create-conversation). |
413+
| [ConversationsResult object](#conversationsresult-object) | Defines the result of a call to [Get Conversations](#get-conversations). |
376414
| [Entity object](#entity-object) | Defines an entity object. |
377415
| [Error object](#error-object) | Defines an error. |
378416
| [ErrorResponse object](#errorresponse-object) | Defines an HTTP API response. |
379417
| [Fact object](#fact-object) | Defines a key-value pair that contains a fact. |
380-
| [Geocoordinates object](#geocoordinates-object) | Defines a geographical location using World Geodetic System (WSG84) coordinates. |
418+
| [GeoCoordinates object](#geocoordinates-object) | Defines a geographical location using World Geodetic System (WSG84) coordinates. |
381419
| [HeroCard object](#herocard-object) | Defines a card with a large image, title, text, and action buttons. |
382420
| [Identification object](#identification-object) | Identifies a resource. |
383-
| [MediaEventValue object](#mediaeventvalue-object) |Supplementary parameter for media events.|
421+
| [MediaEventValue object](#mediaeventvalue-object) | Supplementary parameter for media events. |
384422
| [MediaUrl object](#mediaurl-object) | Defines the URL to a media file's source. |
385423
| [Mention object](#mention-object) | Defines a user or bot that was mentioned in the conversation. |
386424
| [MessageReaction object](#messagereaction-object) | Defines a reaction to a message. |
387425
| [Place object](#place-object) | Defines a place that was mentioned in the conversation. |
388426
| [ReceiptCard object](#receiptcard-object) | Defines a card that contains a receipt for a purchase. |
389427
| [ReceiptItem object](#receiptitem-object) | Defines a line item within a receipt. |
390428
| [ResourceResponse object](#resourceresponse-object) | Defines a resource. |
429+
| [SemanticAction object](#semanticaction-object) | Defines a reference to a programmatic action. |
391430
| [SignInCard object](#signincard-object) | Defines a card that lets a user sign in to a service. |
392431
| [SuggestedActions object](#suggestedactions-object) | Defines the options from which a user can choose. |
393432
| [ThumbnailCard object](#thumbnailcard-object) | Defines a card with a thumbnail image, title, text, and action buttons. |
394433
| [ThumbnailUrl object](#thumbnailurl-object) | Defines the URL to an image's source. |
434+
| [Transcript object](#transcript-object) | A collection of activities to be uploaded using [Send Conversation History](#send-conversation-history). |
395435
| [VideoCard object](#videocard-object) | Defines a card that can play videos. |
396-
| [SemanticAction object](#semanticaction-object) | Defines a reference to a programmatic action. |
397436

398437
### Activity object
399438
Defines a message that is exchanged between bot and user.<br/><br/>
@@ -467,7 +506,7 @@ Defines additional information to include in the message. An attachment may be a
467506
<a href="#objects">Back to Schema table</a>
468507

469508
### AttachmentData object
470-
Describes an attachment data.
509+
Describes an attachment data.<br/><br/>
471510

472511
| Property | Type | Description |
473512
|----|----|----|
@@ -476,6 +515,8 @@ Describes an attachment data.
476515
| **thumbnailBase64** | string | Attachment thumbnail content. |
477516
| **type** | string | Content-type of the attachment. |
478517

518+
<a href="#objects">Back to Schema table</a>
519+
479520
### AttachmentInfo object
480521
Describes an attachment.<br/><br/>
481522

@@ -595,15 +636,25 @@ Defines a conversation in a channel.<br/><br/>
595636

596637
| Property | Type | Description |
597638
|----|----|----|
598-
| **id** | string | The ID that identifies the conversation. The ID is unique per channel. If the channel starts the conversion, 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 Starting a conversation). |
639+
| **id** | string | The ID that identifies the conversation. The ID is unique per channel. 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 Starting a conversation). |
599640
| **isGroup** | boolean | Flag to indicate whether the conversation contains more than two participants at the time the activity was generated. Set to **true** if this is a group conversation; otherwise, **false**. The default is **false**. |
600641
| **name** | string | A display name that can be used to identify the conversation. |
601642
| **conversationType** | string | Indicates the type of the conversation in channels that distingish between conversation types (e.g.: group, personal). |
602643

603644
<a href="#objects">Back to Schema table</a>
604645

646+
### ConversationMembers object
647+
Defines the members of a conversation.<br/><br/>
648+
649+
| Property | Type | Description |
650+
|----|----|----|
651+
| **id** | string | The conversation ID. |
652+
| **members** | array | An array of [ChannelAccount](#channelaccount-object) objects. |
653+
654+
<a href="#objects">Back to Schema table</a>
655+
605656
### ConversationParameters object
606-
Define parameters for creating a new conversation
657+
Define parameters for creating a new conversation.<br/><br/>
607658

608659
| Property | Type | Description |
609660
|----|----|----|
@@ -614,6 +665,8 @@ Define parameters for creating a new conversation
614665
| **activity** | [Activity](#activity-object) | (optional) Use this activity as the initial message to the conversation when creating a new conversation. |
615666
| **channelData** | object | Channel specific payload for creating the conversation. |
616667

668+
<a href="#objects">Back to Schema table</a>
669+
617670
### ConversationReference object
618671
Defines a particular point in a conversation.<br/><br/>
619672

@@ -629,16 +682,28 @@ Defines a particular point in a conversation.<br/><br/>
629682
<a href="#objects">Back to Schema table</a>
630683

631684
### ConversationResourceResponse object
632-
Defines a response that contains a resource.
685+
Defines a response to [Create Conversation](#create-conversation).<br/><br/>
633686

634687
| Property | Type | Description |
635688
|----|----|----|
636689
| **activityId** | string | ID of the activity. |
637690
| **id** | string | ID of the resource. |
638691
| **serviceUrl** | string | Service endpoint. |
639692

693+
<a href="#objects">Back to Schema table</a>
694+
695+
### ConversationsResult object
696+
Defines the result of [Get Conversations](#get-conversations).<br/><br/>
697+
698+
| Property | Type | Description |
699+
|----|----|----|
700+
| **continuationToken** | string | The continuation token that can be used in subsequent calls to [Get Conversations](#get-conversations). |
701+
| **conversations** | array | An array of [ConversationMembers](#conversationmembers-object) objects |
702+
703+
<a href="#objects">Back to Schema table</a>
704+
640705
### Error object
641-
Defines an error.<br/><br/>
706+
Defines an error.<br/><br/>
642707

643708
| Property | Type | Description |
644709
|----|----|----|
@@ -648,12 +713,13 @@ Defines an error.<br/><br/>
648713
<a href="#objects">Back to Schema table</a>
649714

650715
### Entity object
651-
Defines an entity object.
716+
Defines an entity object.<br/><br/>
652717

653718
| Property | Type | Description |
654719
|----|----|----|
655720
| **type** | string | Entity type. Typically contain types from schema.org. |
656721

722+
<a href="#objects">Back to Schema table</a>
657723

658724
### ErrorResponse object
659725
Defines an HTTP API response.<br/><br/>
@@ -674,7 +740,7 @@ Defines a key-value pair that contains a fact.<br/><br/>
674740

675741
<a href="#objects">Back to Schema table</a>
676742

677-
### Geocoordinates object
743+
### GeoCoordinates object
678744
Defines a geographical location using World Geodetic System (WSG84) coordinates.<br/><br/>
679745

680746
| Property | Type | Description |
@@ -712,12 +778,14 @@ Identifies a resource.<br/><br/>
712778
<a href="#objects">Back to Schema table</a>
713779

714780
### MediaEventValue object
715-
Supplementary parameter for media events.
781+
Supplementary parameter for media events.<br/><br/>
716782

717783
| Property | Type | Description |
718784
|----|----|----|
719785
| **cardValue** | object | Callback parameter specified in the **Value** field of the media card that originated this event. |
720786

787+
<a href="#objects">Back to Schema table</a>
788+
721789
### MediaUrl object
722790
Defines the URL to a media file's source.<br/><br/>
723791

@@ -742,12 +810,14 @@ Defines a user or bot that was mentioned in the conversation.<br/><br/>
742810
<a href="#objects">Back to Schema table</a>
743811

744812
### MessageReaction object
745-
Defines a reaction to a message.
813+
Defines a reaction to a message.<br/><br/>
746814

747815
| Property | Type | Description |
748816
|----|----|----|
749817
| **type** | string | Type of reaction. |
750818

819+
<a href="#objects">Back to Schema table</a>
820+
751821
### Place object
752822
Defines a place that was mentioned in the conversation.<br/><br/>
753823

@@ -795,13 +865,22 @@ Defines a line item within a receipt.<br/><br/>
795865
### ResourceResponse object
796866
Defines a response that contains a resource ID.<br/><br/>
797867

798-
799868
| Property | Type | Description |
800869
|---------------------|--------|-------------------------------------------|
801870
| <strong>id</strong> | string | ID that uniquely identifies the resource. |
802871

803872
<a href="#objects">Back to Schema table</a>
804873

874+
### SemanticAction object
875+
Defines a reference to a programmatic action.<br/><br/>
876+
877+
| Property | Type | Description |
878+
|----|----|----|
879+
| **id** | string | ID of this action |
880+
| **entities** | [Entity](#entity-object) | Entities associated with this action |
881+
882+
<a href="#objects">Back to Schema table</a>
883+
805884
### SignInCard object
806885
Defines a card that lets a user sign in to a service.<br/><br/>
807886

@@ -846,6 +925,15 @@ Defines the URL to an image's source.<br/><br/>
846925

847926
<a href="#objects">Back to Schema table</a>
848927

928+
### Transcript object
929+
A collection of activities to be uploaded using [Send Conversation History](#send-conversation-history).<br/><br/>
930+
931+
| Property | Type | Description |
932+
|----|----|----|
933+
| **activities** | array | An array of [Activity](#activity-object) objects. They should each have a unique ID and timestamp. |
934+
935+
<a href="#objects">Back to Schema table</a>
936+
849937
### VideoCard object
850938
Defines a card that can play videos.<br/><br/>
851939

@@ -865,13 +953,3 @@ Defines a card that can play videos.<br/><br/>
865953
| **value** | object | Supplementary parameter for this card|
866954

867955
<a href="#objects">Back to Schema table</a>
868-
869-
### SemanticAction object
870-
Defines a reference to a programmatic action.<br/><br/>
871-
872-
| Property | Type | Description |
873-
|----|----|----|
874-
| **id** | string | ID of this action |
875-
| **entities** | [Entity](#entity-object) | Entities associated with this action |
876-
877-
<a href="#objects">Back to Schema table</a>

0 commit comments

Comments
 (0)