SaleSmartly API Skills

29 个核心脚本 | 100% API 覆盖 | 所有脚本支持 --json 结构化输出

红线规则

禁止直接使用 curl/Python/HTTP 客户端调用 SaleSmartly API，必须使用 scripts/ 中的脚本。

# ✅ 正确
uv run scripts/query-customers.py --days 7

# ❌ 禁止
curl -X GET "https://developer.salesmartly.com/api/v2/..."

脚本自动处理签名计算、SSL 验证、分页、时间格式转换、错误提示。详见 NO-DIRECT-API.md。

Few-shot 示例

示例 1：查询销售数据

用户: "查一下昨天的销售数据"

调用:

uv run scripts/daily-sales-report.py --days 1

示例 2：查询 VIP 客户

用户: "有哪些 VIP 客户"

调用:

uv run scripts/query-customers.py --tags "VIP"

示例 3：模糊意图澄清

用户: "我想看看数据"

澄清话术:

请问具体是：
1. 销售数据（每日销售额）
2. 客户数据（新增客户、客户列表）
3. 会话数据（客服接待量）
4. 其他数据（请具体说明）

示例 4：批量操作

用户: "批量分配这些客户给小李"

调用:

uv run scripts/batch-assign-session.py \
  --chat-user-ids abc123,def456 \
  --assign-sys-user-id 456 \
  --sys-user-id 789 \
  --action start

示例 5：WhatsApp 设备管理

用户: "添加一个 WhatsApp 设备"

调用:

uv run scripts/add-whatsapp-device.py --country us

用户意图映射

ID 字段说明

口诀：客服 ID = sys_user_id，客服发消息时 sender = sys_user_id

错误处理指南

核心能力

1. 客户管理 - 查询、创建、更新客户，批量操作标签，导入订单
2. 团队管理 - 获取团队成员信息，会话统计，在线时长
3. 会话管理 - 查询聊天记录、会话分配、批量回聊、结束会话
4. 营销管理 - 分流链接管理与数据统计
5. 集成管理 - WhatsApp 设备全生命周期管理
6. 数据分析 - 销售报告、客户反馈分析、跟进提醒、钉钉推送

配置方式

在 api-key.json 中配置（也支持环境变量 SALESMARTLY_API_KEY / SALESMARTLY_PROJECT_ID）：

{
  "apiKey": "your_api_key",
  "projectId": "your_project_id",
  "dingtalk": {
    "webhook": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"
  }
}

可用命令

客户管理

uv run scripts/query-customers.py --days 7 --page-size 20
uv run scripts/query-customers.py --chat-user-id <ID>
uv run scripts/create-customer.py --phone 8613800138000 --remark-name "客户名"
uv run scripts/update-customer.py --chat-user-id <ID> --remark "备注"
uv run scripts/batch-tags.py --ids <ID1>,<ID2> --update-label-names "VIP" --update-type append
uv run scripts/import-orders.py --chat-user-id <ID> --order-id <ORDER_ID>
uv run scripts/get-customer-history.py --chat-user-id <ID>
uv run scripts/find-followup-customers.py --days 7
uv run scripts/customer-stats.py --days 30

团队管理

uv run scripts/query-members.py --status active
uv run scripts/member-session-stats.py --today
uv run scripts/online-duration-report.py --today

会话管理

uv run scripts/query-sessions.py --days 7 --page-size 10
uv run scripts/query-messages.py --chat-user-id <ID> --days 7
uv run scripts/query-all-messages.py --yesterday
uv run scripts/assign-session.py --session-id <SID> --chat-user-id <ID> --assign-sys-user-id <客服ID>
uv run scripts/batch-assign-session.py --chat-user-ids <ID1>,<ID2> --assign-sys-user-id <客服ID> --sys-user-id <操作者ID> --action start
uv run scripts/batch-talk-back.py --chat-user-ids <ID1>,<ID2> --sys-user-id <客服ID>
uv run scripts/end-session.py --session-id <SID> --chat-user-id <ID>

营销管理

uv run scripts/query-links.py --days 30
uv run scripts/query-link-records.py --page-size 50

WhatsApp 管理

uv run scripts/query-whatsapp-apps.py --status 1
uv run scripts/add-whatsapp-device.py --country us
uv run scripts/get-whatsapp-qrcode.py --id <设备ID>
uv run scripts/set-whatsapp-proxy.py --id <设备ID> --is-proxy 1 --host <主机> --port <端口>
uv run scripts/delete-whatsapp-device.py --id <设备ID>

数据分析

uv run scripts/daily-sales-report.py --days 1
uv run scripts/daily-feedback-report.py
uv run scripts/check-customer-feedback.py --days 7

通用参数

所有脚本支持以下参数：

JSON 输出格式：

{"success": true, "data": {...}, "meta": {"total": 100, "page": 1}}
{"success": false, "error": {"code": 10001, "message": "..."}}

分页处理

大数据量查询必须使用 --all 参数自动翻页：

uv run scripts/query-customers.py --days 7 --all

其他注意事项

1. API 域名: https://developer.salesmartly.com
2. 时间戳: 13 位毫秒自动转换为秒
3. 分页限制: page_size 最大 100
4. SSL 验证: 默认启用完整 SSL 验证

相关文档

• GitHub 仓库
• API 文档
• 签名规则
• 禁止直接调用 API

场景示例

查看 examples/ 目录中的场景化示例：

最佳实践

1. 先确认，再执行

涉及修改/发送的操作，先向用户确认：

AI: 您想给 156 个客户发送消息，确认吗？

2. 主动提供下一步

查询后主动询问：

AI: 找到 23 个 VIP 客户。需要我：
   1. 导出联系方式
   2. 发送活动通知
   3. 查看详细信息

3. 模糊时多问一句

AI: 您想查哪个时间范围的销售？昨天 / 今天 / 最近 7 天 / 指定日期

4. 使用 --json 获取结构化数据

当需要对结果做进一步处理时，使用 --json 参数获取机器可读输出。