sales-qwilr-automation

Qwilr を CRM や各種ツールと連携して自動化する

Qwilr REST API、Zapier、またはネイティブ連携を通じて、Qwilr と CRM やその他のツールを連携する自動化の構築を支援します。

Qwilr API の概要

Qwilr REST API を使うと、保存済みブロックからトークンを置換してページを作成したり、インタラクティブな価格設定を含む見積もりセクションを管理したり、リアルタイムのエンゲージメント情報を受け取る Webhook を登録したりできます。

クイックリファレンス：ベース URL は https://api.qwilr.com/v1、JWT Bearer 認証を使用します。主なエンドポイント：POST /pages（作成）、GET /blocks/saved（テンプレートの確認）、POST /webhooks（イベントの登録）。

エンドポイント、curl の例、トークンのマッピング、見積もりブロックの構造、テストチェックリストを含む API リファレンス全体については、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 — 自動化を構築する

構築プロセスは4つの段階で進めます。curl の例、JSON ペイロード、トークンのマッピングの詳細については、references/qwilr-api-reference.md を参照してください。

3a. 利用可能なブロックを確認する

GET /blocks/saved を使って保存済みブロックを一覧表示し、ページ作成に使うブロックの id 値を確認します。

3b. CRM データからページを作成する

templateId または blocks 配列を指定して POST /pages を使用します。CRM の項目値は最上位の substitutions オブジェクト1つに渡します（API では変数を「tokens」ではなく「substitutions」と呼びます）。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、連絡先名、担当者情報、取引金額
• 半自動（入力後に確認する）：industry、company_size、product
• 必ず手動で入力する：エグゼクティブサマリー、課題、カスタム範囲
• ページに生の {{token}} テキストが表示されないよう、任意トークンにはフォールバック値を設定する

ステップ 5 — テストチェックリスト

本番稼働前に、認証の検証、ブロックの検出、トークンのレンダリング、見積もりブロックの正確性、Webhook の配信、CRM の同期、エラー処理、公開フローを一通り確認します。完全なチェックリストは references/qwilr-api-reference.md にあります。

よくある自動化レシピ

よくある 3 つのパターン（実装の詳細は 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. 取引ステージの変更をトリガーとして設定し、templateId とトップレベルの substitutions オブジェクトを指定して POST /pages を実行します（文字列のみ、フォールバック値を設定）。まずテストできるよう、published: false に設定します。
4. 返された Qwilr ページの URL を HubSpot の取引プロパティに書き戻します。

結果：ステージ 3 に進んだ取引には、値が入力済みの Qwilr 提案書が作成され、URL が取引レコードに保存されます。手動でコピー＆ペーストする必要はありません。

例 2：見込み客が提案書を閲覧または承諾したら、Slack に通知して CRM を同期する

ユーザーの発言：「誰かが提案書を開いたら Slack に通知し、承諾したら取引を「受注」に移動したいです。」

スキルの動作：

1. POST /webhooks を介して Webhook イベントを登録します。閲覧の通知には pageFirstViewed、承諾には pageAccepted を使用します。
2. イベント ID を基準に重複を排除する、冪等性のある Webhook ハンドラーを作成してから処理します（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 を案内します。JWT は環境変数（$QWILR_TOKEN）から 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