> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timothe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot メールとの連携

> HubSpot から配信するメールに Turnint AI のリンクを埋め込み、ユーザー情報を引き継いでエージェント体験へ誘導する方法

HubSpot Marketing Hub / Sales Hub から配信するメールに Turnint AI のリンクを差し込み、ユーザー情報（メールアドレス、会社名、HubSpot Contact ID など）を URL の query parameter として引き継ぐことで、ゲートをスキップしたパーソナライズされたエージェント体験へ誘導できます。

<Info>
  HubSpot のランディングページ（フォーム送信）からの誘導は別ドキュメントで解説しています。本ページはメール配信からの導線に特化した内容です。あわせて [HubSpot ランディングページとの連携](/ja/get-started/onboarding/hubspot-landing-page) もご参照ください。
</Info>

## フロー

```mermaid theme={null}
flowchart LR
    A["HubSpotメール配信"] --> B["ユーザーがリンクをクリック"]
    B --> C["?email=..."]
    C --> D["Turnint AIエージェントページ"]
    D --> E["ユーザー情報を自動取得"]
```

1. HubSpot のメールに、パーソナライゼーショントークンを含む Turnint AI の URL を埋め込む
2. 配信時に `{{contact.email}}` などのトークンが連絡先ごとの値に展開される
3. ユーザーがリンクをクリックすると、Turnint AI のポータルが query parameter を読み取り、ゲートのフォームフィールドと一致する値を事前入力する
4. ゲートのフォームフィールドと一致するパラメータがあれば入力済み扱いとなり、ゲートの設定で `自動確認` オプションがアクティブの場合はゲートをスキップして自動でセッションを開始する

## 仕組み

### HubSpot のパーソナライゼーショントークン

HubSpot のメールでは、本文や URL に連絡先プロパティを変数として埋め込めます。代表的なトークンは以下です。

| トークン                       | 値                      |
| -------------------------- | ---------------------- |
| `{{contact.email}}`        | 連絡先のメールアドレス            |
| `{{contact.firstname}}`    | 名                      |
| `{{contact.lastname}}`     | 姓                      |
| `{{contact.company}}`      | 会社名                    |
| `{{contact.hs_object_id}}` | HubSpot Contact ID（数値） |
| `{{contact.<内部名>}}`        | カスタムプロパティ              |

<Info>
  HubSpot のカスタムプロパティを参照する場合は、ラベルではなくプロパティ設定画面の **Internal name**（内部名）を指定してください。
</Info>

<Info>
  URL の query 文字列内に変数を含めた場合、HubSpot は配信時に自動で URL エンコードを行います。`encodeURIComponent` 相当の処理を二重に施す必要はありません。
</Info>

### Turnint AI 側での受け取り

Turnint AI のポータル（`xxx.turnint.site`）は、URL の query parameter のうち、ゲートのフォームフィールドのキーと一致するパラメータを入力済みとして扱います。ゲートに含まれない query parameter はセッションのユーザーデータには保持されません。追加のコンテキストを保持したい場合は、ゲートフィールドとして定義するか、埋め込み時の `data-turnint-context` を使用してください。

詳細な内部仕様（ゲートとの一致ルール、`自動確認` の挙動）は [HubSpot ランディングページとの連携 ＞ Turnint AI 側の設定](/ja/get-started/onboarding/hubspot-landing-page#turnint-ai-側の設定) を参照してください。

## 推奨パラメータ

メールから誘導する URL には、以下のパラメータを推奨します。

| パラメータ名      | HubSpot 変数式                | 必須 / 任意 | 説明                                                     |
| ----------- | -------------------------- | ------- | ------------------------------------------------------ |
| `email`     | `{{contact.email}}`        | 必須      | 見込み顧客の identity key。Turnint AI のバックエンドで人物の突合に使用します     |
| `hubspotid` | `{{contact.hs_object_id}}` | 任意      | HubSpot Contact ID。セッションで利用したい場合は、同名のゲートフィールドを作成してください |
| `firstname` | `{{contact.firstname}}`    | 任意      | パーソナライズ表示／ゲート事前入力                                      |
| `lastname`  | `{{contact.lastname}}`     | 任意      | 同上                                                     |
| `company`   | `{{contact.company}}`      | 任意      | 会社名フィールドの事前入力                                          |
| `<カスタム>`    | `{{contact.<内部名>}}`        | 任意      | ゲートのフィールドキーと一致させると事前入力扱いになります                          |

<Note>
  パラメータ名は、HubSpot のフィールド内部名と Turnint AI のゲートフィールドキーを揃えてください。
</Note>

<Note>
  HubSpot Contact ID は `hubspotid` を推奨します。既存の URL で `hubspot_id`、`hs_contact_id`、`hscontactid` を使っている場合も、Turnint AI 側では `hubspotid` として扱われます。
</Note>

## URL 組み立て例

### 基本形（プレーンテキストリンク）

メール本文に貼り付ける URL の例です。HubSpot がトークンを連絡先ごとに展開して配信します。

```
https://xxx.turnint.site/decks/xxx?email={{contact.email}}&firstname={{contact.firstname}}&company={{contact.company}}&hubspotid={{contact.hs_object_id}}
```

配信後、実際にユーザーの元へ届くリンクは次のようになります（HubSpot が自動で URL エンコード）。

```
https://xxx.turnint.site/decks/xxx?email=user%40example.com&firstname=%E5%A4%AA%E9%83%8E&company=%E6%A0%AA%E5%BC%8F%E4%BC%9A%E7%A4%BEABC&hubspotid=12345
# email = user@example.com, firstname = 太郎, company = 株式会社ABC, hubspotid = 12345
```

### HTML での記述

HubSpot のメールエディタで「リンクを挿入」する操作で URL を貼り付ければ、エディタ側でアンパサンド等のエスケープが適切に処理されます。HTML ソースを直接編集する場合のみ、`&` を `&amp;` と書いてください。

```html theme={null}
<a href="https://xxx.turnint.site/decks/xxx?email={{contact.email}}&amp;hubspotid={{contact.hs_object_id}}&amp;autoconfirm=true">
  AI コンシェルジュに相談する
</a>
```

### 変数が空のときのフォールバック

HubSpot のパーソナライゼーショントークンには既定値を指定できます。

```
{{contact.firstname|default:"お客様"}}
```

ただし `email` のような identity key には既定値を設定しないでください。別人として識別されると本末転倒です。**`email` プロパティが未設定の連絡先には、本フローのリンクを送らない運用を推奨**します（HubSpot のリスト条件で除外できます）。

`hubspotid`（`{{contact.hs_object_id}}`）は連絡先に常に存在するため既定値は不要です。

## HubSpot メールへの組み込み手順

### マーケティングメール（Marketing Hub）の場合

1. メールエディタで本文を開き、「リンクを挿入」ダイアログを開く
2. URL 入力欄に[基本形](#基本形プレーンテキストリンク)の URL をそのまま貼り付ける
3. 必要に応じて「パーソナライズ」ボタンから `{{contact.email}}` などのトークンを挿入する
4. プレビュー機能で実際の連絡先を選び、展開後の URL が想定どおりかを確認する
5. テスト送信を自分宛に行い、リンクをクリックして `自動確認` によるゲートスキップ動作を検証する

### 1:1 セールスメール / Sequences の場合

Sales Hub の **Sequences** **Snippet** **Template** でも同じ変数式が利用できます。Sequences の自動配信では送信者ごとにトラッキング設定や差出人情報が異なる場合があるため、配信前にプレビューで URL を確認してください。

<Note>
  Connected Inbox 経由（Gmail / Outlook 個別送信）では、メールクライアント側のリンク短縮や安全リンク機能（例: Microsoft Defender Safe Links）でリンクがラップされる場合があります。受信側環境を考慮した検証を推奨します。
</Note>

### CTA ボタンの場合

HubSpot CTA の URL に変数を埋め込む場合、CTA 編集画面の **URL リダイレクト** モードで上記 URL を設定します。ただし CTA はメール外（ランディングページなど）でも再利用される可能性があり、その場合は `email={{contact.email}}` の値が空になります。**メール用とランディングページ用で CTA を分けるか、メール本文の通常リンクとして実装することを推奨**します。

## Turnint AI 側の設定

### ゲートのフィールドキー

ダッシュボードでエージェントのゲートを設定する際、query parameter で渡したいフィールドのキーを HubSpot のプロパティ内部名と揃えてください。具体的な手順は [HubSpot ランディングページとの連携 ＞ ゲートの設定](/ja/get-started/onboarding/hubspot-landing-page#ゲートの設定) を参照してください。

## ハマりやすい注意点

* **二重 URL エンコード禁止** — HubSpot は配信時に自動でエンコードを適用します。変数を `encodeURIComponent` で囲ったり、`%` を手書きで含めないでください
* **空文字列は prefill 失敗** — `email` 等が連絡先に未設定の場合、`?email=` のように空で展開されゲートのバリデーションを通らず、`autoconfirm` も発動しません。配信前に HubSpot のリスト条件で除外してください
* **クリックトラッキング有効時のリダイレクト** — HubSpot のメールクリックトラッキングが有効な場合、リンクは中間 URL（`https://[portal].hs-sites.com/...` 等）を経由します。最終的に Turnint AI には正しく query parameter が渡りますが、メールクライアントのリンクプレビューでは中間 URL が見える点に留意してください
* **Sandbox / 本番ポータルの差** — `hs_object_id` などの Contact ID は HubSpot ポータル単位で別空間です。Sandbox でテストした URL を本番運用で再利用しないでください
* **メールクライアント側のリンク改変** — Gmail / Outlook の安全リンクラッピングや、社内プロキシによる URL 改変で query parameter が消失したり付加情報が混ざる可能性があります。ユーザー環境で再現する場合は環境固有の挙動として確認してください
* **配信前のプレビュー必須** — 連絡先ごとに展開された URL を HubSpot のプレビューで必ず目視し、想定どおりの値が入っているか確認してください

## セキュリティ配慮

### email を URL に含めることの設計上の整理

Turnint AI では、ユーザー識別のために `email` を URL の query parameter として渡すことを推奨しています。一見すると平文の連絡先情報を URL に載せることに抵抗を感じるかもしれませんが、この設計は次の前提に基づいています。

* HubSpot からのメール配信は TLS で行われ、HubSpot のクリックトラッキングを経由する場合のリダイレクトサーバーも HubSpot の信頼境界内にあります
* Turnint AI のバックエンドでは、`email` は人物 / HubSpot コンタクトとの突合に用いるための受け渡しが必要です（識別に使われるキーは `name` `email` `phone` `company` `role` の 5 種に限定されています）

### Referrer-Policy と外部リンクの取り扱い

Turnint AI のポータル URL には `email` などが含まれるため、ポータルページから外部サイトへ遷移する際、Referer ヘッダ経由でこれらの値が漏洩する懸念があります。エージェントセッション中はアウトバウンドリンクを設けない設計が前提のため通常は問題になりませんが、エージェントの応答に外部リンクを含める設計を採用する場合は、ポータルの HTML レスポンスに `Referrer-Policy: strict-origin-when-cross-origin` を最低ライン、より厳格な `strict-origin` または `same-origin` を望ましい設定として検討してください。

### クリックトラッキングと URL 改変

HubSpot のメールクリックトラッキングが有効な場合、リンクは中間 URL を経由します。Turnint AI への最終的な query parameter は保持されますが、社内プロキシやメールセキュリティゲートウェイによる URL 改変で、リンクが破壊されたり余分なパラメータが追加されるケースが稀にあります。重要な配信の前にはテストアカウントで実配信検証を行ってください。

## 関連ドキュメント

* [HubSpot CRM 連携](/ja/integrations/crm.hubspot) — セッションデータの HubSpot コンタクトへの自動同期
* [HubSpot トラッキング連携](/ja/integrations/analytics.hubspot) — セッションイベントの HubSpot カスタム行動イベントとしての送信
* [トラッキングパラメータの自動保持](/ja/integrations/tracking-params) — UTM パラメータや広告クリック ID の自動引き継ぎ
* [ウェブフック連携](/ja/integrations/webhook) — セッションデータの外部システムへのリアルタイム同期