让消息连接业务
让服务抵达用户

01 / 群聊 Webhook

把业务通知送进群聊

适合监控告警、构建部署、订单状态和任务通知。由你的服务端发起 HTTP POST 请求，群成员在长勺中接收消息。

三步完成接入

1. 在群聊中创建推送

   使用群主账号，进入目标群的「消息推送」，填写名称和简介。每个群最多创建 5 个 Webhook。

2. 保存专属地址

   创建或重新生成时，复制完整 Webhook 地址。把它作为服务端配置 WEBHOOK_URL 保存；地址中的 key 是调用凭证，不要写入网页或公开仓库。

3. 发送第一条文字消息

   在终端中设置 WEBHOOK_URL 为刚复制的完整地址，再执行下方示例。每个新业务事件使用新的 request_id，同一事件重试时复用原值。

curl --request POST "$WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "msgtype": "text",
    "request_id": "deploy-20260918-0001",
    "text": {
      "content": "**部署完成**\n服务已更新，点击[查看详情](https://example.com/releases/1)",
      "mentioned_all": false
    }
  }'

消息格式与返回值

轻量 Markdown 支持粗体、行内代码、代码块、引用、列表、分隔线及 HTTP/HTTPS 链接。标题、表格、远程图片和 HTML 不按富文本执行。

{
  "msgtype": "news",
  "request_id": "release-20260918-0001",
  "news": {
    "articles": [{
      "title": "新版本已发布",
      "description": "查看本次更新内容",
      "url": "https://example.com/releases/1",
      "picurl": "https://example.com/images/release.png"
    }]
  }
}

{
  "errcode": 0,
  "errmsg": "ok",
  "msgid": "1234567890123456789"
}

errcode=0 表示消息已受理，msgid 为字符串形式的消息 ID。请检查 JSON 中的 errcode，不要只判断 HTTP 状态码；受理成功不代表所有成员已经阅读。

轻量 Markdown：语法与完整示例

Webhook 文字消息默认按轻量 Markdown v1 展示。保持 msgtype: "text"，把 Markdown 写入 text.content，无需使用额外的 markdown 消息类型。

先将 WEBHOOK_URL 设置为群聊推送提供的完整地址，再执行下面的请求。JSON 中使用 \n 表示换行；由程序生成正文时，交给 JSON 序列化工具处理转义。请为新的业务事件更换 request_id。

curl --request POST "$WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --data '{
  "msgtype": "text",
  "request_id": "markdown-20260918-0001",
  "text": {
    "content": "**部署完成**\n> 生产环境健康检查通过\n\n- 服务：`api-service`\n- 版本：`2.2.2`\n\n1. 检查服务状态\n2. 查看发布日志\n\n```text\nstatus: ok\n```\n\n---\n[查看发布详情](https://example.com/releases/1)",
    "mentioned_all": false
  }
}'

**部署完成**
> 生产环境健康检查通过

- 服务：`api-service`
- 版本：`2.2.2`

1. 检查服务状态
2. 查看发布日志

```text
status: ok
```

---
[查看发布详情](https://example.com/releases/1)

status: ok

不支持标题、表格、远程图片、HTML、脚本、数学公式和复杂嵌套；这些内容按普通文字显示，不执行或加载。Markdown 标记也计入 1024 字符上限。通知、会话摘要、搜索和引用摘要会转为纯文本，不能依赖粗体等格式传递唯一信息。

调用限制与错误处理

02 / 智能客服

把网站访客接入你的服务

在长勺中配置客服，再将生成的代码放进网站。访客无需登录，可发送文字、表情和图片；客服在长勺中接待咨询。

先配置，再复制代码

1. 创建专属客服

   在长勺的「智能客服」中创建客服，填写名称和欢迎语，开启服务。

2. 配置接待入口

   按需设置浮窗图标、主题颜色、电话和微信联系方式。AI 能力跟随当前账号的管家设置。

3. 复制「嵌入第三方」代码

   选择全屏、移动端或浮窗模式，复制客服配置页生成的完整代码。下面的 YOUR_SERVICE_ID 仅为占位符，必须替换为你自己的客服 ID。

选择网站中的展示方式

<!-- 将 YOUR_SERVICE_ID 替换为客服配置页提供的服务 ID -->
<script async
  src="https://web.cszn.cc/support/embed.js"
  data-service="YOUR_SERVICE_ID"
  data-frame="https://api.cszn.cc/im/support-public/frame/YOUR_SERVICE_ID?mode=float"
></script>

<iframe
  src="https://api.cszn.cc/im/support-public/frame/YOUR_SERVICE_ID?mode=fullscreen"
  title="在线客服"
  referrerpolicy="origin"
  style="width:100%;height:100dvh;min-height:480px;border:0;display:block"
></iframe>

<iframe
  src="https://api.cszn.cc/im/support-public/frame/YOUR_SERVICE_ID?mode=mobile"
  title="在线客服"
  referrerpolicy="origin"
  style="width:100%;height:100dvh;min-height:480px;border:0;display:block"
></iframe>

上线前，检查这四项

• 客服已开启，名称与欢迎语显示正确。
• 服务 ID 与配置页一致，代码示例中的占位符已替换。
• 使用网站实际域名打开页面，确认脚本与 iframe 能正常加载。
• 由测试访客发送一条咨询，在长勺端确认收到消息并回复。

如果网站启用了 CSP，请允许 https://web.cszn.cc 的脚本，以及 https://api.cszn.cc 的 frame 和连接。保留 iframe 的 referrerpolicy="origin"；服务暂停后，访客页面会显示暂停状态。