使用 discourse-chat-integration 插件来整合 Slack 通知

[honeymoose]

本部分中的内容，翻译在官方的：Set up Slack notifications using the discourse-chat-integration plugin - Integrations - Discourse Meta

本主题对如何在 Slack 中整合 Discourse 进行讨论和说明，在启用功能之前，需要启用 discourse-chat-integration 插件。

本插件允许把通知推送到 Slack 上，并且使用 Slash 命令行工具来把内容提交回 Discourse 安装实例。Slash 命令行工具（Slash command）的使用可用通过在 Slack 中输入 /discourse help 来获得帮助。IM 消息的发送和接收也可用通过上下文的方式来创建。

安装

如还没有安装 Discourse 聊天整合插件的话，请访问 Discourse Chat（聊天）工具整合 中的内容来进行安装。同时需要确定 chat integration enabled 配置启用。

根据安装的版本的不同，针对 Slack 的话，还需要启用 Slack 的整合。

设置 Slack

1. 访问 Slack API: Applications | Slack 链接，然后创建一个新的 app。如果你还没有登录的话，需要提示进行登录。针对一个特定的 Discourse 安装实例，我们只能使用一个 Slack 的空间。在 Slack 中成为 WorkSpace，因为针对这个安装好的空间，Slack 需要提供 Key 和 Token 来进行通讯。

2. 单击创建新 App（Create New App）按钮。

3. 在后续的页面中，选择 From Scartch，这里表示的是从头开始创建。

4. 选择一个名称，在这里可用选择你任何喜欢使用的名称，然后针对后面的 Slack Team，你需要选择你的 Slack Team。通常来说在 Slack 中有很多的 Team，如果不想和已有的 Team 搞乱的话，管理员可以在这里重新创建一个 WorkSpace。

例如，在这里，我们就自己创建了一个新的 WorksSpace 叫做 iSharkFly。

5. 选择 Slack 的左侧导航菜单中，在 “Features” 下单击 “OAuth & Permissions”

6. 在当前的页面中往下翻页到 “Scopes / Bot Token Scopes”，然后添加下面 的内容到你启用的 Slack workspace 下：
   • chat:write
   • chat:write.customize

针对 Slack commands 和 对话发布（transcript posting ） 功能，你还需要添加下面的配置（如果你不需要这个功能的话，可以直接忽略本部分的参数）

7. 添加下面的 Scopes 到 “Scopes / Bot Token Scopes”

   • users:read
   • channels:history
   • groups:history
   • im:history

8. 在左侧菜单的 “Features”，然后选择 Slash Commands 页面 单击 Create New Command

在弹出的对话框中需要输入下面的一些参数：

• Command - /discourse
• Request URL - <your-discourse-url>/chat-integration/slack/command
• Short Description - Manage this channel's integration with Discourse
• Usage Hint - [watch|thread|follow|mute|remove|status|post|help]

Note: 注意，如果你希望使用你的 Slash 命令不同于 /discourse (例如，你可以选择和你站点相同的命令名称)，你可以调整帮助显示的文本内容，这部分的配置是在你的 Discourse 实例上进行配置的。进入 Discourse 管理员控制面板，然后选择 Customize → Text Content → search 搜索下下面的配置然后修改 /discourse 来满足你的的命令。

- "`chat_integration.provider.slack.help`"
- "`chat_integration.provider.slack.status.no_rules`"
- "`chat_integration.provider.slack.parse_error`"
- "`chat_integration.provider.slack.delete.error`"

9. Save

10. 进入 Interactivity & Shortcuts 页面，启用Interactivity ，通过单击页面上的按钮改变为 by switching it to On 同时在 “Request URL” 选项卡中输入下面的内容：

    <your-discourse-url>/chat-integration/slack/interactive
    

需要注意的是，你需要修改上面的 Discourse 安装实例地址，并且使用 https。

11. Save Changes

12. 进入 Interactivity & Shortcuts 页面，单击Create new Shortcut, 选择 “On messages”，然后单击 Next，在页面中输入下面的内容：

    • Name: “Post to Discourse” (可以随便修改你想要的名字)
    • Short description: “Create a transcript to post on Discourse” (可以随便修改为你想要的注释)
    • Callback ID: post_shortcut (不能修改)

12. 进入设置下面的 > Install App 页面，单击 Install to Workspace，然后对 WorkSpace 进行授权。

授权成功后，将会返回一个很长的 OAuth Token，保存下这个 Token，我们稍后需要把这个 Token 填回 Discourse。

13. 拷贝 OAuth Access Token 然后粘贴到 Discourse 安装实例中的配置chat_integration_slack_access_token 下。

14. 进入 Slack 的 Basic Information 页面，然后拷贝 Verification Token 后，把值张贴回 Discourse 站点设置的 chat_integration_slack_incoming_webhook_token 参数下。

Discourse 在这里需要回填总计 2 个 Token。

15. 在 Slack 的 Basic Information 页面，你可以设置机器人的 Icon，名字，描述等。在这里我们就不进行设置了，使用默认的就好了。

16. 设置规则 “Rules” ，这个设置是在 Discourse 中进行设置，这个规则的设置目的就是为了告诉 Slack 那些操作回触发相关的消息。规则的设置是在 discourse-chat-integration 插件中进行的，如果不设置规则，Slack 是没有办法进行任何消息操作的。

17. 添加 Discourse bot 用户到 Slack 的 Channels 下：

    • 在 Slack 的左侧客户端页面中，右键单击 Channel 的名字，然后选项 View Channel Details:
      
    • 在弹出的窗口中选择 Integrations 标签页
    • 在整合标签页中，你可以选择 Add an App 然后选择 Discourse Bot:
      
    • Discourse 和 Slack 的整合现在应该完成了。

升级到 ‘Granular Scopes’

如果你的 Discourse 安装实例和 Slack 的整合在很多年就已经完成了的话，那么你可能需要升级到 Slack 的 “Granular Scopes” 好让 Slack 能够和上面描述的一样正常工作。

Instructions

1. 进入 Slack API: Applications | Slack 然后选择你的 Discourse integration app
2. 在左侧，选择 “Update to Granular Scopes”
   
3. 在 “Bot Token Scopes” 中，选择 chat:write 和 chat:write.customize，如果你正在使用 Slash 命令或者 transcript posting 的话，还需要同时选择users:read, channels:history, groups:history, im:history。然后取消选择其他的 Scopes。
4. 单击下一步
5. 取消所有的用户 Scope Token—— 我们已经不需要这些配置了。
6. 单击下一步继续，然后选择 “Yes, Migrate my app” 来完成整合。
7. 在 Slack 的左侧选择 “Install App”，然后选择 “Reinstall to Workspace”
8. 拷贝 “Bot User OAuth Token” 后张贴到 Discourse 安装实例下的 “chat_integration_slack_access_token” 参数配置。
9. 在 Slack 下的 “Apps”，选择 Discourse app 整合
10. 单击名字，然后 “Add this app to a channel”
11. 选择你希望 Discourse 添加到的 channels 下面，然后单击完成。
12. 完成:tada:

问题和解决

/discourse slash command returns dispatch_failed 错误

问题

当完成配置好 Slack 后，输入命令，Slack 可能会提示 /discourse slash command and see the following error` 错误。

/discourse failed with the error "dispatch_failed"

原因

这种情况更多的可能是因为 Discourse 和 Slack 的配置错误。

请确认 Request URL 配置是正确的，这个参数应该是：

<your-discourse-url>/chat-integration/slack/command

修正

更新你的 Request URL 并且针对下面的内容特别留意一下：

1. 确定请求 URL 的返回参数中有协议的标记，例如 https://
2. 确定配置的域名是 Discourse 安装实例的域名，而不是 Slack 的域名。
3. 确定调用的路径是正确配置为 /chat-integration/slack/command

[honeymoose]

这算是整合好了。

Slack 的坑还蛮多的，先吧主题列在这里吧，等后面随时再补充。