介绍
# Campaign Orchestrator Skill
用于 ShapeScale 销售的多渠道跟进营销活动编排器。执行预定的 SMS + 邮件序列，集成 CRM，并在收到回复时自动终止。
## 概述
**Campaign（营销活动）** 是一系列随时间执行的已定义步骤（短信/邮件）。当线索回复任何消息时，营销活动将自动终止。
### 主要功能
- **多渠道**：SMS (Dialpad) + 邮件 (Gmail) - **定时执行**：基于 Cron 的执行，具有可配置的延迟 - **个性化**：使用 Attio CRM 数据填充模板 - **自动终止**：回复将停止所有未来的计划步骤 - **日志记录**：所有活动记录在 Attio 中
## 设置
**所需环境变量：** ```bash DIALPAD_API_KEY=your_dialpad_api_key ATTIO_API_KEY=your_attio_api_key GOG_KEYRING_PASSWORD=your_google_password # For Gmail access ```
**同时请确保：** - Dialpad webhook 已配置为命中此服务器 - Attio 中包含线索的公司/联系人记录 - 已为销售邮件启用 Gmail API 访问
## 使用方法
### 启动营销活动
```bash # Start primary follow-up campaign for a lead python3 campaign.py start "primary" --lead "Apex Fitness"
# Start with custom delay override (hours) python3 campaign.py start "primary" --lead "Apex Fitness" --delay 2
# Start with Attio deal/company ID python3 campaign.py start "post-demo" --lead "Apex Fitness" --attio-id "deal-uuid" ```
### 营销活动前检查清单（必须）
在启动任何营销活动之前，请验证：
1. **客户状态检查** - 在记忆/CRM 中搜索“已是客户”或“已购买”标记 - 检查 campaigns.json 中的排除列表 - 验证电子邮件域名不在客户数据库中
2. **邮件格式检查**（针对邮件步骤） - 预览模板呈现为正确的段落 - 每段 2-4 句话，段落之间有空行 - 没有单句孤立的段落 - 段落中间没有硬换行
3. **语气检查** - 没有道歉性语言（如“no worries”、“sorry to bother”） - 没有简单的推脱（如“if not relevant, no problem”） - 专业，而不是恳求
**除非明确要求进行追加销售，否则绝不向现有客户发送营销信息。**
### 检查营销活动状态
```bash # Status for specific lead python3 campaign.py status "Apex Fitness"
# All active campaigns python3 campaign.py list ```
### 停止营销活动
```bash # Manual termination (lead replied, not interested, etc.) python3 campaign.py stop "Apex Fitness" --reason "replied_interested" ```
### 移除线索
```bash # Remove lead from campaigns (opted out, not interested) python3 campaign.py remove "Apex Fitness" ```
### 检查回复
```bash # Check if lead has responded to any prior messages python3 campaign.py check "Apex Fitness" # Shows response status for each completed step # Warns if responses detected (safe to proceed or terminate) ```
### 查看待处理步骤
```bash # Show all pending campaign steps sorted by time python3 campaign.py pending # Useful for seeing what's due soon across all campaigns ```
### 模板管理
```bash # List available templates python3 campaign.py templates
# Preview a template python3 campaign.py preview "primary" ```
## 营销活动模板
| 模板 | 时间 | 渠道 | 目的 | |----------|--------|---------|---------| | `primary` | +4 小时 | SMS | 回顾演示，分享录像 | | `secondary` | +1 天 | 邮件 | 价格，详细 ROI | | `tertiary` | +4 天 | SMS | 快速跟进 | | `quaternary` | +7 天 | 邮件 | 最后跟进，案例研究 | | `post-demo` | +0 小时 | SMS | 立即致谢 |
### 模板变量
模板支持变量替换：
``` {name} - Lead first name {company} - Company name {deal_value} - Deal value from Attio {owner} - Sales owner name {demo_notes} - Notes from demo conversation {checkout_link} - Personalized checkout URL ```
## 架构
``` campaign-orchestrator/ ├── SKILL.md # This file ├── campaign.py # Main CLI (start, stop, status, list) ├── webhook_handler.py # Processes reply → termination ├── primary.md # SMS follow-up template ├── secondary.md # Email template ├── post-demo.md # Immediate follow-up template └── state/ └── campaigns.json # Campaign state persistence ```
## 状态管理
营销活动状态存储在 `<workspace>/state/campaigns.json` 中：
```json { "campaigns": { "Apex Fitness": { "template": "primary", "attio_id": "deal-uuid", "started": "2026-01-27T13:00:00Z", "steps_completed": ["sms_primary"], "next_step": "email_secondary", "next_scheduled": "2026-01-28T13:00:00Z", "status": "active" } }, "templates": { "primary": {...}, "secondary": {...} } } ```
## Cron 集成
营销活动步骤通过 Clawdbot 的 cron 系统执行：
- **执行器作业**：每 5 分钟运行一次，检查到期步骤 - **每个营销活动的作业**：为每个计划步骤创建
调度器脚本会自动创建和管理这些作业。
## Webhook 处理
当 Dialpad 收到对营销活动消息的回复时：
1. Dialpad 发送 webhook 到服务器 2. `webhook_handler.py` 解析回复 3. 查找原始消息属于哪个营销活动 4. 将营销活动标记为已终止 5. 将回复记录到 Attio
## 集成点
### Dialpad SMS ```bash python3 /home/art/niemand/skills/dialpad/send_sms.py --to "+14155551234" --message "..." ```
### Gmail (via gog) ```bash gog-shapescale --account [email protected] send-email --to "[email protected]" --subject "..." --body "..." ```
### Attio CRM ```bash attio note companies "company-uuid" "Campaign message sent: {message}" ```
## 示例
### 完整营销活动工作流
```bash # 1. After demo, start campaign /campaign start "post-demo" --lead "Dr. Smith's Clinic"
# 2. Check status next day /campaign status "Dr. Smith's Clinic" # Output: Step 1 sent, Step 2 scheduled for tomorrow
# 3. Lead replies "interested" # Webhook automatically terminates campaign # Logs reply to Attio
# 4. Manual follow-up if needed /campaign start "secondary" --lead "Dr. Smith's Clinic" --delay 0 ```
### 监控活跃营销活动
```bash # List all active /campaign list
# Output: # Active Campaigns: # - Apex Fitness (primary) - Step 2/4, next: email # - Dr. Smith's Clinic (post-demo) - Complete # - Wellness Center (tertiary) - Step 1/3, next: sms ```
## 故障排除
**营销活动未发送：** - 检查 `cron` 是否正在运行：`crontab -l` - 检查日志：`journalctl -u moltbot` 或营销活动日志 - 验证 API 密钥：`echo $DIALPAD_API_KEY`
**Webhook 未终止：** - 验证 Dialpad webhook URL 是否已配置 - 检查 webhook 处理程序是否正在运行 - 检查 `campaigns.json` 中是否有匹配的线索
**模板变量未填充：** - 验证线索在 Attio 中存在且具有必填字段 - 检查模板语法：使用 `{variable}` 而不是 `{ variable }`
## 许可证
shapescale-moltbot-skills 的一部分。请参阅父存储库。