HubSpot を接続する

grantry を HubSpot に接続すると、エージェントが CRM（取引・連絡先）やマーケティングEメールのデータを扱えるようになります。

接続方法は OAuth と アクセストークン（Private App） の 2 通りです。どちらでも構いません。

できること（必要なスコープ）

操作	必要な HubSpot スコープ
取引（Deals）の読み取り・作成	`crm.objects.deals.read` / `crm.objects.deals.write`
連絡先（Contacts）の読み取り・作成	`crm.objects.contacts.read` / `crm.objects.contacts.write`
マーケティングEメールの取得・操作	`content`

マーケティングEメールには content が必須

content スコープが無いと、CRM は動いてもマーケティングEメール系（/marketing/v3/emails）だけが 403 エラーになります。マーケティングEメールを使う場合は、下記のどちらの方式でも content を必ず含めてください。

マーケティングEメールを使う場合は、OAuth アプリ側で content を任意（optional）スコープとして設定しておく必要があります。設定後、content を許可した状態で接続し直してください。

サービス用アカウントで固定的に繋ぎたい場合はこちら。

HubSpot にログインし、設定（⚙️）→ 連携 → 非公開アプリ（Private Apps） を開く
- URL の形式: https://app.hubspot.com/private-apps/{ポータルID}
新しい非公開アプリを作成
スコープタブで、使いたい操作に応じて以下を有効にする
- crm.objects.deals.read（必要に応じて .write）
- crm.objects.contacts.read（必要に応じて .write）
- マーケティングEメールを使うなら content
保存し、アクセストークン（pat-... で始まる文字列）をコピー

後からスコープを足したとき

Private App のスコープを追加して保存した場合、同じアクセストークンがそのまま新しい権限で有効になります。grantry へトークンを貼り直す必要はありません。接続画面で再チェックすればOKです。

接続後、ダッシュボードの接続カードで状態を確認できます。一部の操作だけ失敗する場合は、スコープ不足がほとんどです。