sales-qwilr-automation

使用 CRM 和工具自动化 Qwilr

帮助用户构建自动化流程，将 Qwilr 与 CRM 和其他工具连接起来——通过 Qwilr REST API、Zapier 或原生集成。

Qwilr API 概览

Qwilr REST API 支持使用已保存的内容块和令牌替换创建页面、管理包含交互式定价的报价部分，以及订阅 Webhook，以实时获取参与度信号。

快速参考：基础 URL 为 https://api.qwilr.com/v1，使用 JWT Bearer 身份验证。关键端点：POST /pages（创建）、GET /blocks/saved（查找模板）、POST /webhooks（订阅事件）。

完整的 API 参考——包括端点、curl 示例、令牌映射、报价内容块结构和测试清单——请参阅 references/qwilr-api-reference.md。

步骤 1 — 收集背景信息

如果存在 references/learnings.md，请先阅读以了解累积的知识。

询问用户：

1. 您想自动化什么？

   • A) 当交易进入特定阶段时自动创建提案
   • B) 将提案状态／接受状态同步回 CRM
   • C) 在潜在客户查看或接受提案时收到通知
   • D) 完整双向流程：从 CRM 数据创建提案，并将参与度信息同步回来
   • E) 其他——请描述

2. 您正在使用什么 CRM／工具？

   • A) HubSpot
   • B) Salesforce
   • C) Pipedrive
   • D) Zoho CRM
   • E) 其他 CRM（请说明）
   • F) 没有 CRM——仅使用 API／Webhook

3. 您更倾向于使用哪种自动化平台？

   • A) Zapier
   • B) Make (Integromat)
   • C) 直接调用 API（代码／脚本）
   • D) Qwilr 原生集成（HubSpot／Salesforce／Pipedrive）
   • E) 不确定——请推荐合适的方案

4. 您使用的是哪种 Qwilr 方案？（会影响 API 访问权限和原生集成）

如果用户的请求已经提供了大部分背景信息，请直接跳到相关步骤。 在合理假设（并明确说明）的基础上，先尽力给出答案，然后只在末尾询问最关键的 1—2 个澄清问题——不要因为需要收集完整背景信息而延后答复。

步骤 2 — 推荐架构

根据用户的回答，推荐合适的方案并说明权衡：

原生集成（最简单）

• HubSpot：Qwilr 的原生集成会使用 HubSpot 交易／联系人数据自动填充模板，并将接受状态同步回交易属性
• Salesforce：原生集成会将 Salesforce 商机字段映射到 Qwilr 令牌，并根据商机记录创建提案
• Pipedrive：原生集成可将交易数据连接到 Qwilr 模板
• 最适合：希望零代码配置并使用受支持 CRM 的团队
• 限制：可定制程度低于 API，且仅支持有限的字段映射

Zapier / Make（中等复杂度）

• 最适合：涉及多种工具的工作流（例如，收到 Stripe 付款时创建提案，或在查看提案时通知 Slack）
• 方案：使用 Qwilr 的 Zapier 触发器（页面已查看、已接受）和操作（创建页面）
• 限制：执行速度较慢，大规模使用时可能触及速率限制，并且按任务收费

直接调用 API（功能最强）

• 最适合：自定义工作流、高调用量、复杂逻辑（条件部分、动态定价计算）
• 方案：直接从您的后端、无服务器函数或脚本调用 Qwilr REST API
• 限制：需要投入开发工作

步骤 3 — 构建自动化流程

构建流程分为四个阶段。curl 示例、JSON 负载和令牌映射详情，请参阅 references/qwilr-api-reference.md。

3a. 查找可用内容块

通过 GET /blocks/saved 列出已保存的内容块，以查找创建页面所需的内容块 id 值。

3b. 使用 CRM 数据创建页面

使用 POST /pages 并提供 templateId 或 blocks 数组。在单个顶层 substitutions 对象中传入 CRM 字段值（API 将这些变量称为“替换项”，而非“令牌”），设置 published（而非 isPublished），并将报价部分放在已保存内容块内，以实现交互式定价。确切的字段名称请参阅 references/qwilr-api-reference.md。

3c. 订阅 webhook 事件

订阅 pageFirstViewed、pageViewed、pageAccepted 和 pagePartiallyAccepted 事件，以获取实时互动信号。

3d. 检查页面状态

使用 GET /pages/{id}?expand=acceptance,metadata 轮询页面详情和接受状态。

第 4 步 — 令牌／替换值映射

设计 CRM 字段与 Qwilr 模板令牌之间的映射。常见令牌包括 {{company_name}}、{{contact_first_name}}、{{deal_amount}}、{{rep_name}} 等。如需查看完整的令牌参考和指南，请参阅 references/qwilr-api-reference.md。

关键原则：

• 始终自动填充：company_name、联系人姓名、销售代表信息、交易金额
• 半自动（填充后核实）：行业、公司规模、产品
• 始终手动填写：执行摘要、痛点、自定义范围
• 为可选令牌设置备用值，避免页面显示原始的 {{token}} 文本

第 5 步 — 测试清单

上线前进行端到端检查：身份验证、区块发现、令牌渲染、报价区块准确性、webhook 投递、CRM 同步、错误处理和发布流程。完整清单请参阅 references/qwilr-api-reference.md。

常见自动化方案

三种常见模式（详细实现请参阅 references/qwilr-api-reference.md）：

1. 交易进入第 3 阶段时自动创建提案：CRM 触发器 → POST /pages → 使用 Qwilr URL 更新 CRM
2. 查看提案时通知 Slack：pageFirstViewed webhook → Slack 消息 → 销售代表跟进
3. 接受提案时更新 CRM：pageAccepted webhook → 将交易阶段更新为 Closed Won → 触发入职流程

注意事项

• Zapier 可用时，不要用自定义 API 把事情复杂化。 如果用户的自动化只是简单的触发器—操作（交易进入某阶段 → 创建提案），使用 Zapier 或原生集成会更快，也更易于维护。只有自定义逻辑、高调用量或复杂条件工作流才需要直接调用 API。

• 不要忘记 webhook 重试和去重。 Qwilr webhook 可能会在失败时重试，导致同一事件被发送多次。任何 webhook 处理程序都必须具备幂等性——处理前检查是否存在重复的事件 ID。Claude 经常生成缺少这项检查的 webhook 处理程序。

• 不要未经核实就假定 CRM 字段名称。 Salesforce 自定义字段以 __c 结尾，HubSpot 使用的内部属性名称可能与显示名称不同，Pipedrive 则使用自定义字段键。构建映射前，务必提醒用户核实实际的字段名称／ID。

• 不要跳过沙盒／测试数据测试。 Claude 往往会生成直接面向生产环境的 API 代码。务必建议先创建 published: false 的测试页面，在 CRM 中使用测试交易，并在上线前确认替换值能正确渲染。

• 替换值只能是字符串。 Qwilr 不会对变量值进行格式化——日期和数字必须以最终格式的字符串传入（例如 "$48,000"、"March 30, 2026"）。发送前先格式化 CRM 值；未提供的变量会渲染为空字符串。

• API 访问受套餐限制且需付费。 根据 Qwilr 的文档和 API 页面，使用 API 需要开通 API 访问权限的 Enterprise 账户，并需支付额外费用（请联系 Qwilr 销售团队）。推荐直接调用 API 构建方案前，先确认用户拥有 API 访问权限；否则应建议使用原生集成或 Zapier。

• 不要在脚本中硬编码 API 令牌。 使用环境变量（$QWILR_TOKEN）进行身份验证。Claude 有时会生成在代码中内联占位令牌的示例——务必提醒用户使用环境变量或密钥管理器。

• 持续改进：如果发现此处未涵盖的内容，请将其连同当天日期追加到 references/learnings.md。

示例

示例 1：HubSpot 商机进入第 3 阶段时自动创建 Qwilr 提案

用户说：“当 HubSpot 中的商机进入‘提案’阶段时，我希望自动创建一份 Qwilr 提案，并将链接写回商机。”

技能会：

1. 询问适合使用哪个自动化平台——此处建议使用 HubSpot 原生集成或 Zapier，因为这是简单的触发-操作流程；只有需要自定义逻辑时才使用直接 API。
2. 将 HubSpot 商机/联系人字段映射到 Qwilr 替换字段（company_name、contact_first_name、deal_amount、rep_name），并提醒 HubSpot 内部属性名称与显示名称不同。
3. 将触发器设置为商机阶段变更，然后调用 POST /pages，传入 templateId 和顶层 substitutions 对象（仅包含字符串，并提供备用值）；首先设置 published: false 进行测试。
4. 将返回的 Qwilr 页面 URL 写回 HubSpot 商机属性。

结果：每个进入第 3 阶段的商机都会获得一份预填好的 Qwilr 提案，URL 也会保存到商机记录中，无需手动复制粘贴。

示例 2：潜在客户查看或接受提案时通知 Slack 并同步 CRM

用户说：“有人打开我的提案时，我希望收到 Slack 提醒；他们接受提案后，商机应转为‘已赢单’。”

技能会：

1. 通过 POST /webhooks 订阅 Webhook 事件——查看信号使用 pageFirstViewed，接受提案使用 pageAccepted。
2. 构建幂等的 Webhook 处理程序，操作前根据事件 ID 去重（Qwilr 可能会重试并重新发送同一事件）。
3. 将 pageFirstViewed 路由到 Slack 消息，以便销售代表及时跟进。
4. 将 pageAccepted 路由为更新 CRM 商机阶段至“已赢单”，并触发入门流程。

结果：Slack 中可实时收到查看提醒，商机会自动更新为“已赢单”，且不会重复发送 Slack 提醒或多次变更商机阶段。

故障排除

页面显示原始 {{token}} 文本，而不是对应的值

原因：某个替换变量被遗漏、命名错误或未提供备用值——Qwilr 会显示未匹配的标记，并将遗漏的变量渲染为空字符串。 解决方案：确认模板中的每个标记在顶层 substitutions 对象中都有对应键；以预先格式化的字符串传递值（例如 "$48,000"，因为 Qwilr 不会进行数字/日期格式化）；并为可选标记设置备用值，避免原样显示 {{token}}。

同一提案查看或接受事件触发多次 Webhook

原因：Qwilr 会在 Webhook 投递失败时重试，因此同一个 pageViewed/pageAccepted 事件可能到达多次；非幂等的处理程序会重复处理这些事件。 解决方案：确保处理程序具备幂等性——在处理前存储并检查事件 ID，跳过已处理的事件，以确保 Slack 提醒和 CRM 更新都只触发一次。

直接 API 调用返回身份验证或访问错误

原因：Qwilr REST API 受套餐限制——需要启用 API 访问权限的 Enterprise 账户（需额外付费），或者 JWT Bearer 令牌缺失/无效。 解决方案：建议直接构建 API 集成前，先确认账户已启用 API 访问权限；否则应引导用户使用 CRM 原生集成或 Zapier。通过环境变量（$QWILR_TOKEN）提供 JWT Bearer 令牌，切勿将令牌硬编码到脚本中。

相关技能

• /sales-proposal-page — 编写实际的提案内容并设计报价区块
• /sales-proposal-analytics — 解读互动信号并决定后续跟进措施
• /sales-proposal-template — 设计可通过 API 自动填充的可复用模板
• /sales-deal-room — 适用于复杂的多页面商机空间
• /sales-do — 不确定该使用哪个技能？路由器会根据销售目标匹配合适的技能。安装：npx skills add sales-skills/sales --skill sales-do