HubSpotを接続する
HubSpot連携の認可手順、Steveが要求するスコープ、保存されるデータ、接続の確認方法
概要
HubSpotとSteveの接続は、1回のOAuth認可だけです。所要時間は約1分で、完了した瞬間に取引と会社の初回インポートが自動的に始まります。
対象者: 📣 PMM／管理者 — 連携の接続は組織レベルの操作です。
先に前提条件を確認してください。 HubSpotアカウントの要件 をお読みください。ロール、プロジェクト、HubSpotの権限に関する問題は、分かりにくいエラーとしてこの画面に現れます。
前提条件
| 要件 | 内容 |
|---|---|
| Steveにサインイン済み | app.hiresteve.ai。本ガイドの操作はすべてSteveアプリ上で行います。 |
| Steveの組織マネージャー権限 | 連携の追加・設定・削除ができるのは組織マネージャーだけです。 |
| Individual Sales以外のロール | HubSpotのページはIndividual SalesユーザーをProjectsへリダイレクトします。 |
| 取引を持つHubSpotアカウント | CRMがあるプランであれば構いません。 |
| HubSpotでアプリをインストールする権限 | マーケットプレイスが制限されている場合は、スーパー管理者に認可または事前承認を依頼してください。 |
| HubSpotの取引プロパティ権限 | 認可時にSteveがカスタムプロパティを作成できるようにするためです。 |
どこから始めるか
HubSpotアプリマーケットプレイスではなく、Steveから始めてください。 認可の
stateパラメータにSteveの組織IDが含まれるため、Steveの設定ページから開始する必要があります。他の場所から始めると 「Invalid state parameter」 で戻され、何も接続されません。
ステップ1: HubSpot設定タブを開く
- app.hiresteve.ai でSteveにログインします。
- ナビゲーションメニューの Settings をクリックします。
- HubSpot タブを開きます。
app.hiresteve.ai/settings?tab=hubspot から直接開くこともできます。
カードには HubSpot Integration — Connect your HubSpot account to sync deal data with Steve と表示され、オレンジのクラウドアイコンが付いています。未接続の状態では警告アラート HubSpot Not Connected — Connect your HubSpot account to start syncing deal data with Steve. が表示されます。
キャプション: 連携前の「設定 → HubSpot」画面。
ステップ2: HubSpotで認可する
- Connect to HubSpot をクリックします。
- Steveが
app.hubspot.com/oauth/authorizeの認可画面へ遷移させます。 - 未ログインの場合はHubSpotにサインインします。
- 複数のHubSpotアカウントにアクセスできる場合は、Steveに取り込みたい取引がある ポータルを選択 します。
- Steveが要求する権限（下記）を確認します。
- Connect app をクリックします。
- HubSpotがSteveの設定画面へ戻します。
キャプション: HubSpotの同意画面 — ポータルが正しいか確認し、スコープを見てから接続します。
要求される権限
| 権限 | スコープ | 用途 |
|---|---|---|
| 基本OAuth | oauth | HubSpotがすべてのOAuthアプリに要求します。 |
| 取引の読み取り | crm.objects.deals.read | 取引とそのプロパティを取り込みます。 |
| 取引の書き込み | crm.objects.deals.write | 競合アノテーション、バトルカードリンク、関連通話、勝因・失注理由、AI抽出値を取引へ書き戻します。 |
| 取引プロパティの読み取り | crm.schemas.deals.read | マッピングと同期対象の選択のためにプロパティ一覧を取得します。 |
| 取引プロパティの書き込み | crm.schemas.deals.write | Steveのカスタム取引プロパティを作成します。 |
| 会社の読み取り | crm.objects.companies.read | 会社タブへ会社を取り込みます。 |
| 会社の書き込み | crm.objects.companies.write | AI抽出値を会社レコードへ書き込みます。 |
| 会社プロパティの読み取り | crm.schemas.companies.read | プレイブックの項目マッピング用に会社プロパティを取得します。 |
| 会社プロパティの書き込み | crm.schemas.companies.write | プレイブックが必要とする場合にカスタム会社プロパティを作成します。 |
| コンタクトの読み取り | crm.objects.contacts.read | 勝敗サーベイ用に取引の主担当を解決し、通話を正しい会社に紐づけます。 |
| コンタクトの書き込み | crm.objects.contacts.write | 取引・会社のアクティビティタイムラインに書き込む ノート と 通話エンゲージメント を作成・更新します。 |
SteveはHubSpotのレコードを 削除できません。チケット、見積もり、明細、商品、フォーム、マーケティングメール、ワークフローの読み書きも行わず、HubSpotから何かを送信することもありません。
認可した瞬間に自動で起こること
HubSpotからSteveへ戻った瞬間に、3つの処理が順に走ります。
- トークンの交換と保存。 認可コードをアクセストークンとリフレッシュトークンに交換します。HubSpotのアクセストークンは30分で失効するため、Steveはリフレッシュトークンを使って自動更新します。
- 自動作成プロパティの追加。 初回接続時のみ、
steve_connected_callsとsteve_connected_battle_cardsを 取引情報 グループの複数行テキストプロパティとして作成します。権限不足などで失敗しても接続自体は成功し、後からワンクリックで作成できるバナーが表示されます。 - 初回同期のキュー投入。 HubSpotの取引と会社のバックグラウンドインポートを開始します。取引と会社が同期される仕組み を参照してください。
新規接続では、既定の取引プロパティも自動選択されます: dealname、dealstage、amount、dealtype、description、hs_lastmodifieddate、steve_connected_calls。これは フィールドマッピング ページで後から変更できます。
認可後にSteveが保存するもの
| 保存されるもの | 保存先 | 削除されるタイミング |
|---|---|---|
| HubSpotのアクセストークンとリフレッシュトークン | Steveのデータベース（組織スコープ） | Steveで連携を削除したとき |
| 付与されたスコープ、トークン種別、有効期限 | Steveのデータベース（組織スコープ） | Steveで連携を削除したとき |
| フィールドマッピングと選択済みプロパティ | Steveのデータベース（組織スコープ） | Steveで連携を削除したとき |
| 取り込まれた取引 — 名前、ステージ、種別、金額、通貨、クローズ日、パイプライン、説明、選択済みプロパティすべて | Steveのデータベース（組織スコープ） | Steveで連携を削除したとき |
| 取り込まれた会社 — 名前、ドメイン、業種、所在地、規模、売上、ライフサイクルステージ、担当者 | Steveのデータベース（組織スコープ） | Steveで連携を削除したとき |
| アップロードした取引リソースとそこから抽出したインサイト | Steveのデータベースと暗号化オブジェクトストレージ | 削除するまで、または依頼により削除 |
取り込まれたデータは、取り込んだSteve組織の内部からのみ参照できます。完全削除の依頼方法を含む詳細は HubSpot連携を削除する にあります。
ステップ3: 接続を確認する
認可が成功すると、
- 「Successfully connected to HubSpot!」 のトーストが表示されます。
- 設定カードが緑のチェックアラート Connected to HubSpot — Your HubSpot account is successfully connected and ready to sync deal data. に切り替わります。
- View HubSpot Data、Configure Field Mapping、Re-integrate の3つのボタンが表示されます。
- 区切り線の下に、赤い Delete Account ボタンが表示されます — 連携を削除するときはここからです。
キャプション: 緑の「Connected to HubSpot」アラートが、ポータルの接続完了を示します。
ステップ4: セットアップを完了する
接続すれば取引は取り込まれますが、双方向の機能はまだ動きません。競合アノテーション、勝因・失注理由、バトルカードリンクにはマッピング済みプロパティが必要です。
- Steveのプロパティを作成する — 6つのカスタム取引プロパティをワンクリックまたは手動で。
- 項目をマッピングしてプロパティを選ぶ — Save Configuration すると、新しい選択で同期が走ります。
再連携（Re-integrate）
設定カードの Re-integrate は、接続済みのポータルに対して同じOAuthフローを再実行します。次のような場合に使います。
- 琥珀色の 「Re-integrate to enable deal activity notes」 バナーが出ている（ノート用スコープが追加される前に接続した場合）
- 初回に拒否したスコープを付与したい
- 接続先を別のHubSpotポータルに変更したい
再連携は保存済みのトークンとスコープを 更新 します。取引、会社、マッピング、リソース、インサイトは削除されず、プロパティの自動作成も再実行されません。
うまくいかないとき
HubSpot設定タブに戻され、赤いトースト 「HubSpot connection failed: …」 が表示されます。
| メッセージ | 意味 | 対処 |
|---|---|---|
| Authorization code not found | 認可が完了しないまま戻ってきた。 | 同意画面をキャンセル／閉じた可能性があります。Connect to HubSpot をもう一度クリックし、画面を離れずに完了してください。 |
| Invalid state parameter | 応答を組織に紐づけられなかった。 | Steveの設定画面以外から開始したか、途中でセッションが変わりました。/settings?tab=hubspot を再読み込みし、正しい組織を確認してからやり直してください。 |
| Failed to fetch access token | コードとトークンの交換をHubSpotが拒否した。 | 同意画面を開いたまま放置してコードが失効した場合がほとんどです。すぐに再試行してください。繰り返す場合はご連絡ください。 |
| Failed to verify HubSpot connection | トークンは発行されたが確認できなかった。 | 再試行してください。続く場合はアプリがポータルで承認されていない可能性があります。スーパー管理者にご確認ください。 |
| Internal server error occurred | Steve側で想定外の失敗が発生した。 | 1回再試行し、それでも駄目なら発生時刻を添えて tech@hiresteve.ai までご連絡ください。 |
| Unknown error occurred | Steveに個別メッセージのないエラーをHubSpotが返した。 | HubSpotの通知バーで権限拒否の通知を確認してから再試行してください。 |
詳細は トラブルシューティング にあります。
次のステップ
- カスタム項目の作成手順 — Steveのカスタムプロパティを作成する。
- フィールドマッピングとプロパティ選択 — 設定を完了して同期を実行する。
- 取引と会社が同期される仕組み — 初回インポートの中身。
- HubSpot連携を削除する — 削除手順と消えるデータ。