Bot Framework 커넥트or 서비스에 대한 API 참조

아티클
10/27/2023

참고 항목

REST API는 SDK와 동일하지 않습니다. REST API는 표준 REST 통신을 허용하도록 제공되지만 Bot Framework와 상호 작용하는 기본 방법은 SDK입니다.

Bot Framework 내에서 Bot 커넥트or 서비스를 사용하면 봇이 Bot Framework 포털에 구성된 채널에서 사용자와 메시지를 교환할 수 있습니다. 이 서비스는 HTTPS를 통해 업계 표준 REST 및 JSON을 사용합니다.

기본 URI

사용자가 봇에 메시지를 보내면 들어오는 요청에는 봇이 응답을 보내야 하는 엔드포인트를 지정하는 serviceUrl 속성이 있는 Activity 개체가 포함됩니다. Bot 커넥트or 서비스에 액세스하려면 이 값을 API 요청에 대한 기본 URI로 사용합니다serviceUrl.

채널에 대한 서비스 URL이 아직 없는 경우 서비스 URL로 사용합니다 https://smba.trafficmanager.net/teams/ . 자세한 내용은 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 상태 코드	의미
200	요청이 성공했습니다.
201	요청이 성공했습니다.
202	처리를 위해 요청이 수락되었습니다.
204	요청이 성공했지만 콘텐츠가 반환되지 않았습니다.
400	요청의 형식이 잘못되었거나 요청이 잘못되었습니다.
401	봇은 아직 인증되지 않았습니다.
403	봇은 요청된 작업을 수행할 권한이 없습니다.
404	요청된 리소스를 찾을 수 없습니다.
405	채널은 요청된 작업을 지원하지 않습니다.
500	내부 서버 오류가 발생했습니다.
503	서비스를 일시적으로 사용할 수 없습니다.

Errors

4xx 범위 또는 5xx 범위의 HTTP 상태 코드를 지정하는 모든 응답에서 오류 관련 정보를 제공하는 응답 본문에는 ErrorResponse 개체가 포함됩니다. 4xx 범위에서 오류 응답을 수신하는 경우 ErrorResponse 개체를 검사하여 오류의 원인을 확인하고 요청을 다시 제출하기 전에 문제를 해결합니다.

대화 작업

이러한 작업을 사용하여 대화를 만들고, 메시지(활동)를 보내고, 대화 내용을 관리합니다.

Important

모든 채널이 모든 엔드포인트를 지원하는 것은 아닙니다. 그러나 모든 채널은 활동 엔드포인트에 대한 회신을 지원해야 합니다.

예를 들어 직접 회선 및 웹 채팅 대화 가져오기 엔드포인트만 지원합니다.

연산	설명
대화 만들기	새 대화를 만듭니다.
삭제 작업	기존 활동을 삭제합니다.
대화 멤버 삭제	대화에서 멤버를 제거합니다.
활동 멤버 가져오기	지정된 대화 내에서 지정된 활동의 멤버를 가져옵니다.
대화 멤버 가져오기	대화의 멤버에 대한 세부 정보를 가져옵니다.
대화 구성원 가져오기	지정된 대화의 멤버를 가져옵니다.
대화 페이징 멤버 가져오기	지정한 대화의 멤버를 한 번에 한 페이지씩 가져옵니다.
대화 가져오기	봇이 참여한 대화 목록을 가져옵니다.
활동에 회신	지정된 활동에 대한 회신으로 지정된 대화에 활동(메시지)을 보냅니다.
대화 기록 보내기	대화에 과거 활동의 대본을 업로드합니다.
대화로 보내기	지정된 대화의 끝에 활동(메시지)을 보냅니다.
업데이트 작업	기존 활동을 업데이트.
채널에 첨부 파일 업로드	첨부 파일을 채널의 Blob Storage에 직접 업로드합니다.

대화 만들기

새 대화를 만듭니다.

POST /v3/conversations

내용	설명
요청 본문	ConversationParameters 개체
반환	ConversationResourceResponse 개체

활동 삭제

일부 채널에서는 기존 활동을 삭제할 수 있습니다. 성공하면 이 작업은 지정된 대화에서 지정된 활동을 제거합니다.

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

내용	설명
요청 본문	해당 없음
반환	작업의 결과를 나타내는 HTTP 상태 코드입니다. 응답 본문에는 아무것도 지정되지 않습니다.

대화 멤버 삭제

대화에서 멤버를 제거합니다. 해당 멤버가 대화의 마지막 멤버인 경우 대화도 삭제됩니다.

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

내용	설명
요청 본문	해당 없음
반환	작업의 결과를 나타내는 HTTP 상태 코드입니다. 응답 본문에는 아무것도 지정되지 않습니다.

활동 멤버 가져오기

지정된 대화 내에서 지정된 활동의 멤버를 가져옵니다.

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

내용	설명
요청 본문	해당 없음
반환	ChannelAccount 개체의 배열

대화 가져오기

봇이 참여한 대화 목록을 가져옵니다.

GET /v3/conversations?continuationToken={continuationToken}

내용	설명
요청 본문	해당 없음
반환	ConversationsResult 개체

대화 멤버 가져오기

특정 대화의 특정 멤버에 대한 세부 정보를 가져옵니다.

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

내용	설명
요청 본문	해당 없음
반환	멤버에 대한 ChannelAccount 개체입니다.

대화 구성원 가져오기

지정된 대화의 멤버를 가져옵니다.

GET /v3/conversations/{conversationId}/members

내용	설명
요청 본문	해당 없음
반환	대화 멤버에 대한 ChannelAccount 개체의 배열입니다.

대화 페이징 멤버 가져오기

지정한 대화의 멤버를 한 번에 한 페이지씩 가져옵니다.

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

내용	설명
요청 본문	해당 없음
반환	PagedMembersResult 개체

활동에 회신

지정된 활동에 대한 회신으로 지정된 대화에 활동(메시지)을 보냅니다. 채널에서 지원하는 경우 활동이 다른 활동에 대한 응답으로 추가됩니다. 채널이 중첩된 회신을 지원하지 않는 경우 이 작업은 대화에 보내기와 같이 동작합니다.

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

내용	설명
요청 본문	Activity 개체
반환	ResourceResponse 개체

대화 기록 보내기

클라이언트가 렌더링할 수 있도록 과거 활동의 기록을 대화에 업로드합니다.

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

내용	설명
요청 본문	Transcript 개체
반환	ResourceResponse 개체입니다.

대화로 보내기

지정된 대화에 활동(메시지)을 보냅니다. 활동은 채널의 타임스탬프 또는 의미 체계에 따라 대화의 끝에 추가됩니다. 대화 내의 특정 메시지에 회신하려면 대신 활동에 회신을 사용합니다.

POST /v3/conversations/{conversationId}/activities

내용	설명
요청 본문	Activity 개체
반환	ResourceResponse 개체

업데이트 작업

일부 채널을 사용하면 기존 활동을 편집하여 봇 대화의 새 상태를 반영할 수 있습니다. 예를 들어 사용자가 단추 중 하나를 클릭하면 대화의 메시지에서 단추를 제거할 수 있습니다. 성공하면 이 작업은 지정한 대화 내에서 지정한 활동을 업데이트합니다.

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

내용	설명
요청 본문	Activity 개체
반환	ResourceResponse 개체

채널에 첨부 파일 업로드

지정된 대화에 대한 첨부 파일을 채널의 Blob Storage에 직접 업로드합니다. 이렇게 하면 규격 저장소에 데이터를 저장할 수 있습니다.

POST /v3/conversations/{conversationId}/attachments

내용	설명
요청 본문	AttachmentData 개체입니다.
반환	ResourceResponse 개체입니다. ID 속성은 첨부 파일 정보 가져오기 작업 및 첨부 파일 가져오기 작업과 함께 사용할 수 있는 첨부 파일 ID를 지정합니다.

첨부 파일 작업

첨부 파일에 대한 정보와 파일 자체의 이진 데이터를 검색하는 데 사용하는 작업은 다음과 같습니다.

연산	설명
첨부 파일 정보 가져오기	파일 이름, 파일 형식 및 사용 가능한 보기(예: 원본 또는 썸네일)를 포함하여 지정된 첨부 파일에 대한 정보를 가져옵니다.
첨부 파일 가져오기	지정된 첨부 파일의 지정된 뷰를 이진 콘텐츠로 가져옵니다.

첨부 파일 정보 가져오기

파일 이름, 형식 및 사용 가능한 보기(예: 원본 또는 축소판 그림)를 포함하여 지정된 첨부 파일에 대한 정보를 가져옵니다.

GET /v3/attachments/{attachmentId}

내용	설명
요청 본문	해당 없음
반환	AttachmentInfo 개체

첨부 파일 가져오기

지정된 첨부 파일의 지정된 뷰를 이진 콘텐츠로 가져옵니다.

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

내용	설명
요청 본문	해당 없음
반환	지정된 첨부 파일의 지정된 뷰를 나타내는 이진 콘텐츠

상태 작업(사용되지 않음)

Microsoft Bot Framework State 서비스는 2018년 3월 30일부터 사용 중지됩니다. 이전에는 Azure AI Bot Service 또는 Bot Builder SDK를 기반으로 빌드된 봇이 봇 상태 데이터를 저장하기 위해 Microsoft에서 호스트하는 이 서비스에 대한 기본 연결이 있었습니다. 자체 상태 스토리지를 사용하려면 봇을 업데이트해야 합니다.

연산	설명
`Set User Data`	채널의 특정 사용자에 대한 상태 데이터를 저장합니다.
`Set Conversation Data`	채널에 특정 대화의 상태 데이터를 저장합니다.
`Set Private Conversation Data`	채널의 특정 대화 컨텍스트 내에 포함된 특정 사용자에 대한 상태 데이터를 저장합니다.
`Get User Data`	채널의 모든 대화에서 특정 사용자에 대해 이전에 저장된 상태 데이터를 검색합니다.
`Get Conversation Data`	채널에서 특정 대화에 대해 이전에 저장된 상태 데이터를 검색합니다.
`Get Private Conversation Data`	채널에서 특정 대화의 컨텍스트 내에서 특정 사용자에 대해 이전에 저장된 상태 데이터를 검색합니다.
`Delete State For User`	이전에 사용자에 대해 저장된 상태 데이터를 삭제합니다.

스키마

Bot Framework 스키마는 봇이 사용자와 통신하는 데 사용할 수 있는 개체 및 해당 속성을 정의합니다.

Object	설명
Activity 개체	봇과 사용자 간에 교환되는 메시지를 정의합니다.
AnimationCard 개체	애니메이션 GIF 또는 짧은 비디오를 재생할 수 있는 카드 정의합니다.
Attachment 개체	메시지에 포함할 추가 정보를 정의합니다. 첨부 파일은 미디어 파일(예: 오디오, 비디오, 이미지, 파일) 또는 풍부한 카드 수 있습니다.
AttachmentData 개체	첨부 파일 데이터를 설명합니다.
AttachmentInfo 개체	첨부 파일을 설명합니다.
AttachmentView 개체	첨부 파일에 사용할 수 있는 보기를 나타내는 개체를 정의합니다.
AudioCard 개체	오디오 파일을 재생할 수 있는 카드 정의합니다.
CardAction 개체	수행할 작업을 정의합니다.
CardImage 개체	카드 표시할 이미지를 정의합니다.
ChannelAccount 개체	채널의 봇 또는 사용자 계정을 정의합니다.
ConversationAccount 개체	채널에서 대화를 정의합니다.
ConversationMembers 개체	대화의 멤버를 정의합니다.
ConversationParameters 개체	새 대화를 만들기 위한 매개 변수 정의
ConversationReference 개체	대화의 특정 지점을 정의합니다.
ConversationResourceResponse 개체	대화 만들기에 대한 응답을 정의합니다.
ConversationsResult 개체	대화 가져오기 호출 의 결과를 정의합니다.
Entity 개체	엔터티 개체를 정의합니다.
오류 개체	오류를 정의합니다.
ErrorResponse 개체	HTTP API 응답을 정의합니다.
팩트 개체	팩트를 포함하는 키-값 쌍을 정의합니다.
GeoCoordinates 개체	WSG84(World Geodetic System) 좌표를 사용하여 지리적 위치를 정의합니다.
HeroCard 개체	큰 이미지, 제목, 텍스트 및 작업 단추가 있는 카드 정의합니다.
InnerHttpError 개체	내부 HTTP 오류를 나타내는 개체입니다.
MediaEventValue 개체	미디어 이벤트에 대한 보조 매개 변수입니다.
MediaUrl 개체	미디어 파일의 원본에 대한 URL을 정의합니다.
Mention 개체	대화에 멘션 사용자 또는 봇을 정의합니다.
MessageReaction 개체	메시지에 대한 반응을 정의합니다.
PagedMembersResult 개체	대화 페이징 멤버 가져오기에서 반환하는 멤버의 페이지입니다.
Place 개체	대화에 멘션 위치를 정의합니다.
ReceiptCard 개체	구매 영수증이 포함된 카드 정의합니다.
ReceiptItem 개체	영수증 내의 품목을 정의합니다.
ResourceResponse 개체	리소스를 정의합니다.
SemanticAction 개체	프로그래밍 작업에 대한 참조를 정의합니다.
SignInCard 개체	사용자가 서비스에 로그인할 수 있는 카드 정의합니다.
SuggestedActions 개체	사용자가 선택할 수 있는 옵션을 정의합니다.
TextHighlight 개체	다른 필드 내에 있는 콘텐츠의 하위 문자열을 참조합니다.
ThumbnailCard 개체	썸네일 이미지, 제목, 텍스트 및 작업 단추를 사용하여 카드 정의합니다.
ThumbnailUrl 개체	이미지 원본에 대한 URL을 정의합니다.
Transcript 개체	대화 기록 보내기를 사용하여 업로드할 활동의 컬렉션입니다.
VideoCard 개체	비디오를 재생할 수 있는 카드 정의합니다.

Activity 개체

봇과 사용자 간에 교환되는 메시지를 정의합니다.

속성	종류	설명
작업	문자열	적용하거나 적용된 작업입니다. type 속성을 사용하여 작업의 컨텍스트를 확인합니다. 예를 들어 type이 contactRelationUpdate인 경우 사용자가 연락처 목록에 봇을 추가한 경우 작업 속성의 값이 추가되거나 연락처 목록에서 봇을 제거한 경우 제거됩니다.
attachmentLayout	문자열	메시지에 포함된 attachments 서식 있는 카드의 레이아웃입니다. 다음 값 중 하나: 회전식, 목록. 서식 있는 카드 첨부 파일에 대한 자세한 내용은 메시지에 서식 있는 카드 첨부 파일 추가를 참조하세요.
첨부 파일	첨부 파일[]	메시지에 포함할 추가 정보를 정의하는 Attachment 개체의 배열입니다. 각 첨부 파일은 파일(예: 오디오, 비디오, 이미지) 또는 풍부한 카드 수 있습니다.
callerId	문자열	봇의 호출자를 식별하는 IRI가 포함된 문자열입니다. 이 필드는 유선으로 전송되는 것이 아니라 호출자의 ID를 어설션하는 암호화된 확인 가능한 데이터(예: 토큰)를 기반으로 봇 및 클라이언트에 의해 채워집니다.
channelData	Object	채널 관련 콘텐츠가 포함된 개체입니다. 일부 채널은 첨부 파일 스키마를 사용하여 나타낼 수 없는 추가 정보가 필요한 기능을 제공합니다. 이러한 경우 채널 설명서에 정의된 대로 이 속성을 채널별 콘텐츠로 설정합니다. 자세한 내용은 채널별 기능 구현을 참조 하세요.
channelId	문자열	채널을 고유하게 식별하는 ID입니다. 채널에 의해 설정됩니다.
code	문자열	대화가 종료된 이유를 나타내는 코드입니다.
대화	ConversationAccount	활동이 속한 대화를 정의하는 ConversationAccount 개체입니다.
deliveryMode	문자열	활동에 대한 받는 사람 대체 전송 경로에 신호를 보내는 전송 힌트입니다. 다음 값 중 하나: 일반, 알림.
entities	object[]	메시지에 멘션 엔터티를 나타내는 개체의 배열입니다. 이 배열의 개체는 모든 Schema.org 개체일 수 있습니다. 예를 들어 배열에는 대화에서 언급된 사람을 식별하는 Mention 개체와 대화에서 언급된 위치를 식별하는 Place 개체가 포함될 수 있습니다.
expiration	문자열	활동을 "만료됨"으로 간주하고 받는 사람에게 표시해서는 안 되는 시간입니다.
보낸 사람	ChannelAccount	메시지의 발신자를 지정하는 ChannelAccount 개체입니다.
historyDisclosed	부울	기록이 공개되는지 여부를 나타내는 플래그입니다. 기본값은 거짓입니다.
id	문자열	채널의 활동을 고유하게 식별하는 ID입니다.
importance	문자열	활동의 중요도를 정의합니다. low, normal, high 값 중 하나입니다.
inputHint	문자열	메시지가 클라이언트에 전달된 후 봇이 사용자 입력을 수락, 예상 또는 무시할지 여부를 나타내는 값입니다. acceptingInput, expectingInput, ignoringInput 값 중 하나입니다.
label	문자열	활동에 대한 설명이 포함된 레이블입니다.
listenFor	String[]	음성 및 언어 초기화 시스템에서 수신 대기해야 하는 구 및 참조 목록입니다.
로캘	문자열	메시지 내에서 텍스트를 표시하는 데 사용해야 하는 언어의 로캘입니다 `<language>-<country>`. 채널은 봇이 해당 언어로 표시 문자열을 지정할 수 있도록 이 속성을 사용하여 사용자의 언어를 나타냅니다. 기본값은 en-US입니다.
localTimestamp	문자열	메시지가 ISO-8601 형식으로 표현된 현지 표준 시간대로 전송된 날짜 및 시간입니다.
localTimezone	문자열	IANA 표준 시간대 데이터베이스 형식으로 표시되는 메시지의 로컬 표준 시간대 이름을 포함합니다. 예를 들어 미국/Los_Angeles.
membersAdded	ChannelAccount[]	대화에 참가한 사용자 목록을 나타내는 ChannelAccount 개체의 배열입니다. 활동 유형 이 "conversationUpdate"이고 사용자가 대화에 참가한 경우에만 표시됩니다.
membersRemoved	ChannelAccount[]	대화를 떠난 사용자 목록을 나타내는 ChannelAccount 개체의 배열입니다. 활동 유형 이 "conversationUpdate"이고 사용자가 대화를 떠난 경우에만 표시됩니다.
이름	문자열	호출할 작업의 이름 또는 이벤트의 이름입니다.
reactionsAdded	MessageReaction[]	대화에 추가된 반응의 컬렉션입니다.
reactionsRemoved	MessageReaction[]	대화에서 제거된 반응의 컬렉션입니다.
받는 사람	ChannelAccount	메시지의 받는 사람을 지정하는 ChannelAccount 개체입니다.
relatesTo	ConversationReference	대화의 특정 지점을 정의하는 ConversationReference 개체입니다.
replyToId	문자열	이 메시지가 회신하는 메시지의 ID입니다. 사용자가 보낸 메시지에 회신하려면 이 속성을 사용자 메시지의 ID로 설정합니다. 모든 채널이 스레드 회신을 지원하는 것은 아닙니다. 이러한 경우 채널에서 이 속성을 무시하고, 시간 순서가 지정된 의미 체계(타임스탬프)를 사용하여 대화를 메시지에 추가합니다.
semanticAction	SemanticAction	프로그래밍 작업에 대한 참조를 나타내는 SemanticAction 개체입니다.
ServiceUrl	문자열	채널의 서비스 엔드포인트를 지정하는 URL입니다. 채널에 의해 설정됩니다.
말할	문자열	음성 지원 채널에서 봇이 말할 텍스트입니다. 음성, 속도, 볼륨, 발음 및 피치와 같은 봇 음성의 다양한 특성을 제어하려면 이 속성을 SSML(Speech Synthesis Markup Language) 형식으로 지정합니다.
suggestedActions	SuggestedActions	사용자가 선택할 수 있는 옵션을 정의하는 SuggestedActions 개체입니다.
요약	문자열	메시지에 포함된 정보의 요약입니다. 예를 들어 전자 메일 채널에서 보낸 메시지의 경우 이 속성은 전자 메일 메시지의 처음 50자를 지정할 수 있습니다.
text	문자열	사용자가 봇으로 보내거나 봇에서 사용자로 보내는 메시지의 텍스트입니다. 이 속성의 콘텐츠에 적용되는 제한 사항은 채널 설명서를 참조하세요.
Textformat	문자열	메시지 텍스트의 형식입니다. markdown, plain, xml 값 중 하나입니다. 텍스트 형식에 대한 자세한 내용은 메시지 만들기를 참조 하세요.
textHighlights	TextHighlight[]	활동에 replyToId 값이 포함된 시기를 강조 표시할 텍스트 조각의 컬렉션입니다.
timestamp	문자열	메시지가 ISO-8601 형식으로 표현된 UTC 표준 시간대로 전송된 날짜 및 시간입니다.
topicName	문자열	활동이 속한 대화의 토픽입니다.
type	문자열	활동의 유형입니다. message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff 값 중 하나입니다. 활동 유형에 대한 자세한 내용은 활동 개요를 참조하세요.
value	Object	개방형 값입니다.
valueType	문자열	활동 값 개체의 형식입니다.

속성	종류	설명
aspect	부울	축소판 그림/미디어 자리 표시자의 가로 세로 비율입니다. 허용되는 값은 "16:9" 및 "4:3"입니다.
autoloop	부울	마지막 GIF가 끝날 때 애니메이션 GIF 목록을 재생할지 여부를 나타내는 플래그입니다. 애니메이션을 자동으로 재생하려면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
Autostart	부울	카드가 표시될 때 애니메이션을 자동으로 재생할지 여부를 나타내는 플래그입니다. 애니메이션을 자동으로 재생하려면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
buttons	CardAction[]	사용자가 하나 이상의 작업을 수행할 수 있도록 하는 CardAction 개체의 배열입니다. 채널은 지정할 수 있는 단추 수를 결정합니다.
duration	문자열	미디어 콘텐츠 의 길이(ISO 8601 기간 형식)입니다.
image	ThumbnailUrl	카드 표시할 이미지를 지정하는 ThumbnailUrl 개체입니다.
media	MediaUrl[]	MediaUrl 개체의 배열입니다. 이 필드에 둘 이상의 URL이 포함된 경우 각 URL은 동일한 콘텐츠의 대체 형식입니다.
공유할	부울	애니메이션을 다른 사용자와 공유할 수 있는지 여부를 나타내는 플래그입니다. 애니메이션을 공유할 수 있으면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
subtitle	문자열	카드 제목 아래에 표시할 부제목입니다.
text	문자열	카드 제목 또는 부제목 아래에 표시할 설명 또는 프롬프트입니다.
title	문자열	카드의 제목입니다.
value	Object	이 카드 대한 추가 매개 변수입니다.

속성	종류	설명
content	Object	첨부 파일의 내용입니다. 첨부 파일이 서식 있는 카드 경우 이 속성을 서식 있는 카드 개체로 설정합니다. 이 속성과 contentUrl 속성은 함께 사용할 수 없습니다.
Contenttype	문자열	첨부 파일에 있는 콘텐츠의 미디어 형식입니다. 미디어 파일의 경우 이 속성을 image/png, audio/wav 및 video/mp4와 같은 알려진 미디어 형식으로 설정합니다. 풍부한 카드 경우 이 속성을 다음 공급업체별 유형 중 하나로 설정합니다. application/vnd.microsoft. 카드.adaptive: 텍스트, 음성, 이미지, 단추 및 입력 필드의 조합을 포함할 수 있는 풍부한 카드. 콘텐츠 속성을 AdaptiveCard 개체로 설정합니다. application/vnd.microsoft. 카드.animation: 애니메이션을 재생하는 풍부한 카드. 콘텐츠 속성을 AnimationCard 개체로 설정합니다. application/vnd.microsoft. 카드.audio: 오디오 파일을 재생하는 풍부한 카드. 콘텐츠 속성을 AudioCard 개체로 설정합니다. application/vnd.microsoft. 카드.hero: 영웅 카드. 콘텐츠 속성을 HeroCard 개체로 설정합니다. application/vnd.microsoft. 카드.receipt: 영수증 카드. Content 속성을 ReceiptCard 개체로 설정합니다. application/vnd.microsoft. 카드.signin: 사용자 로그인 카드. 콘텐츠 속성을 SignInCard 개체로 설정합니다. application/vnd.microsoft. 카드.thumbnail: 썸네일 카드. 콘텐츠 속성을 ThumbnailCard 개체로 설정합니다. application/vnd.microsoft.card.video: 비디오를 재생하는 서식 있는 카드입니다. 콘텐츠 속성을 VideoCard 개체로 설정합니다.
contentUrl	문자열	첨부 파일의 콘텐츠에 대한 URL입니다. 예를 들어 첨부 파일이 이미지인 경우 contentUrl을 이미지의 위치를 나타내는 URL로 설정할 수 있습니다. 지원되는 프로토콜은 HTTP, HTTPS, 파일 및 데이터입니다.
이름	문자열	첨부 파일의 이름입니다.
thumbnailUrl	문자열	채널이 콘텐츠 또는 contentUrl의 더 작은 대체 형식 사용을 지원하는 경우 사용할 수 있는 썸네일 이미지의 URL입니다. 예를 들어 contentType을 응용 프로그램/단어로 설정하고 contentUrl을 Word 문서의 위치로 설정하는 경우 문서를 나타내는 썸네일 이미지를 포함할 수 있습니다. 채널에서 문서 대신 미리 보기 이미지를 표시할 수 있습니다. 사용자가 이미지를 클릭하면 채널이 문서를 엽니다.

속성	종류	설명
size	숫자	파일의 크기입니다.
viewId	문자열	ID를 봅니다.

속성	종류	설명
aspect	문자열	이미지 속성에 지정된 썸네일의 가로 세로 비율입니다. 유효한 값은 16:9 및 4:3입니다.
autoloop	부울	마지막 파일이 끝날 때 오디오 파일 목록을 재생할지 여부를 나타내는 플래그입니다. 오디오 파일을 자동으로 재생하려면 이 속성을 true로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
Autostart	부울	카드 표시될 때 오디오를 자동으로 재생할지 여부를 나타내는 플래그입니다. 오디오를 자동으로 재생하려면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
buttons	CardAction[]	사용자가 하나 이상의 작업을 수행할 수 있도록 하는 CardAction 개체의 배열입니다. 채널은 지정할 수 있는 단추 수를 결정합니다.
duration	문자열	미디어 콘텐츠 의 길이(ISO 8601 기간 형식)입니다.
image	ThumbnailUrl	카드 표시할 이미지를 지정하는 ThumbnailUrl 개체입니다.
media	MediaUrl[]	MediaUrl 개체의 배열입니다. 이 필드에 둘 이상의 URL이 포함된 경우 각 URL은 동일한 콘텐츠의 대체 형식입니다.
공유할	부울	오디오 파일을 다른 사용자와 공유할 수 있는지 여부를 나타내는 플래그입니다. 오디오를 공유할 수 있는 경우 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
subtitle	문자열	카드 제목 아래에 표시할 부제목입니다.
text	문자열	카드 제목 또는 부제목 아래에 표시할 설명 또는 프롬프트입니다.
title	문자열	카드의 제목입니다.
value	Object	이 카드 대한 추가 매개 변수입니다.

속성	종류	설명
channelData	문자열	이 작업과 관련된 채널별 데이터입니다.
displayText	문자열	단추를 클릭하면 채팅 피드에 표시할 텍스트입니다.
image	문자열	텍스트 레이블 옆에 있는 단추에 표시되는 이미지 URL입니다.
text	문자열	작업에 대한 텍스트입니다.
title	문자열	단추에 표시되는 텍스트 설명입니다.
type	문자열	수행할 작업의 유형입니다. 유효한 값 목록은 메시지에 서식 있는 카드 첨부 파일 추가를 참조하세요.
value	Object	작업에 대한 추가 매개 변수입니다. 이 속성의 동작은 작업 유형에 따라 달라집니다. 자세한 내용은 메시지에 서식 있는 카드 첨부 파일 추가를 참조하세요.

속성	종류	설명
Alt	문자열	이미지에 대한 설명입니다. 접근성을 지원하려면 설명을 포함해야 합니다.
탭	CardAction	사용자가 이미지를 탭하거나 클릭하는 경우 수행할 작업을 지정하는 CardAction 개체입니다.
url	문자열	이미지 원본 또는 이미지의 base64 이진(예: `data:image/png;base64,iVBORw0KGgo...`)에 대한 URL입니다.

속성	종류	설명
aadObjectId	문자열	Microsoft Entra ID 내에서 이 계정의 개체 ID입니다.
id	문자열	이 채널의 사용자 또는 봇에 대한 고유 ID입니다.
이름	문자열	봇 또는 사용자의 표시 이름입니다.
역할	문자열	계정에 속한 엔터티의 역할입니다. 사용자 또는 봇.

속성	종류	설명
id	문자열	대화 ID입니다.
멤버	ChannelAccount[]	이 대화의 멤버 목록입니다.

속성	종류	설명
activity	활동	만들 때 대화에 보낼 초기 메시지입니다.
봇	ChannelAccount	메시지를 봇에 라우팅하는 데 필요한 채널 계정 정보입니다.
channelData	Object	대화를 만들기 위한 채널별 페이로드입니다.
isGroup	부울	그룹 대화인지 여부를 나타냅니다.
멤버	ChannelAccount[]	메시지를 각 사용자에게 라우팅하는 데 필요한 채널 계정 정보입니다.
tenantId	문자열	대화를 만들어야 하는 테넌트 ID입니다.
topicName	문자열	대화의 주제입니다. 이 속성은 채널에서 지원하는 경우에만 사용됩니다.

속성	종류	설명
Activityid	문자열	이 개체에서 참조하는 활동을 고유하게 식별하는 ID입니다.
봇	ChannelAccount	이 개체에서 참조하는 대화에서 봇을 식별하는 ChannelAccount 개체입니다.
channelId	문자열	이 개체가 참조하는 대화의 채널을 고유하게 식별하는 ID입니다.
대화	ConversationAccount	이 개체에서 참조하는 대화를 정의하는 ConversationAccount 개체입니다.
ServiceUrl	문자열	이 개체에서 참조하는 대화에서 채널의 서비스 엔드포인트를 지정하는 URL입니다.
user	ChannelAccount	이 개체가 참조하는 대화에서 사용자를 식별하는 ChannelAccount 개체입니다.

속성	종류	설명
Activityid	문자열	전송되는 경우 활동 ID입니다.
id	문자열	리소스의 ID입니다.
ServiceUrl	문자열	대화와 관련된 작업을 수행할 수 있는 서비스 엔드포인트입니다.

속성	종류	설명
대화	ConversationMembers[]	각 대화의 멤버입니다.
continuationToken	문자열	대화 가져오기에 대한 후속 호출에 사용할 수 있는 연속 토큰입니다.

속성	종류	설명
code	문자열	오류 코드
innerHttpError	InnerHttpError	내부 HTTP 오류를 나타내는 개체입니다.
message	문자열	오류의 설명.

속성	종류	설명
key	문자열	팩트 이름입니다. 예를 들어 체크 인입니다. 이 키는 팩트 값을 표시할 때 레이블로 사용됩니다.
value	문자열	팩트의 값입니다. 예를 들어 2016년 10월 10일입니다.

속성	종류	설명
elevation	숫자	위치의 상승입니다.
latitude	숫자	위치의 위도입니다.
경도	숫자	위치의 경도입니다.
이름	문자열	위치의 이름입니다.
type	문자열	이 개체의 형식입니다. 항상 GeoCoordinates로 설정합니다.

속성	종류	설명
상태코드	숫자	실패한 요청의 HTTP 상태 코드입니다.
몸	Object	실패한 요청의 본문입니다.

속성	종류	설명
profile	문자열	미디어의 콘텐츠를 설명하는 힌트입니다.
url	문자열	미디어 파일의 원본에 대한 URL입니다.

속성	종류	설명
멘션	ChannelAccount	멘션 사용자 또는 봇을 지정하는 ChannelAccount 개체입니다. Slack과 같은 일부 채널은 대화당 이름을 할당하므로 메시지의 받는 사람 속성에 있는 봇의 멘션 이름이 봇을 등록할 때 지정한 핸들과 다를 수 있습니다. 그러나 둘 다에 대한 계정 ID는 동일합니다.
text	문자열	대화에 멘션 사용자 또는 봇입니다. 예를 들어 메시지가 "@ColorBot 새 색 선택"인 경우 이 속성은 @ColorBot 설정됩니다. 일부 채널에서는 이 속성을 설정하지 않습니다.
type	문자열	이 개체의 형식입니다. 항상 멘션으로 설정합니다.

속성	종류	설명
continuationToken	문자열	대화 페이징 멤버 가져오기에 대한 후속 호출 에 사용할 수 있는 연속 토큰입니다.
멤버	ChannelAccount[]	대화 멤버의 배열입니다.

속성	종류	설명
address	Object	장소의 주소입니다. 이 속성은 문자열 또는 PostalAddress 형식의 복합 개체일 수 있습니다.
지리적	GeoCoordinates	위치의 지리적 좌표를 지정하는 GeoCoordinates 개체입니다.
hasMap	Object	위치에 매핑합니다. 이 속성은 문자열(URL) 또는 Map 형식의 복합 개체일 수 있습니다.
이름	문자열	위치의 이름입니다.
type	문자열	이 개체의 형식입니다. 항상 Place로 설정합니다.

Bot Framework 커넥트or 서비스에 대한 API 참조

기본 URI

헤더

요청 헤더

응답 헤더

HTTP 상태 코드

Errors

대화 작업

대화 만들기

활동 삭제

대화 멤버 삭제

활동 멤버 가져오기

대화 가져오기

대화 멤버 가져오기

대화 구성원 가져오기

대화 페이징 멤버 가져오기

활동에 회신

대화 기록 보내기

대화로 보내기

업데이트 작업

채널에 첨부 파일 업로드

첨부 파일 작업

첨부 파일 정보 가져오기

첨부 파일 가져오기

상태 작업(사용되지 않음)

스키마

Activity 개체

AnimationCard 개체

Attachment 개체

AttachmentData 개체

AttachmentInfo 개체

AttachmentView 개체

AudioCard 개체

CardAction 개체

CardImage 개체

ChannelAccount 개체

ConversationAccount 개체

ConversationMembers 개체

ConversationParameters 개체

ConversationReference 개체

ConversationResourceResponse 개체

ConversationsResult 개체

Entity 개체

Error 개체

ErrorResponse 개체

팩트 개체

GeoCoordinates 개체

HeroCard 개체

InnerHttpError 개체

MediaEventValue 개체

MediaUrl 개체

Mention 개체

MessageReaction 개체

PagedMembersResult 개체

Place 개체

ReceiptCard 개체

ReceiptItem 개체

ResourceResponse 개체

SemanticAction 개체

SignInCard 개체

SuggestedActions 개체

TextHighlight 개체

ThumbnailCard 개체

ThumbnailUrl 개체

Transcript 개체

VideoCard 개체

추가 리소스

속성	종류	설명
image	CardImage	줄 항목 옆에 표시할 썸네일 이미지를 지정하는 CardImage 개체입니다.
price	문자열	구매한 모든 단위의 총 가격을 지정하는 통화 형식 문자열입니다.
quantity	문자열	구매한 단위 수를 지정하는 숫자 문자열입니다.
subtitle	문자열	품목 제목 아래에 표시할 부제목입니다.
탭	CardAction	사용자가 줄 항목을 탭하거나 클릭하는 경우 수행할 작업을 지정하는 CardAction 개체입니다.
text	문자열	줄 항목에 대한 설명입니다.
title	문자열	품목의 제목입니다.

속성	종류	설명
entities	Object	각 속성의 값이 Entity 개체인 개체입니다.
id	문자열	이 작업의 ID입니다.
상태	문자열	이 작업의 상태입니다. 허용되는 값은 start, continue, done입니다.

속성	종류	설명
buttons	CardAction[]	사용자가 서비스에 로그인할 수 있도록 하는 CardAction 개체의 배열입니다. 채널은 지정할 수 있는 단추 수를 결정합니다.
text	문자열	로그인 카드 포함하라는 설명 또는 프롬프트입니다.

속성	종류	설명
actions	CardAction[]	제안된 작업을 정의하는 CardAction 개체의 배열입니다.
to	String[]	제안된 작업이 표시되어야 하는 받는 사람의 ID를 포함하는 문자열의 배열입니다.

속성	종류	설명
발생 빈도	숫자	참조된 텍스트 내의 텍스트 필드가 여러 개 있는 경우 발생합니다.
text	문자열	강조 표시할 텍스트 조각을 정의합니다.

속성	종류	설명
aspect	문자열	비디오의 가로 세로 비율입니다. 16:9 또는 4:3.
autoloop	부울	마지막 비디오 파일이 끝날 때 해당 비디오 파일 목록을 재생할지 여부를 나타내는 플래그입니다. 비디오를 자동으로 재생하려면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
Autostart	부울	카드가 표시될 때 비디오를 자동으로 재생할지 여부를 나타내는 플래그입니다. 비디오를 자동으로 재생하려면 이 속성을 true 로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
buttons	CardAction[]	사용자가 하나 이상의 작업을 수행할 수 있도록 하는 CardAction 개체의 배열입니다. 채널은 지정할 수 있는 단추 수를 결정합니다.
duration	문자열	미디어 콘텐츠 의 길이(ISO 8601 기간 형식)입니다.
image	ThumbnailUrl	카드 표시할 이미지를 지정하는 ThumbnailUrl 개체입니다.
media	MediaUrl[]	MediaUrl의 배열입니다. 이 필드에 둘 이상의 URL이 포함된 경우 각 URL은 동일한 콘텐츠의 대체 형식입니다.
공유할	부울	비디오를 다른 사용자와 공유할 수 있는지 여부를 나타내는 플래그입니다. 비디오를 공유할 수 있으면 이 속성을 true로 설정하고, 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.
subtitle	문자열	카드 제목 아래에 표시할 부제목입니다.
text	문자열	카드 제목 또는 부제목 아래에 표시할 설명 또는 프롬프트입니다.
title	문자열	카드의 제목입니다.
value	Object	이 카드 대한 추가 매개 변수