Merge remote-tracking branch 'origin/main'

docs/develop/agent/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "AI 助理",
+  "position": 1,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/develop/agent/send-message.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+---
+
+# AI 助理发送消息
+
+本文介绍如何实现以 [AI 助理](https://open.dingtalk.com/document/ai-dev/introduction-to-ai-assistant) 身份发送消息，以及在不同场景下如何选择合适的接口。
+
+## 概念
+
+钉钉 AI 助理，它融合了钉钉平台的多项 AI 产品功能，以智能化的方式辅助企业日常的工作流程。钉钉 AI 助理具备多种智能能力，包括但不限于智能沟通、智能协同、智能管理等。
+
+发送消息的模式分为**主动发送模式**和**回复消息模式**，两种模式对比如下：
+
+| | 主动发送模式                                                                                                                                                                                                                                                  | 回复消息模式                                                                                                                                                                                                                                                               |
+| --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 说明 | 给指定用户（UnionID）发送单聊消息，或者给指定群组（OpenConversationID）发送群聊消息                                                                                                                                                                                                  | AI 助理（或机器人）收到来自单聊、群聊或者魔法棒中的消息后，完成请求处理，并以消息方式予以响应                                                                                                                                                                                                                     |
+| 使用场景 | 在定时任务触发，产品主动推送或运营主动推送的场景下，主动给用户或者群组发送消息                                                                                                                                                                                                                 | 在有限的时间内回复来自聊天会话（单聊、群聊或魔法棒）中的请求                                                                                                                                                                                                                                       |                    |
+| 特点 | 可以在任何时候主动发起调用                                                                                                                                                                                                                      | 简单易用，发起调用时候可以不用关心会话类型（单聊、群聊或魔法棒），一次简单的开发即可兼容所有的会话类型中回复消息。<br />在 AI 助理和机器人的开发中，回复消息是主流场景，为该场景特别提供更加易用的接口可以帮助你快速实现功能开发。<br />在回复消息模式中，你会先收到一条消息请求，然后回复它。在收到的消息请求中，你可以获得 SessionWebhook 或者 ConversationToken 参数，通过 SessionWebhook 或 ConversationToken 回复消息即可，无需关心会话类型。 |
+| 使用限制 | 需要根据会话类型，选择不同的发送目标参数来调用。例如：<br />在**单聊**会话场景，需要指定用户 ID 来发送消息，也即 UnionID；<br />在**群聊**会话场景，需要指定群组的会话 ID 来发送消息，也即 OpenConversationID。<br />特别提醒：如果你在回复消息的场景中，使用主动发送模式的话，必须穷举所有会话类型的发送方式。否则会导致在特定会话类型中功能异常。例如：在 AI 助理（或机器人）回复用户消息的处理中，只实现了群聊类型，那么用户单聊中使用该功能将无法收到回复。 | 必须是在收到用户请求之后才能调用回复消息接口，并且有时间限制。<br />无论是 SessionWebhook 还是 ConversationToken，都存在过期时间。你必须在过期之前回复消息，否则会导致调用失败。通常该过期时间是足够的，你可以通过对应的接口文档了解具体的过期时长。                                                                                                                       |
+| 使用建议 | 在没有聊天上下文的场景下，需要主动发送消息到单聊或群聊会话的时候，**只能**使用主动发送模式。                                                                                                                                                                                                        | 当你希望通过 AI 助理（或机器人）回复来自聊天会话中对话请求时候，强烈建议优先采用回复消息模式。当然，在这个场景下，你也可以使用主动发送模式，这种时候需要针对每种会话类型（单聊、群聊、魔法棒）分别实现对应的接口调用，否则会导致部分场景下功能异常。                                                                                                                                         |
+
+## 接口说明
+
+### 回复消息模式
+
+| API                                                                                                                               | 说明                         | 使用场景                                                                                                                                                                             |
+|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [AI 助理回复消息（SessionWebhook 方式）](https://open.dingtalk.com/document/ai-dev/ai-assistant-message-sending-webhook-reply-message-mode) | 通过 SessionWebhook 来回复用户的消息 | 在 SessionWebhook 未过期场景下，采用该接口更简单易用。SessionWebhook 通过 TLS 安全信道和短周期的过期时间确保了其安全性，采用简单的 HTTP POST 方式即可完成调用，无需额外鉴权动作。SessionWebhook 的过期时间设计上，会满足绝大多数场景，如果你的场景是收到请求后立即回复，可以忽略该过期时间的约束。 |
+| [AI 助理回复消息（OpenAPI 方式）](https://open.dingtalk.com/document/orgapp/ai-assistant-messages-reply-mode)                               | 通过 OpenAPI 来回复用户的消息        | 在 SessionWebhook 过期的场景下，选择回复消息模式的话，只能采用 OpenAPI 方式，需要按照 OpenAPI 调用规范，首先通过应用的 Client ID 和 Client secret 换取访问凭证（AccessToken），并使用访问凭证调用该接口。                                         |
+
+### 主动发送模式
+
+#### 直接发送
+
+如果你的消息是一条完整且独立的消息，发送完成后不需要持续更新它，例如文本、图片、互动卡片等，可以使用该方法发送消息。
+
+| API                  | 说明        | 使用场景                        |
+|----------------------|-----------|-----------------------------|
+| [AI 助理发消息（主动发送模式）](https://open.dingtalk.com/document/orgapp/api-send) | 直接发送一条消息  | 主动发送一条完整的消息，例如文本、图片、互动卡片消息等 |
+
+#### 分步发送
+
+如果你希望引入打字机模式，发送后还能持续更新该消息内容。可以使用以下分步发送消息的接口，请务必按照预备、更新、结束的顺序来调用。
+
+| API                                                                         | 说明                                  |
+|-----------------------------------------------------------------------------|-------------------------------------|
+| [AI 助理预备发消息（主送发型模式）](https://open.dingtalk.com/document/orgapp/api-prepare) | 给用户发送一个状态为“准备中”的消息框，开发者收到钉钉颁发的会话凭证。 |
+| [AI 助理更新消息（主动发送模式）](https://open.dingtalk.com/document/orgapp/api-update)   | 开发者使用会话凭证更新消息框中的内容，可以多次更新。          |
+| [AI 助理结束发消息（主动发送模式）](https://open.dingtalk.com/document/orgapp/api-finish)                                                      | 结束该消息。                              |
+
+## 总结
+
+以上文档内容，描述了 AI 助理发送消息的各种接口及使用场景。如果想要了解完整的操作步骤，可以参考参考以下教学文档：
+
+* [AI 助理发消息 - 回复消息模式](https://open.dingtalk.com/document/ai-dev/ai-assistant-message-sending-openapi-reply-message-mode)
+* [AI 助理发消息 - 主动发送模式](https://open.dingtalk.com/document/ai-dev/ai-assistant-messaging-active-sending-mode)
+
+## 参考资料
+
+* [AI 助理概述](https://open.dingtalk.com/document/ai-dev/introduction-to-ai-assistant)

docs/develop/permission/single_to_multi/new_get_app_token.md

@@ -2,20 +2,37 @@
 sidebar_position: 3
 ---
 
-# 获取应用的Access Token [新🔥]
+# 获取应用的 Access Token [新🔥]
 
-企业内部应用推荐使用此文档获取Access Token，原文档[获取企业内部应用的accessToken](https://open.dingtalk.com/document/orgapp/obtain-the-access_token-of-an-internal-app)由于一些局限性，比如不能满足应用从单组织到多组织的切换等，将逐步下线。
+如果你的应用使用到了应用权限点，推荐你使用此文档获取应用的 Access Token。
 
+:::info Note
+**一个应用在开发时，就是一个应用。应用只有在被分发时，才被区分为"内部"还是"三方"。**
+- 原来的钉钉开放平台应用在创建时就区分了"企业内部应用"和"企业三方应用"，但随着业务的发展，平台和开发者们逐渐发现应用在开发时没有必要区分是"内部"还是"三方"。
+- 如果这个应用最终仅被应用开发者组织使用，即应用被分发给开发者组织，那么这个应用可以被称为企业内部应用。
+- 如果这个应用最终通过应用市场被其他组织使用，即应用被分发给其他组织使用，那么这个应用可以被称为企业三方应用。
+:::
+
+:::info Note
+* 企业内部应用由于只能运行在开发该应用的组织里，因此被归类为**单组织应用（Single-tenant Application）**。
+* 企业三方应用、企业上下游应用和企业上下级应用等应用由于能通过应用市场开通、上下游分发等分发渠道，最终运行在多个组织内，因此被归类为**多组织应用（Multi-tenant Application）**。
+:::
+
+:::info Note
+**推荐使用此文档获取应用的 Access Token，原来的一些文档由于存在局限性（比如不能满足应用从单组织到多组织的快速切换），将逐步下线。**
+- 原来企业内部应用获取应用 Access Token 的文档为：[获取企业内部应用的 Access Token](https://open.dingtalk.com/document/orgapp/obtain-the-access_token-of-an-internal-app)
+- 原来企业三方应用获取应用 Access Token 的文档为：[获取第三方应用授权企业的 Access Token](https://open.dingtalk.com/document/isvapp/obtain-the-access_token-of-the-authorized-enterprise)
+:::
 
 ## 一、获取应用的 ClientId 和 ClientSecret
-1. 登录钉钉开发者后台
+1. 登录钉钉开发者后台。
 2. 进入已创建的应用，在“凭证与基础信息”里可以看到应用的 ClientId 和 ClientSecret 。
    ![应用的ClientId和ClientSecret](/img/develop/permission/client_id_secret.png)
 
 
 ## 二、请求方法
 ```http request
-POST /oauth2/{corpId}/token HTTP/1.1
+POST /v1.0/oauth2/{corpId}/token HTTP/1.1
 Host:api.dingtalk.com
 Content-Type:application/json
 
@@ -26,12 +43,12 @@ Content-Type:application/json
 }
 ```
 
-| 参数            | 是否必填 | 说明                            |
-|:--------------|:-----|:------------------------------|
-| corpId        | 是    | 组织ID，应用运行在哪个组织就填写哪个组织的corpId。 |
-| client_id     | 是    | 应用的 ClientID。                 |
-| client_secret | 是    | 应用的 ClientSecret。             |
-| grant_type    | 是    | 必须是client_credentials。        |
+| 参数            | 是否必填 | 说明                             |
+|:--------------|:-----|:-------------------------------|
+| corpId        | 是    | 组织ID，应用运行在哪个组织就填写哪个组织的 corpId。 |
+| client_id     | 是    | 应用的 ClientID。                  |
+| client_secret | 是    | 应用的 ClientSecret。              |
+| grant_type    | 是    | 必须是 client_credentials。        |
 
 
 ```http title="成功的响应"
@@ -49,12 +66,12 @@ Content-Type:application/json
 
 ## 错误码
 
-| 状态码 | 错误码                    | 错误原因                      |
-|-----|------------------------|---------------------------|
-| 400 | invalid.client         | 无效的ClientID或ClientSecret。 |
-| 400 | unsupported.grant.type | 不支持此授权类型，请检查授权类型参数。       |
-| 400 | unauthorized.client    | 应用未被授权。                   |
-| 500 | server.error           | 服务器意外错误。                  |
+| 状态码 | 错误码                    | 错误原因                         |
+|-----|------------------------|------------------------------|
+| 400 | invalid.client         | 无效的 ClientID 或 ClientSecret。 |
+| 400 | unsupported.grant.type | 不支持此授权类型，请检查授权类型参数。          |
+| 400 | unauthorized.client    | 应用未被授权。                      |
+| 500 | server.error           | 服务器意外错误。                     |
 
 
 

docs/explore/tutorials/stream/bot/java/create-bot.md

@@ -22,7 +22,7 @@ sidebar_position: 2
        钉钉开放平台全新升级后，采用“**以应用为中心**”的理念构建 PaaS 开放能力。包括工作台网页应用、机器人、酷应用等，都作为应用扩展能力的形式来开放。<br />
        因此，以前跟应用并列的“机器人”将逐渐退出历史舞台。不要选择“钉钉应用”并列的“机器人”入口来创建，而是先创建“钉钉应用”，然后进入创建的应用，在应用内创建应用的机器人扩展。
        :::
-4. **获取应用凭证**。完成以上步骤成功创建应用之后，进入应用详情页，在左侧导航中，点击“应用信息”，可以查看到应用凭证信息。
+4. **获取应用凭证**。完成以上步骤成功创建应用之后，进入应用详情页，在左侧导航中，点击“凭证与基础信息”，可以查看到应用凭证信息。
     1. 可以点击复制后保存 Client ID（即 AppKey）和 Client Secret（即 AppSecret），用于后续的代码开发；
     2. 关于 Client ID 和 Client Secret 命名<br />
        :::info 提示信息
@@ -31,11 +31,15 @@ sidebar_position: 2
        原 AppSecret 和 SuiteSecret 逐渐统一成 Client Secret。<br />
        在很长一段的过渡期内，相关控制台页面和文档将会提供命名变更提示，帮助开发者理解这个变化。
        :::
-5. **在应用内创建机器人**。完成以上步骤成功创建应用之后，进入应用详情页，在左侧导航中，点击“机器人与消息推送”，开启“机器人配置”，按照表单内容填写机器人信息后，点击“发布”即可完成应用内机器人创建。
+5. **在应用内创建机器人**。完成以上步骤成功创建应用之后，进入应用详情页，在左侧导航中，点击“添加应用能力”添加机器人，开启“机器人配置”，按照表单内容填写机器人信息后，点击“发布”即可完成应用内机器人创建。
     1. 注意：消息接收模式选择 Stream 模式，其他模式需要更复杂的开发方式，不在本教程中提供。
-    2. 开启应用内机器人示意图：<br />![开启机器人](/img/explore/stream/bot/enable-chatbot.jpg)
+    2. 添加应用机器人示意图：<br />![添加机器人](/img/explore/stream/bot/add-chatbot.jpg)
+    3. 开启应用内机器人示意图：<br/>![开启机器人](/img/explore/stream/bot/enable-chatbot-v2.jpg)
 
-至此，你已成功完成机器人应用的创建，可以在后续的章节中学习如何开发相关机器人服务代码。
+6. **创建版本发布**。在左侧导航栏点击**版本创建与发布**，填写版本信息进行点保存后发布即可。
+    1. 版本发布示意图:<br />![创建版本](/img/explore/stream/bot/publish-bot.jpg)
+
+至此，你已成功完成机器人应用的创建并发布，可以在后续的章节中学习如何开发相关机器人服务代码。
 
 ## 相关链接