コンテンツにスキップ

HubSpot 連携

立ち位置

HubSpot は spin-dd が顧客サイトをホストする基盤であり、automedia の文脈では 3 つの顔 を持つ。

役割 内容 MVP (Minimum Viable Product)
ホスティング基盤 サイト本体（automedia の管轄外。Wiki 管理） 範囲外
投稿先（チャネル） HubSpot Marketing Email / Social / Forms 等 後続
データソース コンタクト・タグ・メイト会員データ 段階導入

サイト本体（HubL テーマ）の運用は automedia の範囲外。運用前提 にあるとおり、テーマ管理は各 spin-dd/<key>-hubspot-theme リポと Wiki で実施されている。

対象 HubSpot アカウント

運用前提 にある 8 サイト のうち、SNS 運用を希望する顧客社の HubSpot ポータルを対象とする。MVP では馬頭ゴルフ（HubSpot ポータル: 243366509）。

API トークン（HubSpot Private App Token 等）の SoT は GitHub Actions Secrets。人間用のログイン / パスワードは Backlog Wiki TTRTAGSPIN/Hubspot を SoT とする（詳細）。本リポにはどちらの生値もコピーしない。

想定 API スコープ

  • Contacts API: 会員情報の取得・タグ同期
  • Lists API: セグメント取得
  • Marketing API（必要なら）: メール配信のトリガ
  • 認証: HubSpot Service Key（2026-02 Public Beta、Private App の後継）を テナント（HubSpot ポータル）ごとに 1 つ発行。Webhook を使う場合のみ Private App を 併用 する（Service Key では Webhook 認証不可）

Service Key 発行・カスタムプロパティ・Custom Activity の具体手順は チャネル オンボーディング - 4. HubSpot に集約。本ドキュメントは連携の意図・運用方針を扱う。

エンゲージメント記録方式（プラン依存・両モード両立）

SNS の配信・反応をどう HubSpot に残すかは、テナントの HubSpot プランによって 2 通り ある。テーマリポは .automedia/project.yml > hubspot.engagement_record_mode でどちらかを宣言し、automedia-hubspot SKILL の record_engagement モードが実装を切り替える:

engagement_record_mode 何で記録 プラン要件 想定テナント per-event 詳細の置き場
timeline_event Custom Activity（Timeline Event） Professional 以上 bato（Pro+ 想定） contact timeline 上に時系列で残る
contact_property contact カスタムプロパティ（sns_last_engaged_at / sns_first_engaged_at / sns_sources） Starter 以下でも可 spindd（Starter） Backlog 課題コメント側に書き戻し

設計判断:

  • automedia は 複数テナントをホストする汎用基盤なので、Pro+ 想定 (timeline_event) を base 設計として残す。bato 等のホスト先で Custom Activity timeline がリードスコアリングや顧客視点での履歴確認に活きる
  • spindd の HubSpot は Starter プランで Custom Activity 不可。そのため spindd では contact_property モードを採用し、per-event 詳細は Backlog コメントが SoT になる役割分担
  • どちらのモードも automedia-hubspot SKILL の I/F は共通（record_engagement 呼び出し）。実装は engagement_record_mode を見て Timeline API か Contact PATCH を選ぶ
  • Pro+ にアップグレードした際は engagement_record_mode: contact_property → timeline_event の 1 行切替 で済む。過去分は contact プロパティに残ったまま失われない

具体手順は チャネル オンボーディング §4 エンゲージメント記録方式 を参照。スキル実装は automedia-hubspot/SKILL.md の record_engagement モード。

「メイト会員」のようなサイト固有のロイヤリティプログラムは、HubSpot のカスタムプロパティとして実装されている可能性が高い。実体は対象サイトごとに確認が必要。

メイト会員 ↔ LINE タグ整合

LINE 運用案 7（02-line-pptx-summary）で「メイト会員かどうか」のアンケート→タグがある。HubSpot 側にもメイト会員フラグがあるなら、両者を同期する。

同期方針（案）:

  1. HubSpot を SoT として、is_mate_member を automedia 経由で LINE タグに反映
  2. LINE 側のアンケート回答も automedia 経由で HubSpot のコンタクトプロパティに書き戻す
  3. 競合は HubSpot 優先（顧客 DB が原本）

データ授受

sequenceDiagram
    participant HS as 顧客 HubSpot ポータル
    participant HA as HubSpot Adapter
    participant DB as automedia DB
    participant LA as LINE Adapter
    participant LINE

    HS-->>HA: コンタクト更新 Webhook
    HA->>DB: audience_tags 更新
    DB->>LA: タグ反映ジョブ
    LA->>LINE: ナローキャスト用オーディエンス更新

    LINE-->>LA: アンケート回答
    LA->>DB: audience_tags 追加
    DB->>HA: 書き戻しジョブ
    HA->>HS: コンタクトプロパティ更新

認証

  • HubSpot Service Key（hsk- プレフィクス）を GH Actions Secrets に格納（サイトごとに 1 トークン）。発行手順・スコープ・ローテーション運用は チャネル オンボーディング に集約
  • レート制限を Adapter 側で吸収（HubSpot は API 種別ごとにレート制限が異なる）
  • トークン期限・スコープ変更の通知を可観測性ダッシュボードに
  • MCP 経由（https://mcp.hubspot.com/anthropic）は運用者がアドホックに HubSpot を確認する補助線として併用可。automedia の本番経路は Service Key + REST API のみで構成する

既存運用との分担

関心事 担当
HubSpot テーマ（HubL / CSS / JS） spin-dd エンジニア × 各テーマリポ
HubSpot ページ・モジュール HubSpot 上で手動運用 + テーマリポと整合
HubSpot コンタクト同期（SNS タグ） automedia
HubSpot Marketing Email 配信 現状 HubSpot 手動、将来 automedia 経由を検討
ドメイン / SSL spin-dd インフラ（Wiki Hubspot/SSL）

未決

  • アンケート回答の書き戻し可否（顧客社の HubSpot 運用ポリシー次第）
  • どの List をオーディエンスソースとして採用するか（サイトごとに異なる）
  • HubSpot Marketing Email 配信を automedia 経由に統合するか