企业官网建设流程全解析

Zulip Delighted 集成指南：将客户满意度调查反馈实时同步到团队聊天

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip

Delighted 是常用的客户体验（CX）与 NPS（净推荐值）调查工具，用于收集用户对服务的满意度评分与文字反馈。本指南讲解如何将 Zulip 的 Delighted 官方集成接入你的组织：从创建 Incoming webhook 机器人、生成集成 URL，到在 Delighted 仪表盘完成 Webhook 配置，并深入解析 view.py 中消息格式化与分数阈值处理的底层实现，以及仓库内对应的 测试用例 与 事件 fixtures。读完本文，你将能够在 Zulip 中实时接收每一次调查回复，并掌握该集成的消息结构与扩展思路。

一、集成能力概览

该集成将 Delighted 中“调查回复更新”（survey_response.updated）这一事件实时推送到 Zulip 的指定主题中。每当你收到一条新的客户反馈（分数 + 评语），团队就能在 Zulip 里第一时间看到通知，无需再频繁刷新 Delighted 后台。

从仓库的集成注册表 zerver/lib/integrations.py 可以看到，该集成被归类为customer-support与marketing两大使用场景：

IncomingWebhookIntegration( "delighted", ["customer-support", "marketing"], [WebhookScreenshotConfig("survey_response_updated_promoter.json")], ),

这也从侧面说明：Delighted 反馈不仅适合客服团队跟进负面评价，也适合市场/产品团队追踪正面口碑。

二、第一步：创建 Incoming webhook 机器人

所有 Zulip 的第三方 Webhook 集成都依赖专用机器人账号来发送消息。按官方模板 create-an-incoming-webhook.md 的操作指引：

1. 进入 Zulip 的Settings → Personal → Bots（或通过/help/add-a-bot-or-integration帮助页直达）。
2. 点击Add a new bot。
3. 为机器人命名（例如Delighted Bot）。
4. Bot type 必须选择Incoming webhook——这是集成能够接收外部请求并以机器人身份发消息的前提。

创建成功后，系统会分配该机器人专属的API key，稍后生成 Webhook URL 时会用到。

三、第二步：生成集成 URL

按照 generate-webhook-url-basic.md 的说明，你需要决定将通知发送到哪个频道（stream），然后通过 Zulip 的/help/generate-integration-url帮助页生成集成 URL。

Zulip Incoming webhook URL 遵循统一的规范格式（完整规范见仓库文档 docs/webhooks/incoming-webhooks-overview.md）：

https://<your-zulip-host>/api/v1/external/delighted?api_key=<机器人API Key>&stream=<目标频道名>

其中：

• <your-zulip-host>：你的 Zulip 服务器地址；
• api_key：刚才创建的 Incoming webhook 机器人专属密钥，用于身份认证；
• stream（可选）：指定接收通知的频道，不填时默认发送到#zulip（一般建议显式指定业务频道，如#customer-feedback）。

该 URL 是 Delighted 端唯一需要填写的信息，也是安全敏感信息——它等同于向持有者开放了往你的频道发送消息的权限，请妥善保管，不要泄露到公开渠道。

四、第三步：在 Delighted 仪表盘配置 Webhook

打开 Delighted 后台，按 doc.md 的步骤操作：

1. 点击页面右上角的 Settings（设置）。
2. 选择Integrations（集成），再选择Webhooks。
3. 在Send webhook notifications for（发送 Webhook 通知的订阅项）下方，将Webhook URL设置为上一步生成的集成 URL。
4. 点击Save and turn on（保存并启用），完成启用。

启用后，Delighted 会在调查回复更新事件发生时，向该 URL 发送 JSON 格式的 POST 请求，Zulip 端随即把反馈以消息形式投递到指定主题。

五、消息格式与 NPS 分数阈值（源码解析）

消息如何组织、如何区分好评与普通反馈，均由 view.py 决定。核心逻辑非常简洁：

PROMOTER = """ Kudos! You have a new promoter. Score of {score}/10 from {email}: ``` quote {comment}

""".strip()

FEEDBACK = """ Great! You have new feedback. Score of {score}/10 from {email}:

{comment}

""".strip()

def body_template(score: int) -> str: if score >= 7: return PROMOTER else: return FEEDBACK

可以提炼出三个关键设计点： - **分数阈值**：当 `score >= 7` 时使用 `PROMOTER` 模板（消息以 “Kudos! You have a new promoter.” 开头）；否则使用 `FEEDBACK` 模板。注意这与标准 NPS 的三档划分（0-6 贬损者、7-8 被动者、9-10 推荐者）并不完全一致，是从源码结构上**将 7 分及以上统一视为正面反馈**的简化实现——如果希望严格按 NPS 口径拆分 7-8 分，可以在此函数基础上扩展。 - **消息主题固定**：`topic_name = "Survey response"`，所有 Delighted 通知都聚合在 `delighted > Survey response` 这一主题下，便于集中检索与归档（如截图所示）。 - **模板渲染**：分数、邮箱、评语通过 `str.format` 注入模板，评语以 `quote` 引用块形式展示，突出原始反馈文本。 ### Webhook 视图的处理流程 ```python @webhook_view("Delighted") @typed_endpoint def api_delighted_webhook( request: HttpRequest, user_profile: UserProfile, *, payload: JsonBodyPayload[WildValue], ) -> HttpResponse: person = payload["event_data"]["person"] email = person["email"].tame(check_string) score = payload["event_data"]["score"].tame(check_int) comment = payload["event_data"]["comment"].tame(check_string) ... check_send_webhook_message(request, user_profile, topic_name, body) return json_success(request)

请求处理链路为：

1. @webhook_view("Delighted")装饰器负责鉴权，校验请求中携带的api_key对应的 Incoming webhook 机器人；
2. @typed_endpoint+JsonBodyPayload[WildValue]解析 JSON 请求体，并用tame(check_string)/tame(check_int)对email、score、comment做类型校验；
3. check_send_webhook_message将渲染好的消息发送到指定主题，最终返回json_success。

六、Webhook 载荷结构（fixtures 解析）

仓库在 fixtures 目录下保存了两种典型事件的样例载荷，可直接用于本地联调：

• survey_response_updated_promoter.json：评分 9 的推荐者反馈；
• survey_response_updated_non_promoter.json：评分 5 的普通反馈。

两者结构完全一致，核心字段如下：

{ "event_type": "survey_response.updated", "event_id": "b8d057c59327...cbd0", "event_data": { "id": "5435", "person": { "id": "5975", "email": "charlie_gravis@example.com", "name": "Charlie Gravis", "created_at": 1482589349 }, "score": 9, "comment": "Your service is fast and flawless!", "permalink": "https://delighted.com/r/5pFDpmlyC8GUc5oxU6USto5VonSKAqOa", "created_at": 1482589409, "updated_at": 1482590009, "person_properties": null, "notes": [], "tags": [] } }

集成真正消费的只有event_data下的三个字段：

event_data中的permalink、notes、tags、person_properties等字段当前未被消费，若想增强通知内容（例如附上反馈详情链接、展示标签），可以扩展 view.py 的字段提取逻辑。

七、测试与验证

仓库为集成提供了完整的自动化测试：tests.py，覆盖了正反两种分数场景：

• test_feedback_message_promoter：以survey_response_updated_promoter.json为输入，断言主题为Survey response、消息以 “Kudos! You have a new promoter. Score of 9/10 from charlie_gravis@example.com:” 开头，且评语被正确包裹在引用块中；
• test_feedback_message_non_promoter：以非推荐者 fixtures 为输入，断言使用 “Great! You have new feedback. Score of 5/10 ...” 模板。

两个用例均以content_type="application/x-www-form-urlencoded"调用check_webhook，说明该集成同时兼容表单编码与 JSON 载荷的请求体。

在本地开发环境中，你可以通过运行tools/test-backend zerver.webhooks.delighted来执行上述测试，验证集成的消息生成是否符合预期。实际接入后，可在 Delighted 后台手动触发一条测试调查回复，观察 Zulip 主题内是否出现对应通知。

八、总结

Zulip 的 Delighted 集成用极小的配置成本（一个机器人 + 一个 URL）打通了客户反馈与团队协作的链路，其核心价值在于：

• 零代码接入：全程只需在 Delighted 后台填写 URL，无需部署任何中间服务；
• 消息语义化：通过 7 分阈值自动区分“新推荐者”与“新反馈”两种通知语气，重点信息一目了然；
• 源码可定制：模板、主题名、字段提取逻辑都集中在 view.py 的数十行代码内，扩展标签、链接、评分三档划分等能力成本极低；
• 测试保障：仓库自带的 fixtures 与用例让任何修改都能被快速回归验证。

若需要深入了解 Zulip Incoming webhook 的通用机制（URL 规范、鉴权方式、消息过滤等），可继续阅读仓库文档 docs/webhooks/incoming-webhooks-overview.md。

【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip