send-sms

/digital-marketing-pro:send-sms

脚本位置。 如果宿主未设置 ${CLAUDE_PLUGIN_ROOT}，脚本位于此插件的 scripts/ 文件夹中，与 skills/ 同级。请使用 Python 3.10 或更高版本运行：python；如果找不到 python，则使用 python3（macOS 和许多 Linux 系统）。

用途

通过 Twilio 或 Brevo 发送 SMS 或 WhatsApp 营销消息，并强制执行合规检查、同意验证、静默时段要求和送达跟踪。SMS 和 WhatsApp 是影响大、风险高的渠道——消息会立即送达个人设备，打开率接近 100%，因此合规失误会造成重大的法律和声誉后果。此命令会在任何消息离开系统前执行所有必要的防护措施：针对美国收件人的 TCPA 同意、针对欧盟的 GDPR 同意、针对加拿大的 CASL 合规、退订机制、遵守静默时段以及消息长度合规。只有通过所有检查并获得用户明确批准后，才会发送消息。

执行关卡（强制——不可跳过）

1. 在操作任何线上系统前，先将完整预览——收件人／支出／变更／合规情况——作为 执行摘要 呈现。
2. 用户必须输入 yes（或同等明确的批准）。任何其他输入——含糊、暗示、部分批准或未批准——都会取消本次运行。
3. 绝不可根据含糊的输入继续操作。绝不可自动重试失败的执行；重新运行前必须由人工审核失败原因。
4. 只有在用户输入 yes 后，才记录批准：python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"send-sms","platform":"<platform>","content_summary":"<one line from the Execution Summary>","risk_level":"<tier>"}'，然后运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action approve --id {approval_id}。如果任一命令报错，请停止并报告错误；绝不可改用其他工具绕过。如果该操作的批准记录已生成，即证明批准步骤已执行；但无法证明是谁输入了 yes。
5. 执行。通过 connector_executor.py 发送的写入操作需要 --approval-id，且只有在记录匹配、未使用且未过期时才会执行（见 /digital-marketing-pro:execute-action）。通过已连接的 MCP 服务工具执行的写入操作不受该代码检查约束：它依赖于用户输入的 yes，以及宿主显示的权限提示。之后运行 python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action mark-executed --id {approval_id} --data '{"execution_result":"success"}'（或 failure）。

所需输入

用户必须提供（或系统会提示用户提供）：

• 消息内容：短信或 WhatsApp 消息正文 — 必须包含明确的退订方式（例如，“回复 STOP 退订”），以符合监管要求。WhatsApp 消息可包含富媒体（图像、文档、视频或位置），且根据 Meta 的政策，企业主动发起的对话必须使用预先批准的消息模板
• 接收方：采用 E.164 格式的电话号码（+1XXXXXXXXXX）、品牌受众数据中的命名联系人列表，或细分群体引用。批量发送时，请提供 CSV 文件路径或列表标识符。每位接收方都必须有留档的同意记录
• 渠道：sms 或 whatsapp — 决定消息长度限制（短信为 160 个字符；WhatsApp 模板正文为 1,024 个字符，自由格式会话消息为 4,096 个字符）、媒体支持（短信仅支持文本，WhatsApp 支持富媒体）、模板要求和平台特定的合规规则
• 发送方 ID（可选）：要使用的发送方电话号码、短代码或字母数字发送方 ID — 必须已在平台上注册并验证。如果省略，则使用 messaging MCP 中配置的品牌默认发送方。并非所有国家/地区都支持字母数字发送方 ID
• 发送时间：immediate 表示立即发送，或采用包含时区的预定日期和时间（ISO 8601 格式）。安排发送时间时必须遵守静默时段 — 接收方当地时区的晚上 9 点至早上 8 点之间不得发送
• 营销活动名称（可选）：用于跟踪和归因 — 将此次发送关联到品牌分析和效果报告中的营销活动。如果省略，则根据消息内容和日期自动生成
• 个性化字段（可选）：要合并到消息中的动态字段 — 名字、订单号、预约时间、忠诚度积分或自定义变量。每个字段都需要为缺少数据的接收方设置备用默认值（例如，名字缺失时使用“尊贵的客户”）
• WhatsApp 模板 ID（可选）：对于 WhatsApp 企业主动发起的消息，需提供预先批准的模板标识符及变量映射。对于在 24 小时客户服务时限之外发送的消息，Meta 要求提供此项
• 优先级（可选）：normal（标准发送队列）或 urgent（用于预约提醒或安全警报等时效性消息的优先发送）。紧急发送会跳过发送时间优化，但仍会执行所有合规检查

流程

1. 加载品牌背景：读取 ~/.claude-marketing/brands/_active-brand.json 获取当前品牌 slug，然后加载 ~/.claude-marketing/brands/{slug}/profile.json。应用品牌语调、目标市场的合规规则（skills/context-engine/compliance-rules.md）和行业背景。还要检查 ~/.claude-marketing/brands/{slug}/guidelines/_manifest.json 中是否有指南；如果存在，则加载其中的限制。检查 ~/.claude-marketing/sops/ 中是否有代理机构 SOP。如果没有品牌，请询问：“先设置品牌？（/digital-marketing-pro:brand-setup）”——或者使用默认设置继续。
2. 验证同意合规性：检查所有收件人是否都有针对所选渠道的书面选择加入同意记录。应用特定司法管辖区的规则——美国收件人须符合 TCPA 明确书面同意要求，欧盟须符合 GDPR 明确同意要求并记录合法依据，加拿大须符合 CASL 明确或默示同意要求并跟踪有效期。标记缺少必要同意的收件人，并将其从发送名单中排除，同时为每位收件人生成合规报告。
3. 遵守静默时段：在可确定的情况下，根据电话号码的国家代码和区号确定每位收件人的时区；否则使用已存储的受众资料数据。若收件人当地时间为晚上 9 点至早上 8 点，则阻止立即发送。对于定时发送，验证计划发送时间在所有收件人的时区中均符合静默时段要求。标记冲突并建议最近的合规发送时段。
4. 验证退订机制：扫描消息正文，确认包含合规的退订说明，例如“回复 STOP 退订”或符合相应司法管辖区要求的等效说明。对于 WhatsApp，确认已在商业账户设置中配置退订流程。如果缺失或不合规，则拒绝发送，并要求用户添加退订说明后再继续。
5. 检查消息长度：根据渠道限制验证消息长度——每条 SMS 分段为 160 个字符（拼接消息最多 1,600 个字符，并提示分段数量和费用），WhatsApp 文本为 1,024 个字符。对于个性化消息，使用变量替换可能达到的最长长度进行计算，确保不会向任何收件人发送被截断的消息。报告字符数、分段数量和每条消息的费用。
6. 验证消息 MCP 连接：检查已连接的消息平台 MCP（Twilio 或 Brevo），并确认其支持所选渠道（SMS、WhatsApp 或两者）。验证发件人 ID 已注册、已授权，并符合目标国家/地区的发件人 ID 规定。如果尚未连接，则引导用户完成集成设置。
7. 评估品牌语调：对消息内容运行 brand-voice-scorer.py，验证其是否符合品牌语调指南。SMS 消息应简洁、直接——标记不符合品牌风格、对该渠道而言过于正式，或在缺少视觉线索的短文本语境中可能造成误解的内容。
8. 创建审批记录：通过 approval-manager.py --action create-approval 创建记录，并在 --data JSON 中包含风险等级——{"type":"send-sms","platform":"<platform>","content_summary":"...","risk_level":"high"}。SMS 和 WhatsApp 营销存在监管风险（每条未经请求的消息最高可被处以 1,500 美元的 TCPA 罚款），且每条消息都会产生费用。没有 --risk-level 标志；确切命令请参阅上方的执行关卡。生成完整的发送摘要供审核。
9. 呈现发送摘要：显示完整摘要——包含个性化令牌替换后的消息预览（使用示例收件人）、收件人数（总数、经过合规筛选后符合条件的人数、以及按原因排除的人数）、渠道、发件人 ID、发送时间及静默时段验证结果、合规检查清单（同意、静默时段、退订、发件人验证）、每条消息的预估费用和总发送费用、适用时的 SMS 分段数量，以及品牌语调评分。等待用户明确确认“发送”。
10. 通过 MCP 执行发送：获批后，通过已连接的 Twilio 或 Brevo MCP 触发消息发送。按收件人替换个性化令牌，批量发送时进行限速处理，注入 WhatsApp 模板变量，并采用平台特定的 API 格式。监控即时投递失败和 API 错误。
11. 跟踪投递情况：轮询消息平台 API，获取投递状态更新——已送达、失败、未送达、排队中，或已读（仅限 WhatsApp）。跟踪批量发送中每位收件人的状态。如果投递失败率超过 5%，则提醒用户，并按原因分类汇总失败情况（号码无效、运营商拦截、已处理的退订、网络超时）。
12. 记录执行情况：运行 execution-tracker.py，记录发送事件，包括时间戳、平台、渠道、营销活动名称、收件人数（总数及各状态人数）、消息内容哈希、合规验证结果、投递指标、产生的费用和任何失败情况。保存效果分析，以便优化未来的 SMS 策略并分析发送时间。

输出

包含以下内容的结构化发送确认：

• 发送确认：消息 ID 或批次 ID、平台（Twilio 或 Brevo）、渠道（SMS 或 WhatsApp）、发送状态（已发送、已安排、部分发送或待审批）以及含时区的时间戳
• 收件人详情：提交的收件人总数、通过合规筛选后符合条件的收件人数、被排除的收件人及各自原因（缺少同意，注明适用司法管辖区；违反静默时段，注明时区；号码格式无效），以及最终发送名单中的收件人数
• 合规报告：每项检查的通过/未通过状态——TCPA 同意（美国）、GDPR 同意（欧盟）、CASL 同意（加拿大）、退订机制是否存在且合规、是否遵守所有收件人时区的静默时段、发送方 ID 是否已验证且符合所在国家/地区要求，以及 WhatsApp 模板是否已获批准（如适用）
• 消息详情：最终消息内容及字符数、SMS 分段数和拼接状态、针对 2-3 位示例收件人的个性化预览（展示变量解析结果和回退默认值），以及退订机制的位置确认
• 成本报告：按目标国家/地区列出的单条消息成本、拼接 SMS 的每段成本、发送总成本，以及与营销活动消息预算的对比（如已关联营销活动名称）
• 送达报告：实时送达状态——已送达数量和百分比、待处理/排队数量、失败数量及分类后的失败原因（号码无效、运营商拒绝、已处理退订、网络错误、速率限制），以及 WhatsApp 的已读回执
• 品牌语调评分：消息与品牌语调指南及 SMS 最佳实践的契合度，并说明简洁性、清晰度以及针对未来移动消息的调整建议
• 执行日志条目：包含所有发送元数据的带时间戳记录，用于合规审计跟踪、营销活动效果跟踪和成本核算

使用的 Agent

• execution-coordinator — 跨司法管辖区的同意验证（TCPA、GDPR、CASL），逐位收件人进行合规筛选，根据电话号码和受众档案解析时区并执行静默时段限制，按渠道要求验证退订机制，通过 HIGH 风险分类和成本感知摘要执行审批工作流，通过 Twilio 或 Brevo MCP 执行发送并进行批处理和速率限制，实时跟踪送达状态并对失败进行分类和阈值告警，按消息和分段计算成本，并记录执行信息和完整的合规审计跟踪，以便留存监管文档