salesmartly-api-skills

星标11

分支2

更新时间2026年4月7日 02:55

SaleSmartly 全功能 API 技能。29 个核心脚本，覆盖客户/会话/营销/WhatsApp 管理。

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

Sale-Smartly

Sale-Smartly/salesmartly-api-skills

打开 GitHub 仓库查看创作者相关仓库

下载

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

用户意图映射

用户说法	调用脚本	关键参数
"查一下昨天的销售"	`daily-sales-report.py`	`--days 1`
"今天有多少咨询"	`customer-stats.py`	`--days 1`
"有哪些客户"	`query-customers.py`	`--days 7`
"VIP 客户有哪些"	`query-customers.py`	`--tags "VIP"`
"查客户 abc123"	`query-customers.py`	`--chat-user-id abc123`
"看看聊天记录"	`query-messages.py`	`--chat-user-id <ID>`
"查昨天的聊天"	`query-all-messages.py`	`--yesterday`
"把这个客户给小王"	`assign-session.py`	`--chat-user-id`, `--assign-sys-user-id`
"批量分配客户"	`batch-assign-session.py`	`--chat-user-ids`, `--action start`
"批量回聊客户"	`batch-talk-back.py`	`--chat-user-ids`, `--sys-user-id`
"结束这个会话"	`end-session.py`	`--session-id`, `--chat-user-id`
"查客户详细信息"	`get-customer-history.py`	`--chat-user-id`
"WhatsApp 设备"	`query-whatsapp-apps.py`	`--status 1`
"客户反馈"	`check-customer-feedback.py`	`--days 7`
"待跟进客户"	`find-followup-customers.py`	`--days 7`
"在线时长"	`online-duration-report.py`	`--today`
"成员会话统计"	`member-session-stats.py`	`--today`

ID 字段说明

对象	正确字段	错误字段	说明
客服 ID	`sys_user_id`	`id`	`id` 是成员关系 ID，不要用于业务场景
客户 ID	`chat_user_id`	-	只有一个，不会混淆
会话 ID	`session_id`	`chat_session_id`	优先使用 `session_id`
消息发送人	`sender` (看 sender_type)	-	sender_type=2 时是客服 sys_user_id

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

错误处理指南

错误类型	AI 回复模板
配置缺失	"请先配置 `api-key.json` 文件，填入您的 SaleSmartly API Key 和 Project ID"
API 错误	"连接 SaleSmartly 失败：{错误信息}，请检查 API Key 是否正确"
无数据	"没有找到符合条件的数据，您可以尝试放宽筛选条件"
参数模糊	"我没理解{参数}，您是想查昨天、今天还是最近 7 天？"
需要确认	"您想给{数量}个客户发送消息，确认要发送吗？"

核心能力

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

配置方式

在 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`	输出结构化 JSON（Agent 解析用）
`--quiet`	安静模式，最少输出
`--config <path>`	指定配置文件路径

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

场景	是否需要翻页
今天的新增客户 (< 50)	通常不需要
最近 7 天的客户 (100-500)	需要
所有客户 (500-2000+)	必须
聊天记录 (数千条)	必须

其他注意事项

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

场景示例

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

示例	场景	文件
01	查询销售数据	`examples/01-查询销售数据.md`
02	查询客户	`examples/02-查询客户.md`
03	发送消息	`examples/03-发送消息.md`

最佳实践

1. 先确认，再执行

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

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

2. 主动提供下一步

查询后主动询问：

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

3. 模糊时多问一句

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

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

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

name	salesmartly-api-skills
description	SaleSmartly 全功能 API 技能。29 个核心脚本，覆盖客户/会话/营销/WhatsApp 管理。
triggers	["客户","销售","发消息","聊天记录","WhatsApp","分配","跟进","反馈","查客户","查销售","销售数据","客户列表","分配会话","客户跟进","待跟进","客户反馈","昨天卖得怎么样","今天有多少咨询","VIP 客户有哪些","给张三发消息","把这个客户给小王","结束这个会话","查聊天记录","WhatsApp 设备","批量分配","批量回聊","在线时长","成员统计"]

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

用户意图映射

用户说法	调用脚本	关键参数
"查一下昨天的销售"	`daily-sales-report.py`	`--days 1`
"今天有多少咨询"	`customer-stats.py`	`--days 1`
"有哪些客户"	`query-customers.py`	`--days 7`
"VIP 客户有哪些"	`query-customers.py`	`--tags "VIP"`
"查客户 abc123"	`query-customers.py`	`--chat-user-id abc123`
"看看聊天记录"	`query-messages.py`	`--chat-user-id <ID>`
"查昨天的聊天"	`query-all-messages.py`	`--yesterday`
"把这个客户给小王"	`assign-session.py`	`--chat-user-id`, `--assign-sys-user-id`
"批量分配客户"	`batch-assign-session.py`	`--chat-user-ids`, `--action start`
"批量回聊客户"	`batch-talk-back.py`	`--chat-user-ids`, `--sys-user-id`
"结束这个会话"	`end-session.py`	`--session-id`, `--chat-user-id`
"查客户详细信息"	`get-customer-history.py`	`--chat-user-id`
"WhatsApp 设备"	`query-whatsapp-apps.py`	`--status 1`
"客户反馈"	`check-customer-feedback.py`	`--days 7`
"待跟进客户"	`find-followup-customers.py`	`--days 7`
"在线时长"	`online-duration-report.py`	`--today`
"成员会话统计"	`member-session-stats.py`	`--today`

ID 字段说明

对象	正确字段	错误字段	说明
客服 ID	`sys_user_id`	`id`	`id` 是成员关系 ID，不要用于业务场景
客户 ID	`chat_user_id`	-	只有一个，不会混淆
会话 ID	`session_id`	`chat_session_id`	优先使用 `session_id`
消息发送人	`sender` (看 sender_type)	-	sender_type=2 时是客服 sys_user_id

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

错误处理指南

错误类型	AI 回复模板
配置缺失	"请先配置 `api-key.json` 文件，填入您的 SaleSmartly API Key 和 Project ID"
API 错误	"连接 SaleSmartly 失败：{错误信息}，请检查 API Key 是否正确"
无数据	"没有找到符合条件的数据，您可以尝试放宽筛选条件"
参数模糊	"我没理解{参数}，您是想查昨天、今天还是最近 7 天？"
需要确认	"您想给{数量}个客户发送消息，确认要发送吗？"

核心能力

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

配置方式

在 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`	输出结构化 JSON（Agent 解析用）
`--quiet`	安静模式，最少输出
`--config <path>`	指定配置文件路径

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

场景	是否需要翻页
今天的新增客户 (< 50)	通常不需要
最近 7 天的客户 (100-500)	需要
所有客户 (500-2000+)	必须
聊天记录 (数千条)	必须

其他注意事项

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

场景示例

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

示例	场景	文件
01	查询销售数据	`examples/01-查询销售数据.md`
02	查询客户	`examples/02-查询客户.md`
03	发送消息	`examples/03-发送消息.md`

最佳实践

1. 先确认，再执行

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

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

2. 主动提供下一步

查询后主动询问：

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

3. 模糊时多问一句

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

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

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

salesmartly-api-skills

SaleSmartly API Skills

红线规则

Few-shot 示例

示例 1：查询销售数据

示例 2：查询 VIP 客户

示例 3：模糊意图澄清

示例 4：批量操作

示例 5：WhatsApp 设备管理

用户意图映射

ID 字段说明

错误处理指南

核心能力

配置方式

可用命令

客户管理

团队管理

会话管理

营销管理

WhatsApp 管理

数据分析

通用参数

分页处理

其他注意事项

相关文档

场景示例

最佳实践

1. 先确认，再执行

2. 主动提供下一步

3. 模糊时多问一句

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

SaleSmartly API Skills

红线规则

Few-shot 示例

示例 1：查询销售数据

示例 2：查询 VIP 客户

示例 3：模糊意图澄清

示例 4：批量操作

示例 5：WhatsApp 设备管理

用户意图映射

ID 字段说明

错误处理指南

核心能力

配置方式

可用命令

客户管理

团队管理

会话管理

营销管理

WhatsApp 管理

数据分析

通用参数

分页处理

其他注意事项

相关文档

场景示例

最佳实践

1. 先确认，再执行

2. 主动提供下一步

3. 模糊时多问一句

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