微软Bot Framework是一个开发和部署聊天机器人的框架，包含五个主要组成部分：Bot Builder SDK、Bot Connector、Developer Portal、Bot Directory和Emulator。框架支持用户与bot之间的对话处理，包括消息发送、接收和用户状态的存储，还有多种对话逻辑组织方式。它还集成了智能服务和意图识别工具，提供对话的高效管理与交互体验。

1. 简介
• 微软Bot Framework是一套用于开发和部署bot服
务的框架，通过该框架可以开发对话型机器人
服务，并接入到多种应用中。
• Bot Framework框架包括五个组成部分：
- Bot Builder SDK （开发bot服务，目前提供.Net & Node）
- Bot Connector （连接bot服务和最终用户）
- Developer Portal （供开发者注册、发布和管理bot服务）
- Bot Directory （已发布的所有bot服务目录）
- Emulator （供开发者本地调试bot服务的模拟器）

2. 简介
Bot
Bot Connector
User
Channels

3. Hello world (Node version)
var restify = require('restify');
var builder = require('botbuilder');
var server = restify.createServer();
server.listen(process.env.port || process.env.PORT || 3978, function () {
console.log('%s listening to %s', server.name, server.url);
});
var connector = new builder.ChatConnector({
appId: process.env.MICROSOFT_APP_ID,
appPassword: process.env.MICROSOFT_APP_PASSWORD
});
var bot = new builder.UniversalBot(connector);
server.post('/api/messages', connector.listen());
bot.dialog('/', function (session) {
session.send("Hello World");
});
Connector
建立同Bot Connector的连接，实现鉴
权以及用户和Bot之间的消息传递，目
前SDK提供三种：ConsoleConnector、
ChatConnector和CallConnector。
Bot
Bot服务的大脑，负责管理用户和Bot
之间的所有会话，需要使用connector
初始化，目前SDK提供两种：
UniversalBot和UniversalCallBot。
Dialog
实现Bot的具体会话逻辑，类似于网站
的路由，可以定义多个分别实现不同
的会话逻辑

4. 鉴权
第一步: 向MSA登录服务发起请求
POST /d6d49420-f39b-4df7-a1dc-
d59a935871db/oauth2/v2.0/token HTTP/1.1
grant_type=client_credentials
client_id=<YOUR MICROSOFT APP ID>
client_secret=<YOUR MICROSOFT APP PASSWORD>
scope=https://api.botframework.com/.default
第二步: 获取token
HTTP/1.1 200 OK
{"token_type":"Bearer","expires_in":3600,"ext_expires_
in":3600,"access_token":"eyJhbGciOiJIUzI1NiIsInR5cC
I6IkpXVCJ9.eyJzdWIiOiJZb3UgZm91bmQgdGhlIG1hc
mJsZSBpbiB0aGUgb2F0bWVhbCEiLCJuYW1lIjoiQm
90IEZyYW1ld29yayJ9.JPyDDC5yKmHfOS7Gz2jjEhO
PvZ6iStYFu9XlkZDc7wc"}
第三步: 向Bot Connector发送消息
POST /v3/conversations/12345/activities HTTP/1.1
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ
Zb3UgZm91bmQgdGhlIG1hcmJsZSBpbiB0aGUgb2F0
bWVhbCEiLCJuYW1lIjoiQm90IEZyYW1ld29yayJ9.JP
yDDC5yKmHfOS7Gz2jjEhOPvZ6iStYFu9XlkZDc7wc
... (JSON-serialized activity message follows)

5. 鉴权
第一步: 下载OpenId元数据文档
GET /v1/.well-known/openidconfiguration
HTTP/1.1
{
"issuer":"https://api.botframework.com",
"authorization_endpoint":"https://invalid.botframew
ork.com/",
"jwks_uri":"https://api.aps.skype.com/v1/keys",
"id_token_signing_alg_values_supported":["RSA25
6"],
"token_endpoint_auth_methods_supported":["privat
e_key_jwt"]
}
第二步: 下载有效的签名秘钥列表
GET /v1/keys HTTP/1.1
第三步: 验证JWT token

6. 开启对话
Bot向Bot Connector发起创建会话请求
POST https://api.botframework.com/v3/conversations HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
会话创建成功之后Bot Connector返回会话id
{
"id": "abcd1234"
}
通常会话由用户发起，Bot回复用户的
消息即可，但某种场景下可能需要Bot
主动发起会话。
会话可以有多种形式，既可以是一对
一的私有回话，也可以是多对多的群
组会话。

7. 收发消息
• 会话就是在用户与Bot之间发
送的消息序列，在Bot
Framework中每条消息都是一
个Activity对象。
消息类型 描述
contactRelationUpdate 用户将bot添加到联系人列表或者
移除出联系人列表
conversationUpdate 用户加入或离开会话，会话名称修
改
deleteUserData 用户要求bot删除自己的相关信息
message 普通的消息
ping 发给bot用来验证服务可接入
typing 表示对方正在输入
属性 属性说明
conversation 消息所属会话的信息，包括会话id和会话名称
from 发送消息方的信息
locale 消息的语言环境
recipient 接收消息方的信息
replyToId 消息回复的activity id
type 消息类型

8. POST https://api.botframework.com/v3/conversations/abcd1234/activities/5d5cdc723 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
收发消息
回复消息发送的URL路径为
https://api.botframework.com/v3/conversations/{conversation
Id}/activities/{activityId}
发起消息发送的URL路径为
https://api.botframework.com/v3/conversations/{conversation
Id}/activities

9. 消息中携带附件
POST https://api.botframework.com/v3/conversations/abcd1234/activities/5d5cdc723 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "sender's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "recipient's name"
},
"text": "Here's a pic of the duck I was telling you about.",
"attachments": [
{
"contentType": "image/png",
"contentUrl": http://aka.ms/Fo983c
}
],
"replyToId": "5d5cdc723"
}
除了文本文字，消息也可以携带其他类型的附件，如图片、
音频、视频和Rich Card。

10. 消息中携带应用数据
{
"type": "message",
"from": {
"id": "mybot@gmail.com",
"name": "My bot"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "john@gmail.com",
"name": "John Doe"
},
"channelData": {
"htmlBody" : "<html><body style="font-family: Calibri; font-size: 11pt;">email message goes
here</body></html>",
"subject":"email subject goes here",
"importance":"high"
},
"replyToId": "5d5cdc723"
}
某些对接应用无法直接使用text和附件，此时需要携带应用
可使用的数据

11. 保存用户状态数据
• Bot Framework提供了三种存储来保存用户的状态数据
- User Data Store （与会话无关的用户数据）
- Conversation Store （与用户无关的会话数据）
- Private Conversation Store （会话中的用户数据）
• 每种存储可用的最大空间均为32KB，使用ETag实现对数据修改的并发控制
User Data Store
https://api.botframework.com/v3/botstate/{channelId}/users/{userId}
Conversation Store
https://api.botframework.com/v3/botstate/{channelId}/conversations/{conversationId}
Private Conversation Store
https://api.botframework.com/v3/botstate/{channelId}/conversations/{conversationId}/users/{userId}

12. 保存用户状态数据
POST https://api.botframework.com/v3/botstate/abcd1234/users/12345678 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"data": [
{
"trail": "Lake Serene",
"miles": 8.2,
"difficulty": "Difficult",
},
{
"trail": "Rainbow Falls",
"miles": 6.3,
"difficulty": "Moderate",
}
],
"eTag": "a1b2c3d4"
}
GET https://api.botframework.com/v3/botstate/abcd1234/users/12345678
HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"data": [
{
"trail": "Lake Serene",
"miles": 8.2,
"difficulty": "Difficult",
}
],
"eTag": "xyz12345"
}

13. Dialog组织方式
• Waterfall：Bot驱动会话的常用组织方式，bot始终处于一种为用户
提供信息或者问用户问题等待回答的状态。
- 为dialog处理器提供一组函数，框架对于每个会话维护一个dialog栈，bot根据栈中的内容来
判断用户的回复内容路由到哪个dialog。
• Closure：只为dialog处理器提供一个函数，类似于单步的waterfall。
• Dialog Object：为dialog处理提供一个IntentDialog，用于判断用户
意图，然后根据不同的意图执行不同的处理逻辑。
• SimpleDialog：作为waterfall的补充，用来处理waterfall无法覆盖
的场景。

14. IntentDialog
• 意图对话提供两种意图匹配方法：正则表达式和意图识别器，前
者在Bot本地实现意图匹配，后者基于云端实现意图识别和实体
抽取。
• 微软提供的云端意图识别的服务为LUIS(https://www.luis.ai/)。
• 目前Bot Framework提供的智能服务涉及：Vision、Speech、
Language、Knowledge和Search。