连接 WhatsApp、Microsoft Teams 与 DHL
这份指南回答三个问题：环境 production / sandbox 是什么意思、每个参数去哪里取、连上以后怎么验证与排障。全部步骤按真实控制台路径写成，可以照着做。
一分钟看懂：连接的原理
你在后台填写的第三方账号信息，只用于让平台服务器代表你的组织去调用第三方接口。真正干活的是平台后台的常驻服务，不是你的浏览器：
- 你可以随时退出后台、关闭浏览器甚至关机，平台仍会持续收消息、自动回复与重试（这是平台服务端的能力，不靠浏览器保活）。
- 密钥（Access Token / App Secret / Client Secret / DHL API Secret）只加密保存在平台服务端，页面永远只显示掩码（如 ••••1234），也不会出现在日志里。
- 需要人工介入时，打开后台「客服工作台」即可接管会话、直接回复，或把对话交回 AI。
第 1 步 · 确认前置条件
- 后台账号需为 OWNER 或 ADMIN（OPERATOR 可以接待会话，但不能修改第三方连接；VIEWER 只读）。
- 平台需为你的组织开通对应能力。未开通时页面会提示
CAPABILITY_REQUIRED/CAPABILITY_NOT_FOUND/CAPABILITY_DISABLED—— 请联系平台客服开通后再连接。 - 回调地址必须使用平台公网地址（不要用
localhost或内网 IP）：Instagram 私信（Instagram Messaging）：https://www.aidlz.cn/api/webhooks/external/instagramLINE 官方账号（Messaging API）：https://www.aidlz.cn/api/webhooks/external/lineFacebook Messenger（Messenger Platform）：https://www.aidlz.cn/api/webhooks/external/messengerSlack（官方 App）：https://www.aidlz.cn/api/webhooks/external/slackMicrosoft Teams（Azure Bot）：https://www.aidlz.cn/api/webhooks/external/teamsTelegram（官方 Bot API）：https://www.aidlz.cn/api/webhooks/external/telegramWhatsApp Business（Cloud API）：https://www.aidlz.cn/api/webhooks/external/whatsapp
第 2 步 · 进入「第三方连接」
登录你的后台 → 左侧菜单 设置 → 第三方连接（平台控制台同名入口：/dashboard/external-connections）。页面按两类分组：
聊天渠道（CHANNEL）
Instagram 私信（Instagram Messaging） / LINE 官方账号（Messaging API） / Facebook Messenger（Messenger Platform） / Slack（官方 App） / Microsoft Teams（Azure Bot） / Telegram（官方 Bot API） / WhatsApp Business（Cloud API）
作用：把第三方消息接进来，由 AI 自动回复。
外部服务（SERVICE）
DHL Express（MyDHL API） / FedEx（官方 REST API） / 顺丰国际（丰桥开放平台） / 17TRACK（多承运商轨迹聚合） / UPS（官方 API）
作用：让 AI 能查真实运费、真实运单状态（数据来自服务商）。
每张卡片右上角的徽章就是连接状态。点击「连接 / 更新凭据」展开表单 →「保存并测试连接」。保存后会立刻执行一次真实自检：成功即显示「已连接」；失败会记录具体错误码，不会假装成功。
| 状态 | 页面显示 | 含义 |
|---|---|---|
| CONNECTED | 已连接 | 自检通过，平台会正常收发消息 / 调用该服务。 |
| DISCONNECTED | 未连接 | 已保存但尚未通过自检（例如刚更新了凭据）。点「测试连接」完成自检。 |
| AUTH_REQUIRED | 需要授权 | 缺少必要配置或凭据（如 DHL 缺少发件账号）。按提示补齐后重新测试。 |
| EXPIRED | 凭据过期 | 凭据失效（Token / Secret 过期或被重置）。回到第三方控制台重新生成并更新。 |
| ERROR | 异常 | 连续调用失败（第三方 5xx / 网络 / 限流等）。平台会持续记录并在健康巡检中自动复检。 |
| DISABLED | 已停用 | 被手动停用；不接收新事件、不发送任何消息。点「启用」恢复。 |
第 3 步 · 「环境 production / sandbox」是什么意思
目前只有 DHL 提供「环境」开关：它决定平台调用哪一套端点（测试 / 正式）。 WhatsApp 与 Microsoft Teams 没有真正生效的环境开关，因此表单里不提供该项（原因见下表）—— 平台只提供真正会改变行为的配置项。
| 服务商 | 选 sandbox 时 | 选 production 时 | 建议怎么填 |
|---|---|---|---|
| DHL Express | 调用 DHL 测试端点 https://express.api.dhl.com/mydhlapi/test，返回测试数据，不会产生真实运单与费用 | 调用正式端点 https://express.api.dhl.com/mydhlapi，真实报价、真实运单 | 先 sandbox 调通，再切 production；留空 = sandbox |
| WhatsApp 官方没有 sandbox 端点（Cloud API 只有一套地址），因此平台**不提供**「环境」开关。需要测试请使用 Meta 提供的 Test Number：它的 Phone number ID 与正式号码不同，直接填进配置即可，但只能发给最多 5 个测试接收人。 | 表单不提供该开关 | ||
| Microsoft Teams | Teams 的测试/正式由 Azure 侧决定（开发时用 Azure Bot 直接调试，正式则在 Teams 中发布），平台**不提供**「环境」开关。 | 表单不提供该开关 | |
简单结论
- 只有 DHL 需要你认真选择环境：联调用 sandbox，上线前一定切 production（sandbox 的报价与运单不是真实业务数据）。
- WhatsApp / Teams 的表单里没有「环境」项：它们没有独立的测试端点（WhatsApp 用 Meta 的 Test Number，Teams 由 Azure 侧决定），平台只提供真正生效的配置项。
- 环境不影响连接安全：无论哪个环境，凭据都加密保存、只由平台服务端使用。
Instagram 私信（Instagram Messaging）
把 Instagram 专业账号接到 AI 客服：客户在 Instagram 私信里提问 → 平台接收 → AI 自动回复（官方 Instagram Messaging，非浏览器自动化）。
你需要准备
- 一个 Instagram 专业账号（Business / Creator），且已绑定到某个 Facebook 主页
- Meta App 已添加 Instagram 产品与相应权限
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 Instagram 渠道能力
操作步骤
- 1
（推荐）用 Meta 官方授权一键连接
若平台已配置 Meta 官方应用，在「通讯渠道」点「连接 Instagram 私信（官方授权）」→ 授权你自己的账号 → 平台自动发现已绑定主页的 Instagram 专业账号并建连（未绑定主页时平台会明确提示「权限不足 / 配置不完整」，不会猜测账号关系）。
- 2
取出 Instagram 账号 ID 与主页 ID
在 Meta 后台读取该 Instagram 专业账号的数字 ID；主页 ID 取已绑定该 Instagram 账号的 Facebook 主页 ID（发送端点 /{pageId}/messages 使用主页令牌）。
- 3
在平台填写并保存
后台 → 第三方连接 → Instagram → 填 Instagram 专业账号 ID + 主页 ID + Page Access Token + App Secret + Verify Token → 「保存并测试连接」。
- 4
配置 Webhook
Meta App → Instagram → Webhooks：Callback URL 填 {平台基址}/api/webhooks/external/instagram，Verify token 与平台一致 → Verify and save；订阅 messages 字段。
- 5
真机测试
用另一个 Instagram 账号给该专业账号发一条私信，几秒内应收到 AI 回复。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Instagram 专业账号 IDigAccountId | 必填 | Meta 后台 → Instagram 面板（或 Webhook 回调里的 entry.id） | 取该 Instagram 专业账号的数字 ID。最可靠的办法：先配好 Webhook 并给它发一条私信，然后在平台该连接的 Webhook 事件里读取 entry.id。提示：必须是专业账号（Business/Creator）并已与 Facebook 主页绑定。 |
| 已绑定的 Facebook 主页 IDpageId | 必填 | Meta 后台 → 已绑定该 Instagram 账号的 Facebook 主页 | Instagram 私信通过**主页令牌**发送，因此要填该主页 ID（与 Messenger 的 pageId 同源）。Graph API Explorer 查询 /me/accounts 也可得到。提示：若主页未绑定该 Instagram 账号，发送会失败：平台会如实回报 AUTH_FAILED / PROVIDER_REJECTED，不会伪装成功。 |
| Graph API 版本apiVersion | 选填 | Meta 官方 Graph API 变更日志 | 一般留空即可，平台默认使用 v26.0。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Page Access Token（已绑定该 Instagram 账号的主页令牌）pageAccessToken | 必填 | Meta App Dashboard → Messenger → Settings → Access Tokens（选已绑定该 Instagram 账号的主页） | 生成并复制该主页的 Page Access Token（只显示一次）。提示：正式使用请用长期令牌（System users + 主页资源），避免 24 小时临时令牌过期。 |
| App Secret（Webhook 验签）appSecret | 必填 | Meta App Dashboard → App settings → Basic | 复制 App Secret（与 WhatsApp / Messenger 同一个）。 |
| Webhook Verify TokenverifyToken | 必填 | 由你自己定义 | 自定义随机字符串，与 Meta 后台 Instagram Webhook 配置里的 Verify Token 完全一致。 |
注意（真实会踩到的点）
- 两个 ID 都要正确：Instagram 专业账号 ID 决定「消息归属哪个账号」，Facebook 主页 ID 决定「用哪个令牌发送」。缺少任一，平台会明确报 CONFIG_REQUIRED，不会伪装成功。
- 24 小时窗口与 Messenger 一致：AI 回复由客户消息触发，始终落在窗口内；平台不发送营销模板。
LINE 官方账号（Messaging API）
把 LINE 官方账号接到 AI 客服：客户在 LINE 里发消息 → 平台接收 → AI 自动回复（官方 Messaging API，使用 push 发送）。
你需要准备
- 一个 LINE 官方账号（LINE Official Account）与 LINE Developers 上的 Messaging API 频道
- Channel Access Token（长期）与 Channel Secret
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 LINE 渠道能力
操作步骤
- 1
取出 Channel Access Token 与 Secret
LINE Developers → Messaging API 频道：Messaging API 设置里签发长期 Channel access token；Basic settings 里复制 Channel secret。
- 2
在平台填写并保存
后台 → 第三方连接 → LINE → 填 Channel Access Token + Channel Secret → 「保存并测试连接」（平台调用 /v2/bot/info 自检）。
- 3
配置 Webhook URL
LINE Developers → Messaging API → Webhook settings：Webhook URL 填 {平台基址}/api/webhooks/external/line → Verify；并打开 Use webhook。
- 4
真机测试
在 LINE 里给官方账号发一条消息，几秒内应收到 AI 回复。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Bot 的 User IDbotUserId | 选填 | LINE Developers → Messaging API → Bot information | 选填。复制 Bot 的 User ID（应与 Webhook 回调里的 destination 一致，便于排障核对）。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Channel Access Token（长期）channelAccessToken | 必填 | LINE Developers → 你的 Provider → Messaging API 频道 → Messaging API 设置 | 点击 Issue 生成长期 Channel access token 并复制到平台。提示：平台使用 push 消息接口发送 AI 回复（不依赖 replyToken），因此需要具备 push 权限的长期令牌。 |
| Channel Secret（Webhook 验签）channelSecret | 必填 | LINE Developers → 你的 Provider → Messaging API 频道 → Basic settings | 复制 Channel secret，用于校验 LINE 回调签名（X-Line-Signature）。 |
注意（真实会踩到的点）
- 平台使用 push 发送：AI 回复不依赖 replyToken（它一次性且约 30 秒失效），因此即使 AI 生成稍慢也能正常送达；代价是 push 计入你的 LINE 计费额度。
- 签名强制校验：X-Line-Signature 不匹配的回调一律拒绝（fail-closed），因此 Channel Secret 必须与 LINE 后台一致。
Facebook Messenger（Messenger Platform）
把 Facebook 主页接到 AI 客服：客户在 Messenger 里发消息 → 平台接收 → AI 自动回复，与 WhatsApp / Instagram 共用同一套官方 Meta 回调。
你需要准备
- 一个 Facebook 主页（需有主页管理权限）
- 已创建 Business 类型的 Meta App，并添加 Messenger 产品
- 本平台后台 OWNER / ADMIN 权限，且平台已为你的组织开通 Messenger 渠道能力
操作步骤
- 1
（推荐）用 Meta 官方授权一键连接
若平台已配置 Meta 官方应用，在「通讯渠道」点「连接 Facebook Messenger（官方授权）」→ 授权你自己的主页 → 平台自动换取主页令牌并订阅 Webhook，无需手工复制 Token。
- 2
取出主页 ID 与 Page Access Token
Meta App Dashboard → Messenger → Settings → Access Tokens：选择主页 → Generate Token → 复制 Token；同时记下主页 ID（应与 Webhook 回调的 entry.id 一致）。
- 3
在平台填写并保存
后台 → 第三方连接 → Facebook Messenger → 填入主页 ID + Page Access Token + App Secret + 自定义 Verify Token → 「保存并测试连接」，通过后徽章为「已连接」。
- 4
在 Meta 后台配置 Webhook
Meta App → Messenger → Settings → Webhooks：Callback URL 填 {平台基址}/api/webhooks/external/messenger，Verify token 填你自定义的那串 → Verify and save；再订阅 messages 字段。
- 5
真机测试
用你的 Facebook 账号给该主页发一条消息，几秒内应收到 AI 回复；平台「客服工作台」会出现该会话（带 Facebook 平台标记）。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Facebook 主页 ID（Page ID）pageId | 必填 | Meta App Dashboard → Messenger → Settings → Access Tokens 区域的主页选择器 | 选择要接入的 Facebook 主页后，页面上会显示该主页的名称与 ID；也可在主页「关于」页找到主页 ID。它必须与 Webhook 回调里的 entry.id 一致（平台会用回调里的 ID 归属会话）。提示：不确定时先配好 Webhook 后给主页发一条消息，再在平台该连接的 Webhook 事件里核对 entry.id。 |
| Graph API 版本apiVersion | 选填 | Meta 官方 Graph API 变更日志 | 一般留空即可，平台默认使用 v26.0。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Page Access Token（主页令牌）pageAccessToken | 必填 | Meta App Dashboard → Messenger → Settings → Access Tokens | 在上一步选定的主页旁点击 Generate Token，把生成的 Page Access Token 复制到平台（只显示一次）。提示：临时令牌会过期；正式使用请用长期令牌（Business Settings → System users 生成并授权主页），否则连接会变成「凭据过期」而停发消息。 |
| App Secret（Webhook 验签）appSecret | 必填 | Meta App Dashboard → App settings → Basic | 点击 App Secret 右侧的 Show，输入密码后复制（32 位十六进制）。它与 WhatsApp / Instagram 使用的是**同一个 App Secret**。提示：App Secret 重置后必须回到平台更新，否则 Webhook 会验签失败（平台按安全设计拒绝处理并留痕）。 |
| Webhook Verify TokenverifyToken | 必填 | 由你自己定义（不是 Meta 生成的） | 生成一段只有你知道的随机字符串（建议 24 字节以上）。平台填什么，Meta 后台 Messenger Webhook 的 Verify Token 就填完全相同的值。 |
注意（真实会踩到的点）
- 24 小时窗口：Messenger 只允许在客户最后一条消息后的 24 小时内发送自由文本。AI 自动回复由客户消息触发，始终落在窗口内；平台不发送营销模板。
- Page Access Token 会过期：临时令牌仅用于联调，正式请使用 System User 生成的长期令牌，否则连接会变成「凭据过期」并停止回复。
Slack（官方 App）
把 Slack 应用接到 AI 客服：团队成员在 Slack 频道/私聊里 @机器人提问 → 平台接收 → AI 自动回复。
你需要准备
- 一个 Slack workspace，且你有权限创建/安装 App
- Slack App 已开启 Event Subscriptions 并订阅 message.im / app_mention 等事件
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 Slack 渠道能力
操作步骤
- 1
（推荐）用 Slack 官方安装一键连接
若平台已配置 Slack 应用，在「通讯渠道」点「连接 Slack（官方授权）」→ 通过 Slack 的「Add to Slack」选择你自己的 workspace 并授权 → 平台自动获取 Bot Token 并建连，无需手工复制 xoxb- Token。
- 2
取出 Bot Token 与 Signing Secret
api.slack.com/apps → 你的 App：OAuth & Permissions 复制 Bot User OAuth Token（xoxb-…，至少含 chat:write）；Basic Information → App Credentials 复制 Signing Secret。
- 3
在平台填写并保存
后台 → 第三方连接 → Slack → 填 Bot Token + Signing Secret → 「保存并测试连接」（平台调用 auth.test 自检）。
- 4
配置 Event Subscriptions 的 Request URL
Slack App → Event Subscriptions：Request URL 填 {平台基址}/api/webhooks/external/slack。Slack 会立刻发 url_verification 握手，平台会自动回显 challenge；随后订阅 message.im 与 app_mention。
- 5
真机测试
在 Slack 里给机器人发一条私信或 @它，几秒内应收到 AI 回复。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Workspace（Team）IDteamId | 选填 | Slack 工作区 URL（app.slack.com/client/{TEAM_ID}）或 auth.test 返回的 team_id | 选填。留空时平台会在首条事件后自动学习并写入渠道账号，便于精确归属会话。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Bot User OAuth TokenbotToken | 必填 | api.slack.com/apps → 你的 App → OAuth & Permissions | 把 App 安装到目标 workspace 后复制 Bot User OAuth Token（xoxb-…）。至少需要 chat:write 权限才能发送消息。提示：重新安装应用或轮换令牌后，旧令牌会失效 → 平台发送会失败并记录 AUTH_FAILED，请及时回来更新。 |
| Signing Secret（Webhook 验签）signingSecret | 必填 | api.slack.com/apps → 你的 App → Basic Information → App Credentials | 复制 Signing Secret。平台用它校验 Slack 每次请求的签名，并校验时间戳（±5 分钟）防重放。提示：重置后必须同步更新，否则所有回调都会被拒绝（fail-closed）。 |
注意（真实会踩到的点）
- 签名与时间戳双重校验：平台校验 v0 签名，并拒绝时间戳偏差超过 ±5 分钟的请求（防重放）。若服务器时间不准，会导致回调被拒。
- 机器人自己的消息不会触发回复：平台会过滤 bot_id / 子类型事件，避免「AI 回复自己」形成死循环。
Microsoft Teams（Azure Bot）
把 Microsoft Teams 机器人接到 AI 客服：团队成员在 Teams 里与机器人对话，平台经 AI 处理并回复。
你需要准备
- 一个 Azure 订阅（可创建 Azure Bot 资源）
- 在 Azure 中创建 Azure Bot（或 Bot Channels Registration），并把 Channels 里的 Microsoft Teams 打开
- Teams 侧可在团队中安装该机器人（需上传 App 包或由管理员发布）
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 Teams 渠道能力
操作步骤
- 1
（推荐）用 Microsoft 官方授权连接
若平台已配置 Microsoft 多租户应用，直接在「通讯渠道」点「连接 Microsoft Teams（官方授权）」→ 由你的租户管理员完成同意 → 平台在**你自己的 Azure 订阅**中预置 Bot 并自动设置消息终结点（Azure 费用由你的订阅承担）。若平台未配置，则按下方手工步骤操作。
- 2
填写消息终结点（Messaging endpoint）
Azure Bot → Configuration → Messaging endpoint 填 {平台基址}/api/webhooks/external/teams。这是 Teams 把用户消息推给平台的入口。
- 3
取出所需的值
Configuration 里的 Microsoft App ID；Entra ID → App registrations → Certificates & secrets 新建 Client secret 并复制 Value（= App Password）；Entra ID → Overview 复制 Tenant ID（可选）。
- 4
在平台填写并保存
后台 → 第三方连接 → Microsoft Teams → 填入 App ID / App Password /（可选）Tenant ID → 「保存并测试连接」。
- 5
在 Teams 中安装机器人
把机器人 App 包（由 Azure Bot 的 Teams 渠道生成，或开发者门户创建的 Teams App）上传到团队或个人范围，然后与它对话一次。
- 6
验证
在 Teams 中给机器人发一条消息，平台会记录会话并自动回复；附件/卡片在平台内以附件与文本形式保留。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 机器人名称botName | 选填 | 仅用于展示 | 填写一个便于识别的机器人名称（例如「官网客服机器人」）。不影响功能。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Microsoft App IDappId | 必填 | Azure Portal → 你的 Azure Bot 资源 → Configuration | 复制 Microsoft App ID（与 Azure AD 应用注册中的 Application (client) ID 相同）。平台的 Webhook 会校验 Microsoft 签发的令牌，令牌里的 aud 必须等于这个 App ID，因此每个机器人必须使用独立的 Azure Bot / App ID。 |
| Microsoft App Password（Client Secret）appPassword | 必填 | Azure Portal → Microsoft Entra ID（原 Azure AD）→ App registrations → 你的应用 → Certificates & secrets | 点击 New client secret，选择有效期并创建 → 立刻复制 Value（不是 Secret ID；离开页面后无法再查看）。这就是 Microsoft App Password。提示：Client Secret 到期后连接会变为「凭据过期」，请提前在 Azure 续期并回到平台更新。 |
| Azure Tenant IDtenantId | 选填 | Azure Portal → Microsoft Entra ID → Overview | 复制 Tenant ID（Directory ID）。多租户机器人可留空；如果你的机器人是单租户（SingleTenant / 指定目录），请填写。 |
注意（真实会踩到的点）
- App ID 必须唯一：平台用 Microsoft 令牌里的 aud（= 你的 App ID）识别这条连接，不要用同一个 App ID 建立多条 Teams 连接。
- Client secret 会过期：Azure 的 Client secret 有有效期（常见 6 / 12 / 24 个月）。到期后连接会变成「凭据过期」，AI 停止回复 —— 平台的健康巡检会把异常连接暴露出来，请及时续期并回到平台更新。
Telegram（官方 Bot API）
把 Telegram 机器人接到 AI 客服：客户在 Telegram 里与机器人对话 → 平台接收 → AI 自动回复；Telegram 无需审核、零订阅，接入最快。
你需要准备
- 一个 Telegram 账号，可通过 @BotFather 创建机器人
- 机器人 Token 与自定义的 Webhook Secret Token
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 Telegram 渠道能力
操作步骤
- 1
创建机器人并取出 Token
在 Telegram 里找 @BotFather → /newbot → 按提示起名，得到形如 123456789:AA… 的 Bot Token，复制到平台。
- 2
在平台填写并保存
后台 → 第三方连接 → Telegram → 填 Bot Token + 自定义 Webhook Secret Token → 「保存并测试连接」（平台会调用 getMe 自检）。
- 3
注册 Webhook 并带上 secret_token
用 Telegram 官方接口设置回调：setWebhook 的 url 填 {平台基址}/api/webhooks/external/telegram，secret_token 填与平台完全一致的那串（这是平台的验签依据）。
- 4
真机测试
在 Telegram 中给你的机器人发一句 Hello，几秒内应收到 AI 回复。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 机器人用户名botUsername | 选填 | BotFather 创建时设置（或 /setname） | 例如 @my_shop_bot，仅用于展示与排障，不影响功能。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Bot TokenbotToken | 必填 | Telegram → @BotFather → /newbot（或 /mybots → API Token） | 创建机器人后 BotFather 会返回形如 123456789:AA… 的 Token，复制到平台。提示：Token 等于机器人控制权：只填在平台（服务端加密保存），绝不要贴在聊天/邮件/前端代码里。 |
| Webhook Secret TokenwebhookSecret | 必填 | 由你自己定义（setWebhook 的 secret_token） | 生成 1–256 位随机串（只含 A-Za-z0-9_-，例如 openssl rand -hex 24）。调用 setWebhook 时填入相同值；平台用该值校验每次回调来源。提示：平台对回调**强制验签**：不一致的请求一律拒绝（fail-closed），因此两边必须完全一致。 |
注意（真实会踩到的点）
- 验签是强制的：平台校验 X-Telegram-Bot-Api-Secret-Token，与平台填的 secret_token 不一致的回调一律拒绝（fail-closed），因此 setWebhook 时两边必须使用同一个值。
- 群聊能力边界：平台按「聊天 ID」区分会话，群组与私聊是不同会话；机器人需要被加入群组才能收到群消息。
WhatsApp Business（Cloud API）
把 WhatsApp 官方商业号（WhatsApp Business Platform / Cloud API）接到 AI 客服：客户发消息 → 平台接收 → AI 自动回复。
你需要准备
- 一个 Facebook / Meta 账号，并已创建 Business 类型的 Meta App
- 该 App 已添加 WhatsApp 产品
- 至少一个可用号码：开发阶段可用 Meta 提供的 Test Number；正式使用需要已验证的商业号码（部分功能需完成企业验证）
- 本平台后台的 OWNER 或 ADMIN 权限，且平台已为你的组织开通 WhatsApp 渠道能力（未开通时会明确提示）
操作步骤
- 1
（推荐）用官方授权一键连接
若平台已配置 Meta 官方应用，直接在「通讯渠道」点「连接 WhatsApp（官方授权）」→ 在 Meta 弹窗内登录并选择你自己的 WABA 与号码 → 平台自动建连并订阅 Webhook，无需手工复制任何 Token。若平台未配置，则按下方手工步骤操作。
- 2
在 Meta 后台取出所需的值
按下方参数表依次拿到 Phone Number ID、Access Token、App Secret，并自定义 Verify Token。
- 3
回到平台填写并保存
后台 → 第三方连接 → WhatsApp 卡片 → 连接 / 更新凭据：填 Phone Number ID + 三项凭据 → 「保存并测试连接」。平台会立刻调用 Graph API 自检，通过后徽章变为「已连接」。
- 4
在 Meta 后台配置 Webhook
Meta App → WhatsApp → Configuration → Webhook → Edit：Callback URL 填 {平台基址}/api/webhooks/external/whatsapp，Verify token 填你自定义的那串 → Verify and save（平台会自动完成挑战校验）。
- 5
订阅消息字段
在同一 Webhook 区域点击 Manage，勾选 messages（必须；否则客户发来的消息不会推送给平台）。
- 6
真机测试
用你的 WhatsApp 给该号码发一句 Hello。几秒内应收到 AI 回复；同时后台「客服工作台」会出现这条会话（带 WhatsApp 平台标记）。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Phone Number IDphoneNumberId | 必填 | Meta App Dashboard → WhatsApp → API Setup | 在 “Send and receive messages / From” 区域选择你的号码，右侧显示的 Phone number ID（一串数字 ID，形如 123456789012345）就是它。注意它不是电话号码本身。提示：开发阶段可先用 Meta 提供的 Test Number（其 Phone number ID 与正式号码不同，可直接填）。 |
| WhatsApp Business Account ID（WABA）businessAccountId | 选填 | Meta App Dashboard → WhatsApp → API Setup 顶部 | 同一页面顶部的 WhatsApp Business Account ID（WABA ID，一串数字）。选填，填上便于对账排障。 |
| Graph API 版本apiVersion | 选填 | Meta 官方 Graph API 变更日志 | 一般留空即可，平台默认使用 v26.0。若官方再次升级版本，可在此填你的 App 当前版本覆盖单条连接。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Access Token（System User Token）accessToken | 必填 | 正式（不过期）：business.facebook.com → Business Settings → Users → System users | ① 新建 System User（Admin）→ ② Add Assets：把 Meta App 与 WhatsApp Account 都授予它 → ③ Generate New Token：选择你的 App，权限勾选 whatsapp_business_messaging 与 whatsapp_business_management，有效期选 “Never expire” → ④ 复制 Token（只显示一次）。提示：开发/联调也可用 API Setup 页的 Temporary access token，但它 24 小时过期，正式使用会导致连接变成「凭据过期」。 |
| App Secret（Webhook 验签）appSecret | 必填 | Meta App Dashboard → App settings → Basic | 点击 App Secret 右侧的 Show，输入密码后复制（32 位十六进制字符串）。它用于校验 Meta 回调请求的签名。提示：App Secret 一旦重置，必须回到本平台更新，否则 Webhook 会验签失败（平台会记录签名错误并拒绝处理）。 |
| Webhook Verify TokenverifyToken | 必填 | 由你自己定义（不是 Meta 生成的） | 生成一段只有你知道的随机字符串（建议 24 字节以上，例如 openssl rand -hex 24 的结果）。平台填什么，Meta 后台的 Verify token 就填完全相同的值，两边必须一致。 |
注意（真实会踩到的点）
- 24 小时窗口：WhatsApp 只允许在客户最后一次发消息后的 24 小时内发送自由文本消息。AI 自动回复由客户消息触发，始终落在窗口内；但若你主动发起对话（超过 24 小时），Meta 要求使用已审核的模板消息 —— 平台当前只做「客户先来消息 → AI 回复」，不发送营销模板。
- Test Number 限制：Meta 提供的一次性测试号码只能向最多 5 个已添加的测试接收人发送消息，适合联调，不适合对外运营。
- App Secret 别随意重置：重置后平台侧必须同步更新，否则 Webhook 验签失败（平台按安全设计拒绝处理并留痕）。
DHL Express（MyDHL API）
把 DHL Express 账号接到平台物流网关：AI 客服可以查真实运费、查真实运单轨迹与状态（数据来自 DHL，不是编造）。
你需要准备
- DHL 开发者门户账号（developer.dhl.com），并创建 App 订阅 DHL Express – MyDHL API
- Sandbox 凭据（立即可得）；正式使用还需要生产凭据（需 DHL 审核）与 DHL Express 发件账号
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 DHL 物流能力
操作步骤
- 1
先取 Sandbox 凭据
developer.dhl.com → My Apps → 你的 App → 复制 API Key 与 API Secret。
- 2
在平台填写（环境选 sandbox）
后台 → 第三方连接 → DHL Express → 填 API Key / API Secret / 发件账号，环境选 sandbox → 「保存并测试连接」。自检通过后徽章为「已连接」。
- 3
验证查询能力
在「客服工作台」的会话里，以客户口吻问 “Where is my package <运单号>?” 或 “How much is shipping to Germany?”，AI 会经平台物流网关调用 DHL 并基于真实返回值回答。
- 4
切到生产
取得生产凭据后，回到 DHL 卡片「更新凭据」，把环境改为 production，保存并重新测试连接。切换后报价与运单都走真实环境。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| DHL 账号（shipper account）accountNumber | 必填 | 你的 DHL Express 合同 / DHL 客户经理提供 | 填写发件账号（Shipper Account Number，通常是 9 位数字）。运费报价按该账号的协议价计算；创建运单时也是必填项。提示：没有 DHL 账号时可以先只做「运单轨迹查询」（TRACK 不需要账号），但运费报价与创建运单必须填账号（平台会明确报 CONFIG_REQUIRED，不会伪造价格）。 |
| 环境environment | 选填 | 见「环境 production / sandbox」章节 | 先用 sandbox + DHL 测试凭据调通，确认无误后再切 production + 生产凭据。留空 = sandbox（平台默认走测试端点）。 |
| 默认产品代码（如 N）defaultProductCode | 选填 | DHL MyDHL API 官方产品代码表 | 留空则使用 DHL 默认产品；如需指定时效产品（例如 P = Express Worldwide、N = Express Domestic，具体以官方产品代码表为准），在此填写。 |
| 计量单位unitOfMeasurement | 选填 | 平台配置项 | metric（公斤/厘米，推荐）或 imperial（磅/英寸）。留空默认 metric。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| DHL API Key（Basic 用户名）apiKey | 必填 | developer.dhl.com → My Apps（DHL 开发者门户） | 登录后创建 App，并订阅 DHL Express – MyDHL API；在 App 的 Credentials / API Keys 面板复制 API Key（它作为 HTTP Basic 的用户名）。提示：测试凭据（Sandbox）可直接获得；生产凭据需要 DHL 审核批准（通常要求你已有 DHL Express 账号与合同）。 |
| DHL API Secret（Basic 密码）apiSecret | 必填 | developer.dhl.com → My Apps → 你的 App → Credentials | 同一面板复制 API Secret（作为 HTTP Basic 的密码）。若只显示一次，请立即保存到平台。 |
注意（真实会踩到的点）
- Sandbox 返回测试数据：不会产生真实运单、不会产生真实费用；正式对外必须切 production。
- 运费报价需要发件账号：未填 accountNumber 时，运单轨迹查询可用，但报价 / 创建运单会被平台明确拒绝（缺配置），不会伪造价格。
- AI 不接触 DHL 密钥：AI 只能调用平台提供的统一物流工具（查运费 / 查轨迹 / 查状态），密钥只存在于平台服务端，且每次调用都留有操作台账（谁、何时、调用什么、耗时、结果）。
FedEx（官方 REST API）
把 FedEx 账号接到平台物流网关：AI 客服可以查真实运费报价、查真实运单轨迹与状态（数据来自 FedEx，不是编造）。
你需要准备
- FedEx Developer Portal 账号，并创建 App 订阅 Track（必需）与 Rate / Address Validation（按需）
- 测试凭据（developer 门户即时可得）；运费报价还需要 FedEx 发件账号
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 FedEx 物流能力
操作步骤
- 1
先取测试凭据
developer.fedex.com → 你的 Project → 复制 API Key（client_id）与 Secret Key（client_secret）。
- 2
在平台填写（环境选 sandbox）
后台 → 第三方连接 → FedEx → 填 Client ID / Client Secret /（报价需要）发件账号，环境选 sandbox → 「保存并测试连接」。
- 3
验证查询能力
在「客服工作台」里以客户口吻问 “Where is my package <运单号>?” 或 “How much is shipping to Germany?”，AI 会经平台物流网关调用 FedEx 并基于真实返回值回答。
- 4
切到生产
取得生产凭据后回到 FedEx 卡片「更新凭据」，把环境改为 production，保存并重新测试连接。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| FedEx 发件账号（Account Number）accountNumber | 选填 | 你的 FedEx 账号 / FedEx 客户经理提供 | 填写发件账号（Account Number，通常 9 位）。运单轨迹查询可以不填；运费报价必须填。提示：未填时平台会明确报 CONFIG_REQUIRED，不会伪造价格。 |
| 环境environment | 选填 | 见「环境 production / sandbox」章节 | 先用 sandbox + 测试凭据调通，确认无误后再切 production + 生产凭据。留空 = sandbox。 |
| 返回语言（如 zh_CN / en_US）locale | 选填 | 平台配置项 | 返回语言（如 zh_CN / en_US），影响轨迹描述语言。留空默认 zh_CN。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| API Key（Client ID）clientId | 必填 | developer.fedex.com → 你的 Project → API Key | 在 FedEx Developer Portal 创建 App，订阅 Track / Rate / Address Validation 等 API，然后复制 API Key（即 client_id）。提示：测试与生产凭据不同：先用测试凭据（environment=sandbox）调通，生产凭据需通过审核。 |
| Secret Key（Client Secret）clientSecret | 必填 | developer.fedex.com → 你的 Project → Secret Key | 同一页面复制 Secret Key（即 client_secret）。 |
注意（真实会踩到的点）
- 能力边界如实声明：当前启用 RATE / TRACK / ADDRESS_VALIDATION；创建运单与面单**尚未启用**，平台不会显示这些能力（未声明即不可调用）。
- 报价需要发件账号：未填 accountNumber 时轨迹查询可用，但运费报价会被平台明确拒绝（CONFIG_REQUIRED），不会伪造价格。
顺丰国际（丰桥开放平台）
把顺丰丰桥账号接到平台物流网关：AI 客服可以查真实顺丰运单的物流轨迹（数据来自顺丰，不是编造）。
你需要准备
- 已与顺丰签约并开通丰桥开放平台账号
- 在丰桥开通「路由查询」接口，并取得伙伴编码（partnerID）与校验码（checkword）
- 本平台后台 OWNER / ADMIN 权限，且平台已开通顺丰物流能力
操作步骤
- 1
取出伙伴编码与校验码
丰桥开放平台 → 我的项目：复制 partnerID 与 checkword（校验码）。
- 2
在平台填写并保存
后台 → 第三方连接 → 顺丰国际 → 填 partnerID / checkword（如分配了专属网关再填 apiBase）→ 「保存并测试连接」。
- 3
验证轨迹查询
在会话里提供顺丰运单号询问物流进度，AI 会经平台物流网关调用丰桥路由查询并基于真实返回值回答。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 接口地址（丰桥网关）apiBase | 选填 | 丰桥开放平台接口文档 / 顺丰顾问 | 留空使用标准网关 https://bspgw.sf-express.com/std/service；如分配了专属域名再在此覆盖。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 合作伙伴编码（partnerID）partnerId | 必填 | 顺丰丰桥开放平台 → 我的项目（顾客编码） | 复制合作伙伴编码（partnerID）。提示：需先与顺丰签约，并在丰桥开通「路由查询」接口；未开通时接口会返回权限类错误。 |
| 校验码（checkword）checkword | 必填 | 顺丰丰桥开放平台 → 校验码管理 | 复制校验码（checkword）。它只用于服务端签名（md5 + base64），平台永不下发前端。提示：在丰桥重置校验码后必须回到平台更新，否则所有查询都会签名失败。 |
注意（真实会踩到的点）
- 能力边界如实声明：当前仅启用**路由查询（轨迹）**；顺丰运费时效查询与下单各有独立接口，需在丰桥单独开通后才启用（平台不声明未启用的能力）。
- 签名依赖校验码：在丰桥重置 checkword 后必须回到平台更新，否则所有查询都会签名失败（平台会记录并暴露为异常）。
17TRACK（多承运商轨迹聚合）
用 17TRACK 聚合查询覆盖长尾承运商：客户给出的运单号属于哪家都能查到轨迹（顺丰 / EMS / 云途 / 燕文 / 4PX / 各国邮政等），无需逐个接入。
你需要准备
- 17TRACK 账号（免费额度即可开始）
- 17TRACK 后台生成的 API Key（安全密钥）
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 17TRACK 物流能力
操作步骤
- 1
取出 API Key
17TRACK 后台 → 设置 → API → 安全密钥，复制 API Key。
- 2
在平台填写并保存
后台 → 第三方连接 → 17TRACK → 填 API Key → 「保存并测试连接」（平台做一次只读探针，不产生注册副作用）。
- 3
验证轨迹查询
在会话里提供任意承运商的运单号询问「包裹在哪里」，AI 会经平台物流网关调用 17TRACK 并基于真实返回值回答。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 默认承运商代码（可选）carrierCode | 选填 | 17TRACK 官方承运商代码表 | 选填。已知承运商时填写其数字代码可提高识别准确率；留空则由 17TRACK 自动识别（适用于顺丰 / EMS / 云途 / 燕文 / 4PX 等长尾承运商）。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 17TRACK API KeyapiKey | 必填 | 17TRACK 后台 → 设置 → API → 安全密钥 | 复制 API Key。平台以请求头 17token 携带该密钥调用 17TRACK 接口。提示：17TRACK 按查询量计费（有免费额度）：额度用尽后查询会失败，平台会如实回报错误，不会伪造轨迹。 |
注意（真实会踩到的点）
- 只提供轨迹能力：17TRACK 不提供运价与下单 → 平台**不声明** RATE / SHIPMENT，AI 也不会声称能报价。
- 按查询量计费：免费额度用尽或密钥失效时查询会失败，平台会如实回报错误（不会编造轨迹），并在连接健康巡检中暴露异常。
UPS（官方 API）
把 UPS 账号接到平台物流网关：AI 客服可以查真实运费报价与真实运单轨迹（数据来自 UPS，不是编造）。
你需要准备
- UPS Developer Portal 账号，并创建应用订阅 Rating 与 Tracking
- 测试凭据（即时可得）；生产凭据需 UPS 审核
- 本平台后台 OWNER / ADMIN 权限，且平台已开通 UPS 物流能力
操作步骤
- 1
取测试凭据
UPS Developer Portal → 你的应用 → Credentials：复制 Client ID 与 Client Secret。
- 2
在平台填写（环境选 sandbox）
后台 → 第三方连接 → UPS → 填 Client ID / Client Secret，环境选 sandbox → 「保存并测试连接」（平台用 Basic + client_credentials 换 token 完成自检）。
- 3
验证查询能力
在会话里问运费或提供 UPS 运单号，AI 会经平台物流网关调用 UPS 并基于真实返回值回答。
- 4
切到生产
取得生产凭据后更新凭据并把环境改为 production，重新测试连接。
配置项与取值位置
| 字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| 环境environment | 选填 | 见「环境 production / sandbox」章节 | 留空 = sandbox（wwwcie.ups.com）；切 production 后走 onlinetools.ups.com。 |
| Rating API 版本ratingVersion | 选填 | UPS 官方 API 文档（Rating 版本号） | 留空使用平台默认版本（v2403）。若你的账号只开放某版本，在此填写覆盖。 |
| 返回语言（如 zh_CN / en_US）locale | 选填 | 平台配置项 | 返回语言（如 zh_CN / en_US）。留空默认 en_US。 |
凭据（仅服务端使用，页面只显示掩码）
| 凭据字段 | 必填 | 去哪里取 | 具体操作 |
|---|---|---|---|
| Client IDclientId | 必填 | UPS Developer Portal → 你的应用 → Credentials | 创建应用并订阅 Rating / Tracking，复制 Client ID。提示：测试与生产凭据不同：先用测试凭据（environment=sandbox）调通，生产凭据需 UPS 审核。 |
| Client SecretclientSecret | 必填 | UPS Developer Portal → 你的应用 → Credentials | 同一页面复制 Client Secret。平台用 Basic 认证 + client_credentials 换 access_token。 |
注意（真实会踩到的点）
- 能力边界如实声明：当前启用 RATE / TRACK；创建运单与面单尚未启用。
- RatedShipment 版本可能随 UPS 升级：如你的账号只开放特定 Rating 版本，可在配置里填写 ratingVersion 覆盖平台默认值。
第 7 步 · 连接之后会发生什么
- 消息进来：第三方把消息推到平台 Webhook → 平台先验签（防伪造）→ 立刻返回成功凭证 → 消息入库排队。
- AI 处理：平台后台服务取出消息，读取你的知识库 / 站点信息 / 会话历史，必要时调用物流等工具取真实数据，然后生成回复。
- 出站发送：回复经第三方官方接口发给客户；发送失败会自动退避重试，超过上限进入「待人工处理」并通知你。
- 重复消息不会重复回复：同一条第三方消息、同一个事件重复推送，平台只处理一次（幂等），也不会因为第三方重试而重复发送。
- 人工接管：后台「客服工作台」可查看所有渠道会话（WhatsApp / Messenger / Instagram / Teams / Slack / 站内聊天，带平台标记），支持「AI 自动 / 人工接管 / AI 暂停」；人工回复后自动转入人工接管，可随时交回 AI。第三方渠道新消息会实时进入工作台并触发消息提醒（无需刷新页面）。
排障速查表
| 错误码 | 常见原因 | 怎么处理 |
|---|---|---|
| SIGNATURE_INVALID / SIGNATURE_MISSING | 第三方回调的签名校验未通过（常见：App Secret 填错或被重置、请求并非来自第三方）。平台按安全设计直接拒绝并留痕。 | 核对 Meta 的 App Secret 是否与平台一致；确认回调地址与 Verify Token 未被改动。 |
| HANDSHAKE_TOKEN_INVALID | WhatsApp 在 Meta 后台点 Verify 时失败：平台侧填的 Verify Token 与 Meta 后台不一致（这是 GET 握手校验）。 | 把平台上的 Verify Token 与 Meta 后台 Webhook 配置里的值改成完全一致，再点一次 Verify and save。 |
| CREDENTIAL_MISSING | 必需凭据未填齐（例如只填了 Access Token，没填 App Secret）。 | 在「更新凭据」里补齐标 * 的字段并保存。 |
| AUTH_FAILED | 自检时凭据被第三方拒绝：Token / Secret 过期、被重置、权限不足或复制不完整。 | 回到第三方控制台重新生成，确认权限范围（WhatsApp 需 whatsapp_business_messaging）后更新。 |
| TOKEN_EXPIRED / AUDIENCE_MISMATCH | Teams：机器人令牌已过期，或令牌里的 aud（App ID）与这条连接配置的 App ID 不一致（常见于同一 App ID 建了多条连接，或填错 App ID）。 | 核对 Teams 连接里的 Microsoft App ID；如需更换 App，请删除旧连接并新建。 |
| CONFIG_REQUIRED | 缺少非凭据配置（典型：DHL 未填发件账号 accountNumber）。 | 补齐配置字段后重新测试连接（平台不会用默认值伪造业务数据）。 |
| CLIENT_ERROR / NOT_FOUND | DHL 拒绝了请求（参数不被接受，或该运单不存在 / 不属于你的账号）。 | 核对运单号与账号；确认 environment 与凭据环境匹配（测试凭据配 sandbox，生产凭据配 production）。 |
| CONNECTION_NOT_RUNNABLE | 连接未处于「已连接」（异常 / 凭据过期 / 已停用），平台此时只记录事件、不处理、不回复。 | 先修复连接（测试连接 / 更新凭据 / 启用），历史事件可在后台重试。 |
| LOGISTICS_CONNECTION_REQUIRED / LOGISTICS_CAPABILITY_UNSUPPORTED | AI 尝试查询物流时没有可用的 DHL 连接，或该服务商未声明所需能力（例如只支持查轨迹、不支持查运费）。 | 到「第三方连接」完成 DHL 配置并通过自检；能力不足属服务商限制，可联系平台确认。 |
| CAPABILITY_REQUIRED / CAPABILITY_NOT_FOUND / CAPABILITY_DISABLED | 平台尚未为你的组织开通该渠道 / 物流能力（能力由平台侧授予，页面上的第三方连接不会自动获得授权）。 | 联系平台客服开通对应能力后再连接。 |
| ENCRYPTION_KEY_MISSING | 平台侧未配置凭据加密密钥，出于安全考虑拒绝保存第三方凭据（平台配置问题，不是你的操作问题）。 | 联系平台客服处理；在修复前不要尝试以其他方式保存密钥。 |
连接卡片上会显示「最近回调 / 最近成功 / 最近错误」，可据此判断问题发生在接收（第三方没推到平台，或签名不符）还是发送（平台调第三方失败）。日志中不会出现任何密钥明文。
常见问题
1. 我关闭浏览器 / 关掉电脑，AI 还会自动回复吗？
会。收消息、AI 处理、发送、重试全部由平台服务器上的常驻服务执行，与你的浏览器或后台页面是否打开无关。
2. sandbox 会不会把消息发给真实客户 / 产生真实运单？
DHL 的 sandbox 使用测试端点，返回测试数据，不会产生真实运单与费用；WhatsApp / Teams 没有独立测试端点（见上文），是否对外可见取决于你填入的是测试号码/测试机器人还是正式号码/正式机器人。
3. 我的密钥会不会被别人看到？
不会。凭据以加密形式存储在服务端，接口只返回掩码（如 ••••1234），日志与错误信息都不包含密钥明文；页面也无法查看完整值 —— 更新时必须重新粘贴新值。
4. 可以同时连接多个渠道 / 多个 DHL 账号吗？
可以连接多个渠道（WhatsApp 与 Teams 可并存，各自独立会话）。物流服务方面，同一服务商在同一组织下建议只保留一条已连接账号；若存在多条可用连接，平台会明确要求指定，不会擅自挑一个。
5. 消息会不会重复回复、或漏回复？
平台对「第三方事件」「第三方消息」「回复任务」「出站发送」四层都做了唯一性 / 幂等控制：重复推送只算一次；发送失败会重试，超过上限转人工并通知。
6. 改了 App Secret / Token 之后要做什么？
回到「第三方连接」对应卡片「更新凭据」重新粘贴并保存（保存后会自动重新自检），否则连接会进入「凭据过期 / 异常」并停止收发。
官方参考链接
- Instagram 私信（Instagram Messaging） — https://developers.facebook.com/docs/instagram-platform
- LINE 官方账号（Messaging API） — https://developers.line.biz/en/docs/messaging-api/
- Facebook Messenger（Messenger Platform） — https://developers.facebook.com/docs/messenger-platform
- Slack（官方 App） — https://api.slack.com/events-api
- Microsoft Teams（Azure Bot） — https://learn.microsoft.com/microsoftteams/platform/bots/how-to/conversations/
- Telegram（官方 Bot API） — https://core.telegram.org/bots/api
- WhatsApp Business（Cloud API） — https://developers.facebook.com/docs/whatsapp/cloud-api
- DHL Express（MyDHL API） — https://developer.dhl.com/api-reference/dhl-express-mydhl-api
- FedEx（官方 REST API） — https://developer.fedex.com/api/en-us/catalog.html
- 顺丰国际（丰桥开放平台） — https://open.sf-express.com/
- 17TRACK（多承运商轨迹聚合） — https://api.17track.net/en/doc
- UPS（官方 API） — https://developer.ups.com/api/reference
第三方控制台界面可能随官方版本调整而变化；若某一步在控制台里找不到，请以官方文档为准，或联系平台客服协助（我们不会索取你的密钥）。
按步骤操作后仍无法连接？把页面显示的错误码提供给我们，可快速定位是配置、凭据还是第三方侧的问题。
联系客服协助