使用 Microsoft Bot Framework REST API 构建 Bot

您知道使用语言 SDK（.NET、Node.js）构建机器人非常容易。但是，如果您使用的是 PHP、Ruby、Python（带有科学库）等其他编程语言，本文可能对您的开发有所帮助。您可以使用任何语言通过一致的编程模型构建 Skype 机器人、Slack 机器人、Facebook Messenger 机器人、应用内托管机器人等。

如果您曾经使用过以前的 Skype Bot Platform 或 Microsoft Bot Framework 1.0 构建过机器人，那么对于新的 Microsoft Bot Framework 3，有一些重要的注意事项。

Microsoft Bot Framework basically is the common developer platform for building and hosting your bot (the concept is similar with Hubot), and this connects to each bot infrastructures (Slack Bot, Skype Bot, etc.). Therefore, in the v1 endpoint, Microsoft Bot Framework and Skype Bot Platform separated each other. (If you want to use Skype in Microsoft Bot Framework 1.0, you must setup the connection to the Skype Bot.) Microsoft Bot Framework 本质上是用于构建和托管您的机器人的通用开发平台（概念类似于 Hubot），它连接到每个机器人基础设施（Slack Bot、Skype Bot 等）。因此，在 v1 端点中，Microsoft Bot Framework 和 Skype Bot Platform 是相互独立的。（如果您想在 Microsoft Bot Framework 1.0 中使用 Skype，您必须设置与 Skype Bot 的连接。）

On the other hand, Microsoft Bot Framework version 3 is involving the developer experience for "Skype Bot" too, and all Skype bot’s set-up can only be done by Microsoft Bot Framework. For example, if you want to build your Skype bot, you can simply use Microsoft Bot Framework 3. In addition, as I show you later in this post, several concepts of Bot Framework (calling pattern, authentication, etc.) is similar to the original Skype Bot Platform. (The platform design of Microsoft Bot Framework has changed from v1.) 另一方面，Microsoft Bot Framework 3 版本也涉及“Skype Bot”的开发者体验，并且所有 Skype 机器人的设置都只能通过 Microsoft Bot Framework 完成。例如，如果您想构建 Skype 机器人，您只需使用 Microsoft Bot Framework 3 即可。此外，如我稍后在本帖中所示，Bot Framework 的几个概念（调用模式、身份验证等）与原始 Skype Bot Platform 类似。（Microsoft Bot Framework 的平台设计已从 v1 更改。）

Notice: As I show you later, Skype Bot Platform is not retired and you can use the v3 endpoint of Skype Bot Platform. 注意：如我稍后所示，Skype Bot Platform 未淘汰，您可以使用 Skype Bot Platform 的 v3 端点。

Notice: Microsoft Bot Framework v2 is not public (internal build). v1 and v3 only. 注意：Microsoft Bot Framework v2 不是公开的（内部版本）。仅 v1 和 v3。

Call Flow Overview

Before you start, you must register your bot in dev portal (https://dev.botframework.com/bots). In this blog post, we assume that this registration is all done. 在开始之前，您必须在开发人员门户（https://dev.botframework.com/bots）中注册您的机器人。在本博文中，我们假设所有这些注册都已完成。

When you register your bot, your bot is also registered in App Registration Portal (https://apps.dev.microsoft.com) and you can get the client id and client secret for your bot. This data (client id and client secret) is used for the authentication which I describe later. 注册机器人时，您的机器人也会在应用程序注册门户（https://apps.dev.microsoft.com）中注册，您可以获取机器人的客户端 ID 和客户端密钥。这些数据（客户端 ID 和客户端密钥）用于我稍后描述的身份验证。

The following picture illustrates the calling flow of the Microsoft Bot Framework. 下图说明了 Microsoft Bot Framework 的调用流程。

Microsoft Bot Framework provides the basic platform for bot hosting and connects to each communication channel (Slack, Skype, etc.) fronting on end-users through Bot Connector. Your code (your bot) interacts with this Microsoft Bot Framework on the backend. That is, your code (your bot) must communicate with the Microsoft Bot Framework only. Microsoft Bot Framework 提供了机器人托管的基本平台，并通过 Bot Connector 连接到面向最终用户的每个通信渠道（Slack、Skype 等）。您的代码（您的机器人）在后端与 Microsoft Bot Framework 进行交互。也就是说，您的代码（您的机器人）只能与 Microsoft Bot Framework 通信。

If you connect to channels (Slack, Facebook Messenger, etc.), you must set it up in the portal (https://dev.botframework.com/bots). But Skype Bot infrastructure (Skype channel) is initially connected to the Microsoft Bot Framework. (No need for extra work except for publishing to the Skype bot directory.) 如果您连接到渠道（Slack、Facebook Messenger 等），您必须在门户（https://dev.botframework.com/bots）中进行设置。但是 Skype Bot 基础设施（Skype 渠道）最初是连接到 Microsoft Bot Framework 的。（除了发布到 Skype 机器人目录外，无需额外工作。）

Authentication Flow (outgoing – your code to bot framework)

Before starting communications, you must learn about the authentication for secure communications. 在开始通信之前，您必须了解安全通信的身份验证。

The messages to Bot Framework (from your bot) must be protected by Azure Ad v2 endpoint, otherwise the malicious code might call the Microsoft Bot Framework instead of your bot. 发送给 Bot Framework 的消息（来自您的机器人）必须受 Azure Ad v2 端点 的保护，否则恶意代码可能会调用 Microsoft Bot Framework 而不是您的机器人。

In this section, I explain about how to accomplish this flow. 在本节中，我将解释如何实现此流程。

The Bot Framework uses the app-only access token in Azure AD v2 endpoint. To get this kind of access token, you just send the HTTP request as follows. Bot Framework 使用 Azure AD v2 端点的应用程序独占访问令牌。要获取此类访问令牌，只需发送如下 HTTP 请求。

As I described before, you must retrieve the client_id and client_secret from the app registration portal beforehand and set it as follows. 如前所述，您必须提前从应用程序注册门户检索 client_id 和 client_secret，并按如下方式设置。

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a&client_secret=6wyxeJ4...&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default

As a result, you can receive the following HTTP response, and this includes the following access token. (Note that this access token expires in 1 hour.) 结果，您将收到以下 HTTP 响应，其中包含以下访问令牌。（请注意，此访问令牌将在 1 小时后过期。）

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 0,
  "access_token": "eyJ0eXAiOi..."
}

Hold this access token in your bot application, because you must always set this access token as the "Authorization" header for your outgoing messages as follows. And the Microsoft Bot Framework verifies this token for checking whether this request is sent from the valid (registered) bot. 在您的机器人应用程序中保留此访问令牌，因为您必须始终将其作为“Authorization”标头用于您的出站消息，如下所示。Microsoft Bot Framework 将验证此令牌，以检查此请求是否来自有效的（已注册）机器人。

Notice: This access token also includes the claims (client id, expiration, etc.) for communications, and the Microsoft Bot Framework can identify your bot using this access token. (Please see the previous post of "How to verify the OAuth token with the v2.0 endpoint".) 注意：此访问令牌还包含通信的声明（客户端 ID、过期时间等），Microsoft Bot Framework 可以使用此访问令牌识别您的机器人。（请参阅之前的帖子“如何使用 v2.0 端点验证 OAuth 令牌”。）

POST https://skype.botframework.com/v3/conversations/29%3A1iFtpwQ.../activities/6Bt4f5iryCI
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message",
  "timestamp": "2016-08-18T09:22:54.1811797Z",
  "from": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "text": "Hello !",
  "replyToId": "6Bt4f5iryCI"
}

Authentication Flow (incoming – bot framework to your code)

The message from Microsoft Bot Framework is also protected by Authorization header as follows. (see the following header in bold fonts.) In this case, your bot must verify the message for secure communication. (If you ignored this header, your code might be called by the malicious code.) Microsoft Bot Framework 发送的消息也受如下所示的 Authorization 标头保护。（参见下面粗体显示的标头。）在这种情况下，您的机器人必须验证消息以进行安全通信。（如果您忽略此标头，您的代码可能会被恶意代码调用。）

POST https://example.com/yourbot
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "contactRelationUpdate",
  "id": "6Bt4f5iryCI",
  "timestamp": "2016-08-18T09:22:50.927Z",
  "serviceUrl": "https://skype.botframework.com",
  "channelId": "skype",
  "from": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "action": "add"
}

How to verify this header value? 如何验证此标头值？

In this case, the Azure AD is not used. The key in Bot Framework is used for this authentication (AuthN and AuthZ). 在这种情况下，不使用 Azure AD。Bot Framework 中的密钥用于此身份验证（身份验证和授权）。

First, you must retrieve the OpenID / OAuth configuration information hosted at https://api.aps.skype.com/v1/.well-known/openidconfiguration. It returns as follows. (Note that this might change in the future, then don’t copy this JSON result in your production code.) 首先，您必须检索托管在 https://api.aps.skype.com/v1/.well-known/openidconfiguration 的 OpenID / OAuth 配置信息。它返回如下。（请注意，这将来可能会更改，因此请不要将此 JSON 结果复制到您的生产代码中。）

Notice: If you’re using Emulator (debugging) you must use https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration (Azure AD v2) instead of https://api.aps.skype.com/v1/.well-known/openidconfiguration. 注意：如果您正在使用模拟器（调试），则必须使用 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration（Azure AD v2）而不是 https://api.aps.skype.com/v1/.well-known/openidconfiguration。

GET https://api.aps.skype.com/v1/.well-known/openidconfiguration
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "issuer": "https://api.botframework.com",
  "authorization_endpoint": "https://invalid.botframework.com",
  "jwks_uri": "https://api.aps.skype.com/v1/keys",
  "id_token_signing_alg_values_supported": [
    "RSA256"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ]
}

The public key (X.509 certificate) is stored in the previous "jwks_uri" location. Then you must retrieve the key list and verify the previous "Authorization" header (access token). 公钥（X.509 证书）存储在之前的“jwks_uri”位置。然后，您必须检索密钥列表并验证之前的“Authorization”标头（访问令牌）。

As I explained in the previous post of "How to verify the OAuth token with the v2.0 endpoint", this verification is accomplished by the simple steps. 正如我在之前的帖子“如何使用 v2.0 端点验证 OAuth 令牌”中所解释的，此验证通过简单的步骤完成。

Here is the PHP example for this verification. 以下是此验证的 PHP 示例。

<?php
// Authorization header value
$token = "eyJ0eXAiOi...";
// 0:Invalid, 1:Valid
$token_valid = 0;
  
// 1 separate token by dot (.)
$token_arr = explode('.', $token);
$headers_enc = $token_arr[0];
$claims_enc = $token_arr[1];
$sig_enc = $token_arr[2];

// 2 base 64 url decoding
$headers_arr = json_decode(base64_url_decode($headers_enc), TRUE);
$claims_arr = json_decode(base64_url_decode($claims_enc), TRUE);
$sig = base64_url_decode($sig_enc);

// 3 get key list
$keylist = file_get_contents('https://api.aps.skype.com/v1/keys');
$keylist_arr = json_decode($keylist, TRUE);
foreach($keylist_arr['keys'] as $key => $value) {
  
  // 4 select one key (which matches)
  if($value['kid'] == $headers_arr['kid']) {
  
    // 5 get public key from key info
    $cert_txt = '-----BEGIN CERTIFICATE-----' . "\n" . chunk_split($value['x5c'][0], 64) . '-----END CERTIFICATE-----';
    $cert_obj = openssl_x509_read($cert_txt);
    $pkey_obj = openssl_pkey_get_public($cert_obj);
    $pkey_arr = openssl_pkey_get_details($pkey_obj);
    $pkey_txt = $pkey_arr['key'];
    
    // 6 verify signature
    $token_valid = openssl_verify($headers_enc . '.' . $claims_enc, $sig, $pkey_txt, OPENSSL_ALGO_SHA256);
  }
}

// 7 show result
if($token_valid == 1)
  echo 'Token is Valid';
else
  echo 'Token is Invalid';

// Helper functions
function base64_url_decode($arg) {
  $res = $arg;
  $res = str_replace('-', '+', $res);
  $res = str_replace('_', '/', $res);
  switch (strlen($res) % 4) {
    case 0:
    break;
    case 2:
    $res .= "==";
    break;
    case 3:
    $res .= "=";
    break;
    default:
    break;
  }
  $res = base64_decode($res);
  return $res;
}
?>

Messaging Flow – Make contact with your bot

The authentication flow is all done! All you have to do is to communicate using HTTP (REST-styled messaging) with Microsoft Bot Framework. Let’s see this flow. 身份验证流程已全部完成！您所要做的就是使用 HTTP（REST 风格的消息）与 Microsoft Bot Framework 进行通信。让我们看看这个流程。

First, if your bot is added to the contact list (subscribed) by a user, the following HTTP webhook arrives to your bot endpoint. 首先，如果您的机器人被用户添加到联系人列表（订阅），则以下 HTTP webhook 会到达您的机器人端点。

As I explained in the above, you must check the following "Authorization" header value and proceed your arbitrary actions. 如上所述，您必须检查以下“Authorization”标头值并继续执行您的任意操作。

Notice: In this example, I’m using the Skype. 注意：在此示例中，我使用的是 Skype。

POST https://example.com/yourbot
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "contactRelationUpdate",
  "id": "6Bt4f5iryCI",
  "timestamp": "2016-08-18T09:22:50.927Z",
  "serviceUrl": "https://skype.botframework.com",
  "channelId": "skype",
  "from": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "action": "add"
}

The "type" and "action" attributes mean what kind of bot action is published. In this case, this means that your bot is added to the user’s contact list. “type”和“action”属性表示发布了哪种机器人操作。在这种情况下，这意味着您的机器人已添加到用户的联系人列表中。

The "from" attribute is the user id. In this case, this means the Skype user which unique id (not Skype Id) is "1iFtpwQ…". Your bot must store this "from" id in your database, because your bot can communicate with each bot’s user (bot’s subscriber) using this id. “from”属性是用户 ID。在这种情况下，它表示 Skype 用户，其唯一 ID（非 Skype ID）为“1iFtpwQ…”。您的机器人必须将此“from”ID 存储在您的数据库中，因为您的机器人可以使用此 ID 与每个机器人的用户（机器人的订阅者）进行通信。

The "recipient" attribute is the destination id. In this example, this indicates your bot which client id is "1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a". “recipient”属性是目标 ID。在此示例中，它表示您的机器人，其客户端 ID 为“1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a”。

The "id" attribute is called activity id. Sometimes this id is referred by other communication. (I will show you later.) “id”属性称为活动 ID。有时此 ID 会被其他通信引用。（我稍后会展示。）

Notice: The number of "29" means the Skype user, and "28" means the bot. 注意：“29”表示 Skype 用户，“28”表示机器人。

If your bot accepts this request, you just response HTTP status 202. 如果您的机器人接受此请求，只需响应 HTTP 状态 202。

HTTP/1.1 202 Accepted

Of course, you can reply some messages (for example, bot usage info, etc.) against this adding message, and I will show you how to post outgoing messages later. 当然，您可以回复一些消息（例如，机器人使用信息等）来响应此添加消息，我稍后将向您展示如何发送出站消息。

When your bot is removed from the contact list of some user, the following HTTP request (webhook) is received. (As you can see, the action attribute is set as "remove".) 当您的机器人被从某个用户的联系人列表中删除时，会收到以下 HTTP 请求（webhook）。（正如您所见，action 属性设置为“remove”。）

In this case you also response the HTTP status 202 as a successful response. 在这种情况下，您也响应 HTTP 状态 202 作为成功响应。

POST https://example.com/yourbot
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "contactRelationUpdate",
  "id": "X4KtWvi9XS",
  "timestamp": "2016-08-18T09:48:19.201Z",
  "serviceUrl": "https://skype.botframework.com",
  "channelId": "skype",
  "from": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "action": "remove"
}

Messaging Flow – Incoming message

If the user sends the message "Good morning!" to your bot, the following HTTP webhook arrives. 如果用户向您的机器人发送消息“早上好！”，则会收到以下 HTTP webhook。

POST https://example.com/yourbot
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message",
  "id": "4GhGAlkzDAK2I5lw",
  "timestamp": "2016-08-18T09:31:31.756Z",
  "serviceUrl": "https://skype.botframework.com",
  "channelId": "skype",
  "from": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "text": "Good morning !",
  "entities": []
}

This incoming message is very similar to the previous one, and I think there’s no need to explain about details. 这个入站消息与前一个非常相似，我认为无需详细解释。

If your bot accepts this request, you just response HTTP status 202. 如果您的机器人接受此请求，只需响应 HTTP 状态 202。

HTTP/1.1 202 Accepted

Messaging Flow – Outgoing message

On the other hand, when your code sends the outgoing message (which is the message from your bot to the user), you send the following HTTP request to Microsoft Bot Framework. 另一方面，当您的代码发送出站消息（即从您的机器人到用户的消息）时，您将以下 HTTP 请求发送到 Microsoft Bot Framework。

In this example I’m using Skype and the endpoint domain is https://skype.botframework.com. If you’re communicating with Facebook, this domain should be https://facebook.botframework.com. (The domain differs by channels.) 在此示例中，我使用的是 Skype，端点域是 https://skype.botframework.com。如果您正在与 Facebook 通信，则此域应为 https://facebook.botframework.com。（域因渠道而异。）

POST https://skype.botframework.com/v3/conversations/29%3A1iFtpwQ.../activities/4GhGAlkzDAK2I5lw
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message",
  "timestamp": "2016-08-18T09:31:36.2281894Z",
  "from": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "text": "Good morning !",
  "replyToId": "4GhGAlkzDAK2I5lw"
}

The "29%3A1iFtpwQ…" in the url fragment (which is url-encoded) is the conversation id. When your bot is sending the message to some user, this conversation id is the user id itself. URL 片段中（已进行 URL 编码）的“29%3A1iFtpwQ…”是对话 ID。当您的机器人向某个用户发送消息时，此对话 ID 就是用户 ID 本身。

You can respond (reply) against some incoming message (i.e. bidirectional messaging). The above "4GhGAlkzDAK2I5lw" is the incoming "id" attribute (i.e. activity id), and this sample is responding against this incoming message. 您可以回复（回复）某些入站消息（即双向消息）。上面的“4GhGAlkzDAK2I5lw”是入站的“id”属性（即活动 ID），此示例正在响应此入站消息。

On the contrary, you can call the user using one-way style messaging like timer bot or some notification bot. If you do so, you must use the activity id with blank as follows. 相反，您可以使用单向消息传递方式调用用户，例如计时器机器人或某些通知机器人。如果您这样做，您必须使用活动 ID 为空，如下所示。

POST https://skype.botframework.com/v3/conversations/29%3A1iFtpwQ.../activities
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message",
  "timestamp": "2016-08-18T09:31:36.2281894Z",
  "from": {
    "id": "28:1f7dd6e9-cbd7-4c38-adf2-6e9bcab5310a",
    "name": "Echo Bot"
  },
  "conversation": {
    "id": "29:1iFtpwQ..."
  },
  "recipient": {
    "id": "29:1iFtpwQ...",
    "name": "Tsuyoshi Matsuzaki"
  },
  "text": "Good morning !"
}

If Microsoft Bot Framework accepts this message, HTTP status 202 is returned. (As I explained, the "Authorization" header is checked by the framework.) 如果 Microsoft Bot Framework 接受此消息，则会返回 HTTP 状态 202。（如我所述，“Authorization”标头由框架检查。）

HTTP/1.1 202 Accepted

There exists some additional notice about outgoing messages. 关于出站消息还有一些额外的注意事项。

First, almost all attributes are optional (see Microsoft Bot Connector API v3.0 document) and you can omit (skip) several attributes and can use the minimal attributes. 首先，几乎所有属性都是可选的（请参阅Microsoft Bot Connector API v3.0 文档），您可以省略（跳过）几个属性并使用最少的属性。

For example, the following is the omitted request using Skype channel. But, if you’re using Facebook channel, the "from" attribute is required for communication. That is, the required attributes differ by each channels. 例如，以下是使用 Skype 渠道的省略请求。但是，如果您正在使用 Facebook 渠道，则“from”属性是通信所必需的。也就是说，必需的属性因渠道而异。

POST https://skype.botframework.com/v3/conversations/29%3A1iFtpwQ.../activities
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message",
  "text": "Good morning !"
}

Second, if you’re communicating with only Skype, you can also use the Skype Bot Platform v3 endpoint alternatively. 第二，如果您只与 Skype 通信，您也可以选择使用Skype Bot Platform v3 端点。

Please see the following example. This uses https://apis.skype.com as the endpoint domain instead of https://skype.botframework.com. As you can see, you must also keep in mind that several detailed specifications (see the following value of "type" attribute and the HTTP response code) are different from Microsoft Bot Framework. (Similar, but different!) 请看下面的示例。它使用https://apis.skype.com作为端点域，而不是https://skype.botframework.com。正如您所见，您还必须注意，几个详细的规范（请参阅“type”属性的以下值和 HTTP 响应代码）与 Microsoft Bot Framework 不同。（相似，但不同！）

POST https://apis.skype.com/v3/conversations/29%3A1iFtpwQ.../activities
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "type": "message/text",
  "text": "Good morning !"
}
HTTP/1.1 201 Created

State Handling

The Microsoft Bot Framework itself is having the state infrastructure called "Bot State Service." With this infrastructure you can build the stateful bot with scaling. Microsoft Bot Framework 本身拥有一个称为“Bot State Service”的状态基础设施。借助此基础设施，您可以构建可扩展的状态化机器人。

Now I will show you how to use this state with REST API. 现在我将向您展示如何使用 REST API 来处理此状态。

When you want to set user state in Bot State Service, you send the following HTTP request against Bot State Service endpoint (https://state.botframework.com). 当您想在 Bot State Service 中设置用户状态时，您需要向 Bot State Service 端点（https://state.botframework.com）发送以下 HTTP 请求。

The URL must be /v3/botstate/{channelId}/users/{userId}. The following example is using the skype as the bot channel. URL 必须是/v3/botstate/{channelId}/users/{userId}。以下示例使用的是 Skype 作为机器人渠道。

POST https://state.botframework.com/v3/botstate/skype/users/29%3A1iFtpwQ...
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "eTag": "*",
  "data": {
    "DemoData1": "Test Data 1"
  }
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "DemoData1": "Test Data 1"
  },
  "eTag": "W/\"datetime'2016-08-18T10%3A12%3A45.4398159Z'\""
}

Saved data is stored in the state service, and you can pick up the state data by calling GET method. 保存的数据存储在状态服务中，您可以通过调用GET方法来检索状态数据。

GET https://state.botframework.com/v3/botstate/skype/users/29%3A1iFtpwQ...
Authorization: Bearer eyJ0eXAiOi...
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "data": {
    "DemoData1": "Test Data 1"
  },
  "eTag": "W/\"datetime'2016-08-18T10%3A12%3A45.4398159Z'\""
}

The bot state is having 2 types of scope. One is the user-scoped state (the same as previous example), and another is the conversation-scoped state. If you want to share the data across the all conversations (Skype conversation, Facebook conversation, etc.), you must use the user state. If not, you must use the conversation state. 机器人状态有两种作用域。一种是用户作用域状态（与前例相同），另一种是对话作用域状态。如果您想在所有对话（Skype 对话、Facebook 对话等）之间共享数据，则必须使用用户状态。如果不是，则必须使用对话状态。

When you want to use the conversation-scoped state, you send the HTTP request to /v3/botstate/{channelId}/conversations/{conversationId} instead of /v3/botstate/{channelId}/users/{userId} as follows. 当您想使用对话作用域状态时，您将向/v3/botstate/{channelId}/conversations/{conversationId}发送 HTTP 请求，而不是/v3/botstate/{channelId}/users/{userId}，如下所示。

POST https://state.botframework.com/v3/botstate/skype/conversations/29%3A1iFtpwQ...
Authorization: Bearer eyJ0eXAiOi...
Content-Type: application/json; charset=utf-8

{
  "eTag": "*",
  "data": {
    "DemoData2": "Test Data 2"
  }
}

Note that these data objects will fail to be stored if another instance of your bot has changed the object already. 请注意，如果您的机器人的另一个实例已更改了这些数据对象，则它们将无法存储。

Notice: Even if it’s the user state, the state is not shared with another bot. (It’s secured.) The different state in the different bot. 注意：即使是用户状态，状态也不会与其他机器人共享。（这是安全的。）不同机器人的状态不同。

Notice: If you’re using Bot Builder SDK, the serializable Dialog is persisted in the bot state service through IBotDataStore interface by default. 注意：如果您正在使用 Bot Builder SDK，默认情况下，可序列化的 Dialog 会通过 IBotDataStore 接口持久化到 bot state service 中。

In this blog post I’ve just explained the basic concept and steps building your bot with REST API api. As you see, don’t worry about the supported programming language in SDK, and please enjoy your bot development, everyone! 在本博文中，我只是解释了使用 REST API api 构建机器人的基本概念和步骤。您可以看到，不要担心 SDK 中支持的编程语言，大家请享受您的机器人开发吧！

The Microsoft Bot Framework can handle more advanced scenarios like the attachment, rich text, card, and audio, etc. (The video in Skype will be available in the future release.) Next I will explain about these advanced scenarios. Microsoft Bot Framework 可以处理更高级的场景，例如附件、富文本、卡片和音频等。（Skype 中的视频将在未来的版本中提供。）接下来我将解释这些高级场景。

For more details (api reference, arguments, etc.), please see the following official documents. 有关更多详细信息（API 参考、参数等），请参阅以下官方文档。

• Bot REST API Authentication
• Bot Connector REST API 3.0
• Bot State REST API 3.0