Toingg Ops Toolkit

Toingg 运维工具包

该技能集成了通过 Claw 管理 Toingg 推广活动所需的所有功能：

• 推广活动创建：通过 create_campaign.py 实现
• 推广活动发现：通过 fetch_campaigns.py 获取当前活跃的活动 ID 列表（适用于需向用户展示可用 ID 的场景）
• 按需外呼：通过 make_call.py 发起外呼（需提前收集姓名、电话号码及目标活动）
• 可选分析任务定时作业（每日 19:00 执行），由 get_campaign_analytics.py 驱动
• 联系人上传 + WhatsApp 模板广播：依次使用 xlsx_to_contacts.py、add_contacts.py 和 send_whatsapp_templates.py

所有 HTTP 请求均复用 TOINGG_API_TOKEN Bearer Token。

初始化配置

1. 在所有运行这些脚本的环境（gateway、cron、终端等）中导出您的 Token：

   export TOINGG_API_TOKEN="tg_..."

2. 若需处理 Excel 文件，请一次性安装 Python 依赖：

   pip install openpyxl requests

3. 将各类载荷（如活动 JSON 配置、分析快照、联系人导出文件）按贵方安全策略，存入版本控制系统或共享存储。

推广活动发现工作流

当用户希望查看当前活跃活动，或需先获取活动 ID 再发起外呼时，请执行此流程：

1. 首先确认用户是否已知目标活动 ID。若未知，主动提供获取最新活动列表的服务（默认分页参数即可；仅当用户明确要求不同页大小时再调整）。

2. 执行命令：

   ./scripts/fetch_campaigns.py --skip 0 --limit 10 --sort -1 > responses/campaigns-$(date +%s).json

   如需翻页或更改排序方式，请相应调整 --skip / --limit / --sort 参数。

3. 向用户清晰摘要响应内容：至少呈现 campID、name、状态（status）及关键时间字段（如创建/生效时间），以便其准确选择。
4. 若后续操作依赖该快照，请妥善保存生成的 JSON 输出文件。

按需外呼工作流

当用户请求发起一次外呼时，必须在调用 API 前完整收集以下三项信息：

1. 主叫者姓名（将在 Toingg 日志中显示的字符串）
2. 国际格式电话号码（例如 +919999999999）
3. 目标推广活动：若用户未指定活动 ID，请询问是否需要先获取最新活动列表，并按上述「推广活动发现工作流」为其提供选项，随后确认其最终选择。

待全部信息确认无误后，触发 API 调用：

./scripts/make_call.py "接收方姓名" +919999999999 64fd3f9...

该辅助脚本始终以产品团队设定的默认值发送以下参数：asr=AZURE、startMessage=true、clearMemory=false、extraParams={}。请将 API 响应（成功或失败）原样反馈给用户，使其即时掌握外呼状态。

推广活动创建工作流

1. 向用户收集活动各项字段（标题、语音、语言、话术脚本、用途、语气、外呼后数据结构 schema、通知号码、自动应答开关等）
2. 参考 [references/payload-template.md](references/payload-template.md) 提供的模板结构，起草完整的活动 JSON 载荷

3. 运行辅助脚本：

   cd skills/toingg-create-campaign
   ./scripts/create_campaign.py payloads/my_campaign.json > responses/create-$(date +%s).json

4. 将 API 响应（含新生成的 campaign ID、状态或校验错误）返回用户，并同步记录日志。

可选分析定时任务（每日 19:00）

仅当用户明确要求每日自动获取分析数据时，才启用此项服务。

1. 与用户确认期望的执行时间及输出目录路径

2. 参照 [references/analytics-cron.md](references/analytics-cron.md) 中提供的命令片段，执行如下操作创建定时任务：

   openclaw cron create toingg-analytics-digest ...

   根据实际部署路径调整相关参数。

3. 启用前务必再次验证 TOINGG_API_TOKEN 是否对 gateway 可见（即环境变量已正确加载）
4. 首次执行完成后，及时告知用户 JSON 快照的存储位置，并说明如何停用该定时任务（openclaw cron delete ...）

此外，get_campaign_analytics.py 亦支持手动调用以获取即时分析数据：

./scripts/get_campaign_analytics.py > analytics.json

联系人上传 + WhatsApp 模板广播

当用户提供 Excel 表格（含姓名 / 电话 / 上下文等列），并希望批量发送 WhatsApp 模板消息时，请按以下步骤操作：

1. Excel → JSON 转换

   ./scripts/xlsx_to_contacts.py ~/Downloads/leads.xlsx contacts.json

   具体列名规范与排错指南详见 [references/contact-workflow.md](references/contact-workflow.md)。脚本会自动跳过空白行，并对电话号码进行标准化处理。

2. 上传联系人至 Toingg 联系人列表（如列表不存在则自动创建）：

   ./scripts/add_contacts.py ClawTest contacts.json

3. 发送 WhatsApp 模板消息（待联系人列表准备就绪后）：

   ./scripts/send_whatsapp_templates.py \
     231565687 \
     bfesfbgf \
     en-US \
     ClawTest \
     --payload template-variables.json

   • 若模板不含变量，可省略 --payload 参数（此时默认传入空数组 []）
   • 仅当用户明确要求重新触达已有接收者时，才添加 --resend 参数
4. 在 Toingg 后台确认消息投递状态，并将任何错误信息（包括脚本打印的完整 JSON 响应）如实反馈给用户，便于问题追踪与日志归档。

文件映射表

请保持本工具包轻量简洁：当 Toingg 新增字段或引入新工作流时，及时更新 references/ 下的相关文档，确保其他运维人员可沿用统一规范。