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

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>

<script async
  src="https://web.cszn.cc/support/embed.js"
  data-service="YOUR_SERVICE_ID"
  data-mode="fullscreen"
  data-frame="https://api.cszn.cc/im/support-public/frame/YOUR_SERVICE_ID?mode=fullscreen"
></script>

<script async
  src="https://web.cszn.cc/support/embed.js"
  data-service="YOUR_SERVICE_ID"
  data-mode="mobile"
  data-frame="https://api.cszn.cc/im/support-public/frame/YOUR_SERVICE_ID?mode=mobile"
></script>

访客信息与自定义业务参数

接入脚本自动同步访客当前页面的 URL 和标题，支持单页应用路由变化。客服可在会话内展开「访客信息」，查看页面、用户 ID 和业务参数。页面可见时每 2 秒检查变化，只在内容改变时同步。

将初始化代码放在嵌入脚本之前，用站点自己的用户与业务数据替换示例值。脚本不会读取站点的 Cookie、登录信息或本地存储。

window.LadleSupport = window.LadleSupport || {};
window.LadleSupport.contexts = window.LadleSupport.contexts || {};
window.LadleSupport.contexts["YOUR_SERVICE_ID"] = {
  userId: "user-12345",
  attributes: { "昵称": "张三", "套餐": "专业版", "订单号": "ORDER-001" }
};

登录、切换订单或退出登录后，可在嵌入脚本加载完成后更新：

// 登录或业务信息改变后
window.LadleSupport.setContext("YOUR_SERVICE_ID", {
  userId: "user-12345",
  attributes: { "套餐": "专业版", "订单号": "ORDER-002" }
});
// 退出登录后清除业务身份与参数
window.LadleSupport.setContext("YOUR_SERVICE_ID", {
  userId: null, attributes: {}
});

setContext 合并顶层字段；传入 attributes 会整体替换旧参数。业务用户 ID 仅供客服参考，不用于身份认证或合并会话。不要传入密码、令牌或密钥。脚本会过滤 URL 中常见敏感查询参数，但接入站点仍应避免在地址和标题中放置敏感信息。

旧版原生 iframe 接入仍可聊天；如需自动同步宿主页面与使用下方事件，请改用上述脚本接入。

自定义客服对话框头像

进入「发现 → 智能客服」，在客服配置中的「对话框头像」上传专属 Logo。未设置时使用客服所属账号的头像；选择「使用账号头像」可恢复默认。对话框头像与浮窗入口图标分别配置。

打开事件与前置消息

在嵌入脚本之前监听 ladle-support:open。站点可在访客打开客服时发送订单或咨询背景，消息以访客身份进入会话并参与 AI / 人工接待，不覆盖输入框草稿。

window.addEventListener("ladle-support:open", async ({ detail }) => {
  if (detail.serviceId !== "YOUR_SERVICE_ID" || !detail.firstOpen) return;
  try {
    await detail.sendMessage("我想咨询订单 ORDER-001", {
      requestId: "order-ORDER-001"
    });
  } catch (error) {
    console.error("前置消息未发送", error);
    // 如需重试，请复用原 requestId，避免重复入库。
  }
});

firstOpen 指本次网页加载后的第一次打开，不代表访客首次咨询。跨刷新去重请使用同一业务事件的固定 requestId；新事件换新 ID。全屏与移动端模式会在初始化打开时触发事件。

// 在脚本加载完成、对话框已打开后调用
window.LadleSupport.sendMessage(
  "YOUR_SERVICE_ID", "补充咨询订单 ORDER-002",
  { requestId: "order-ORDER-002" }
).then(() => {
  console.log("消息已入库");
}).catch(error => {
  console.error("消息未确认发送", error);
});

消息不能为空，最长 4000 字符。requestId 可选，默认随机生成；自定义值为 8–64 位字母、数字、点、下划线、冒号或短横线。同一会话内按请求 ID 去重。连接建立前会排队，30 秒未确认则 Promise 拒绝；超时不一定代表未入库，重试必须复用同一 ID。成功表示消息已入库，不代表客服已阅读；对话框未打开、脚本未就绪或重复发送中的请求会返回错误。

上线检查 · 最新接入能力

更新于 2026 年 10 月 20 日。上线前请使用真实站点域名，逐项验证以下能力。

• 客服已开启，名称、欢迎语、主题与对话框头像正确；未设置头像时使用账号头像。
• 所有 YOUR_SERVICE_ID 已替换，同一客服服务仅加载一次脚本；事件与初始化参数在脚本之前注册。
• 浮窗、全屏或移动端模式可正常加载；手机键盘弹起后输入区仍可操作。
• 访客发送文字、表情和图片，客服端能收到并回复。
• 切换页面或 SPA 路由后，客服会话中的当前页面、标题与自定义参数同步更新。
• 登录与退出登录时同步更新或清除 userId 和业务参数，参数中不包含密码、令牌和密钥。
• 打开客服时前置消息成功入库；关闭再打开、刷新及失败重试不重复发送同一业务事件。
• 客服服务暂停、网络异常及发送失败时有可处理的反馈。

如果网站启用了 CSP，请允许 https://web.cszn.cc 的脚本与 https://api.cszn.cc 的 frame 和连接。站点内联初始化代码需按自身 CSP 使用 nonce、hash 或独立脚本。图片来源也需符合站点策略；不要为接入关闭整体安全策略。