Lansum Message

第三方应用接入指南

Message 审核应用是否有权发送某类消息，并统一执行渠道、Consent、路由和审计；具体标题与正文由业务应用在每次发送时提供。

申请应用

接入与审核边界

1. 申请应用：填写主体、用途、收件人来源、Consent/退订流程、语言、国家、渠道、消息类别、量级和联系人邮箱。
2. 合规审核：审核人只判断应用及其最大发送范围是否合规，不审核一套固定消息文案。
3. 自动 Provision：通过后，Message 代表申请人请求 Auth 创建相互隔离的 Sandbox / Production machine client；申请人无需认识或单独申请 Auth。
4. 一次性领取：应用所有者在 Message 控制台领取完整接入配置并把 secret 保存到自己的服务端 Secret Manager。审核员和 Message 数据库都接触不到 secret。
5. 配置并测试契约：从常用场景蓝本或空白契约开始，在 Sandbox 配置消息 key、目标渠道和技术约束，并通过测试台验证调用格式。
6. 晋级到 Production：勾选已经确认的 Sandbox 契约批量晋级。系统复制确定版本、保留来源记录，并根据这些契约的实际渠道、类别与国家自动规划路由。
7. 调用 API：业务后端用凭据向 Auth 换取短期 token，再按 locale 生成实际 content；Message 进行格式、契约、Consent、偏好、路由和合规检查后投递。
8. Production 上线：配额、machine client、晋级后的消息契约及系统路由预检全部就绪后，提交最终生产门禁审核，并在批准后启用 Production Auth client。

两段审核分别决定什么

接入合规审核

审核主体、组织/Tenant 归属、用途、收件人来源、Consent、渠道与合规范围。批准后绑定 Tenant 并异步创建 Sandbox 与 Production 凭据，但 Production 保持停用。

生产上线审核

检查 Production machine client、明确配额、消息契约、Provider 路由和合规门禁。批准后才启用 Production 发送能力。

审核阶段由应用状态自动决定，申请人和审核人都不能任意切换。审核决定绑定不可变提交版本；要求补件、拒绝或暂停时必须给出原因，批准备注可选。

管理员在哪里处理：后台“概览”显示待办数量和最近申请；“审核队列”默认只显示需要管理员操作的接入与 Production 申请；“应用列表”用于搜索、筛选和查看全部应用状态；批准后的发送范围、Production 配额、凭据、成员与生命周期变更在“应用变更审批”处理。

领取凭据与换取 token

审核通过后，应用页会出现 Sandbox 和 Production 的“一次性领取”入口。只有近期完成 MFA 的应用所有者可领取；页面会返回该环境的 Product Key、Auth issuer/token endpoint、client ID、只显示一次的 client secret、scope、resource 和 Message API URL。请先准备服务端 Secret Manager，领取后立即保存。刷新或离开页面后无法恢复，丢失只能申请轮换；未领取记录 30 天后过期。

不要把 client secret 直接传给 Message。它只用于你的后端向 Auth 换取约 10 分钟有效的 access token。浏览器、移动端、工单、源码和消息 content 都不应保存它。

POST {LANSUM_AUTH_TOKEN_ENDPOINT}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={LANSUM_MESSAGE_CLIENT_ID}
&client_secret={LANSUM_MESSAGE_CLIENT_SECRET}
&scope=message:send
&resource={LANSUM_MESSAGE_RESOURCE}

取得 access_token 后，以 Authorization: Bearer … 调用 Message。Sandbox 与 Production 凭据完全分离；Production secret 的领取入口只在生产审核及 Auth 激活成功后开放。

需要轮换或停用时，在应用的“设置与应用变更”页面提交变更。批准会自动调用 Auth：轮换保持 client ID 不变、撤销旧 token 并生成新的领取入口；停用会同时禁用 Auth client 和 Message 环境。

申请表怎么填写

请用事实描述“发给谁、为什么可以发、如何退出”，不要求使用法律术语。

收件人来源

说明用户怎样进入应用，以及后端如何从可信登录会话或账户记录取得 Lansum Auth 稳定 sub。recipientSub 不是邮箱或手机号，也不应允许浏览器任意指定。

Consent 获取与证据

按渠道说明用户做了什么同意动作、看到哪版披露，以及保存在哪里。证据至少关联用户、渠道、用途、披露版本和 UTC 时间；Push 权限、营销订阅和交易短信应分别说明。

退订与 opt-out

营销内容必须说明偏好页、邮件退订链接或短信 STOP 等入口、生效时间，以及如何同步到发送前检查和 Provider 回调。非营销应用可留空。

联系人

运营、技术、安全三个栏位都填写通知邮箱；同一个人或团队邮箱可以重复使用，不要求三位不同联系人。

已接入应用如何变更

“应用变更”只表示修改一个已经接入的第三方应用，不是申请新的 Lansum Message 业务。进入应用详情后打开“设置与应用变更”。

发送范围与合规变更

调整渠道、消息类别、收件人来源、Consent/退订流程及内容风险声明。这里不再混入业务量或运行时配额。

Production 配额调整

单独调整 Production 真正执行的 UTC 每日消息配额和每秒请求上限；接入时填写的预计业务量不会被当作生效限额。

与当前生效值完全相同的请求不能提交。
管理员只查看实际变化的字段，即“提交时生效值 → 申请值”，不需要阅读原始 JSON。
如果等待审批期间生效配置已改变，系统会阻止覆盖，申请人必须按最新值重新提交。
凭据、成员权限和生命周期涉及 Lansum Auth 权限边界，现阶段仍需审批；批准说明可选，要求补件或拒绝必须写明原因。

语言由应用自由组合

应用可只选 zh-CN、只选 en-US，或同时选择两者。默认语言必须属于所选集合。这些设置描述产品与发送请求，不会把消息契约拆成不同语言版本；调用方仍必须传入本次消息的 canonical locale，并提供对应语言的 content。

消息契约不是文案模板

消息契约是一份与语言无关的技术与合规约束：稳定 key、消息类别、允许/必需/回退渠道、Consent scope、外部投递依据、国家、内容风险标记、归档方式和可选的 data JSON Schema。它不包含固定标题或正文，也不按语言拆分展示。调用方已经提供完整 content 时，data 默认可以省略。

外部投递依据：新契约默认使用 CONSENT_REQUIRED。只有确属账户安全、履行合同或法律义务的消息，才可选择与类别匹配的必要性依据；SMS 和 Marketing 始终要求有效 Consent，明确退订、用户偏好、Policy、Route、Sender 和 Compliance 门禁始终生效。

环境晋级：Sandbox 与 Production 保持隔离，但无需重复填写。勾选 Sandbox 契约并晋级后，系统会创建独立的 Production 版本，记录来源版本与晋级批次；后续 Sandbox 修改不会静默覆盖 Production。

场景蓝本：新增契约时可以选择验证码、登录提醒、订单状态、支付结果、预约提醒等常用蓝本，先预览推荐 key、渠道、Schema、归档策略和双语 content 示例，再进入表单调整。蓝本只复制技术配置并记录来源版本；示例文案不会保存，蓝本升级也不会自动修改已经生效的契约。

只能使用应用合规审核已批准的渠道、类别和国家范围。
新增或更新先生成不可变 Sandbox 版本；完成安全站内测试后才能晋级，Production 不接受直接编辑。
停用契约后，新的发送请求立即失败；历史事件、投递和审计记录保留。
要扩大渠道或合规范围，先提交应用配置变更并等待审核。

POST /api/v1/developer/applications/{applicationId}/contracts
Content-Type: application/json

{
  "environment": "SANDBOX",
  "key": "order.status.changed",
  "name": "订单状态通知",
  "messageType": "order_status",
  "messageCategory": "TRANSACTIONAL",
  "externalDeliveryBasis": "CONSENT_REQUIRED",
  "allowedChannels": ["IN_APP", "EMAIL"],
  "preferredChannels": ["IN_APP", "EMAIL"],
  "requiredChannels": [],
  "fallbackChannels": [],
  "allowedCountries": ["US"],
  "dataSchema": {
    "additionalProperties": false,
    "required": [],
    "properties": { "orderId": { "type": "string", "maxLength": 80 } }
  },
  "requiresStructuredData": false,
  "archiveMode": "NONE"
}

各渠道 content 格式

渠道	必填字段	可选字段	限制与安全处理
IN_APP	`inApp.title`、`inApp.body`	`navigate`	标题 200、正文 20,000 字符；navigate 仅站内绝对路径或 HTTPS
EMAIL	`email.subject`、`email.text`	`html`	应用可提供 HTML；Message 会移除脚本、事件属性和危险 URL。未提供时由纯文本生成安全 HTML
SMS	`sms.text`	—	最多 1,600 字符；Provider 仍可能按编码拆分计费
PUSH	`push.title`、`push.body`	`navigate`、`tag`	navigate 仅站内绝对路径或 HTTPS；由已注册 Push subscription 投递

请求选择了哪些渠道，就必须同时提供这些渠道对应的 content；多余字段、危险邮件 HTML 和 javascript: 跳转都会被拒绝或净化。

发送 API

POST /api/v1/messages/send
Authorization: Bearer <Lansum Auth machine token>
Content-Type: application/json

{
  "productKey": "acme",
  "contractKey": "order.status.changed",
  "recipientSub": "user_123",
  "locale": "zh-CN",
  "channels": ["in_app", "email"],
  "targets": { "email": "customer@example.com" },
  "dedupeKey": "order-status:123:shipped",
  "content": {
    "inApp": {
      "title": "订单已发货",
      "body": "订单 123 已交给承运商。",
      "navigate": "/orders/123"
    },
    "email": {
      "subject": "订单 123 已发货",
      "text": "订单 123 已交给承运商。
可在订单页面查看物流进度。"
    }
  }
}

content 是实际用户可见文案，也是调用方提供内容模式下唯一必需的消息内容。data 只是可选业务元数据；省略时不会重复校验正文，主动提供时仍按契约 Schema 校验。只有显式启用 requiresStructuredData 的契约才强制要求它。外部渠道必须提供稳定且唯一的 dedupeKey。

Production 门禁仍然保留

Production 默认停用。接入合规审核、Tenant 归属、machine client、应用级每日/每秒配额、至少一个已在 Sandbox 测试并晋级的消息契约、适用 Messaging Policy 及系统路由预检都必须有效。路由需求只来自 Production 契约实际使用的外部渠道、类别和国家；平台管理员可在网站维护 Provider、Sender、Compliance、Consent、Policy 与 Route。Production 审批后进入待激活状态，Auth 暂时不可用时自动重试而不回滚审核。