連絡先 (Contact) の紹介と連携

コンタクト（Contact）の概要と連携 — sourceId による自社システムのユーザーとエンドユーザーの紐付け、コンタクトの作成・同期の4つの方法、Excel 一括インポート、実装上の推奨事項を説明します。

コンタクトとは？

コンタクト（Contact）は「Agent と対話するエンドユーザー」を表し、MaiAgent アカウントは不要です。企業が自社システムのユーザーを sourceId でコンタクトに紐付けると、AI は「誰からの質問か」を認識し、そのユーザーの対話履歴と権限設定を正しく参照できます。コンタクトの概念、匿名コンタクトと非匿名コンタクトの違い、管理画面での操作については、ユーザーマニュアルのコンタクトを参照してください。メンバー・ロールとの違いはロールとコンタクトの違いを参照してください。本ページでは API 連携のみを説明します。

コンタクトに紐付けられる情報

データ	用途	詳細
基本情報（name、email、avatar）	管理画面のコンタクト一覧と対話記録に表示します	本ページ下部の API 説明
カスタム属性（metadata）	部署や会員ランクなどの背景情報です。AI が読み取り、回答に反映します	コンタクトの ID 同期と Token 更新
クエリメタデータ（query_metadata）	ユーザーが検索できるナレッジベース・ドキュメント・タグの範囲を制限します	ナレッジ管理権限（Query Metadata）
MCP／API ツールの認証情報	AI がそのユーザーの ID と権限で外部ツールを呼び出せます	コンタクトの ID 同期と Token 更新
対話履歴	デバイスをまたいで対話を継続できます	フロントエンドで contactId を渡すと有効になります

コンタクトの作成・同期の4つの方法

方法	適した用途	説明
ID 同期 API（setup-contact-credentials）	ログイン時の同期、ツール認証情報の紐付け、既存システムで不足しているコンタクトの一括作成	冪等性があります（同じ sourceId では重複作成されません）。API Key は不要です。Web Chat フロントエンドの auth が自動呼び出しするバージョンもあります。ほとんどの連携シナリオでこの方法を推奨します。詳細はコンタクトの ID 同期と Token 更新を参照してください
コンタクト API（POST /api/v1/contacts/）	バックエンドでコンタクトのライフサイクルを完全に管理する場合、作成時に query_metadata を設定する場合	API Key が必要です。更新には PATCH /api/v1/contacts/{contact_id}/ を使用します（渡したフィールドのみ更新します）。スキーマは API ドキュメント — コンタクトを参照してください
一括インポート（Excel）	既存システムとの初回連携で、大量のユーザーをまとめて作成する場合	上限は 10,000 行です。query_metadata と API ツールの認証情報も同時に設定できます。下記の説明を参照してください
管理画面のグラフィカルインターフェース	少数のコンタクトを手動で管理する場合	下記の操作説明を参照してください

4つの方法で作成するコンタクトは同じ種類であり、併用できます（例：初回連携では一括インポート、日常のログインでは ID 同期を使用します）。

コンタクト API のリクエストフィールド

POST /api/v1/contacts/ のリクエストボディ（camelCase と snake_case の両方に対応します）：

フィールド	必須	説明
name	はい	表示名です。最大 255 文字です
inboxes	はい（2つのうちいずれか）	[{"id": "<対話プラットフォーム ID>"}]。コンタクトが所属する対話プラットフォームで、キーの組織に所属している必要があります。旧フィールド inbox（単一の {"id": …}）も引き続き使用できます。両方を渡した場合は inboxes を優先し、どちらも渡さない場合は 400 を返します
sourceId	いいえ	自社システムのユーザー ID です。最大 255 文字です。同じ対話プラットフォーム内で重複できず、重複すると 400 を返します。省略した場合、そのコンタクトは contactId でのみ識別できます
email、phoneNumber、avatar	いいえ	基本情報です。avatar には完全な URL またはプラットフォームの相対パスを指定できます
metadata	いいえ	カスタム属性です。キーと値の配列形式はコンタクトの ID 同期と Token 更新を参照してください
queryMetadata	いいえ	ナレッジ検索範囲です。形式は Query Metadataを参照してください

最小の有効なリクエストは {"name": "山田太郎", "inboxes": [{"id": "<対話プラットフォーム ID>"}]} です。201 レスポンスには完全なコンタクトオブジェクトが含まれます。mcpCredentials、apiCredentials、contactConnectors、tags は読み取り専用フィールドです。認証情報の書き込みには、それぞれ専用のエンドポイントを使用してください。

コンタクトの所属と可視範囲

コンタクトは組織に所属し、作成に使用した API キーには所属しません。同じ組織内のキーは、紐付けられたメンバーがコンタクト権限を持っていれば、同じコンタクトの取得・更新・削除ができます。キーをローテーションしても contactId と sourceId は引き続き使用できます。他の組織からは一切参照できません（404 を返します）。

メンバーはログインするとコンタクトになりますか？

はい。ただし、ログイン時ではありません。メンバー（SSO でログインするメンバーを含みます）が MaiGPT や管理画面のテスト対話などでプラットフォームアカウントを使って対話を開始すると、その対話プラットフォーム上に、sourceId がそのメンバーのユーザー ID と一致し、アカウントに紐付いたコンタクトが作成（または再利用）されます。API キーで completions を呼び出し、sender を渡さない場合も同じルールです（message.sender 省略時の IDを参照してください）。そのため、このコンタクトに設定された MCP／API ツールの認証情報と queryMetadata は、メンバー自身の対話でも有効です。コンタクトは対話プラットフォームごとに作成されるため、同じメンバーでもプラットフォームが異なれば別のコンタクトになります。メンバーのロール権限とコンタクト設定は独立しています。ロール（Role）とコンタクト（Contact）の違いを参照してください。

連携フロー

3つのステップで進めます：

1. 紐付けを確認します：企業システムの user ID で会員情報を検索し、MaiAgent の contact_id がすでにあるか確認します

2. 作成または更新します：なければ作成し、contact_id を保存します。ユーザーの名前／Email や権限が変更された場合はコンタクトを同期更新（PATCH /api/v1/contacts/{contact_id}/）し、その後の対話でパーソナライズされた情報と権限が正しく反映されるようにします

3. Web Chat を初期化します：フロントエンドの config に contactId を含めます。Web Chat の埋め込みと SDKを参照してください

「ユーザーが企業システムにログインする際に、コンタクトの作成と Token 認証情報の更新を同期する」場合（例：AI がユーザーの権限で MCP ツールを呼び出す場合）は、コンタクトの ID 同期と Token 更新を参照してください。1回の呼び出しでコンタクトの作成と認証情報の紐付けを完了できます。

コンタクトの一括インポート（Excel）

既存システムとの初回連携では、Excel で大量のコンタクトをまとめて作成（または更新）できます：

1

テンプレートをダウンロードします

GET /api/v1/contacts/bulk-import-template/ で Excel テンプレート（ヘッダー行とサンプル行を含みます）をダウンロードします。

2

データを入力します

フィールド	必須	説明
Name(required)	✅	コンタクトの表示名です
Email(required)	✅	照合キーの1つです（大文字・小文字を区別しません）
Phone Number		電話番号です
Source ID(required)	✅	企業システムのユーザー識別子で、照合キーの1つです。推測できない値を使用してください（ID 同期 API のセキュリティ上の注意と同様です）
Query Metadata		JSON オブジェクトで、コンタクトのナレッジ検索範囲を設定します。空白セルは既存の値を保持します。形式は JSON 形式ガイドを参照してください
API Credentials		JSON 配列 [{"tool": "<ツール ID>", "headers": {...}}] で API ツールの認証情報を紐付けます。空白の場合は既存の認証情報を保持します

3

アップロードしてインポートします

POST /api/v1/contacts/bulk-import/（multipart/form-data、Authorization: Api-Key 認証を使用し、コンタクト API と同じです）：

• file：入力済みの .xlsx ファイルです（上限は 10 MB、10,000 行です）

• inboxes：受信トレイ UUID のリストです（1つ以上必要です）。後で Web Chat のログイン同期を使用する場合は、対応する Web Chat の受信トレイを含めてください

• inboxMode（任意、デフォルトは replace）：replace では、インポートした各コンタクトの受信トレイ集合を inboxes ですべて置き換えます。merge では inboxes のみを追加し、既存の受信トレイを保持します

• dryRun（任意、デフォルトは false）：true ではファイルの解析と検証のみを行い、作成・更新予定の件数を返します。データは書き込みません（200 を返します。実際のインポートは 201 を返します）

レスポンス：{ "created": N, "updated": M, "dryRun": false }

まず dryRun=true で送信し、件数が想定どおりであることを確認してから、実際のインポートを行うことを推奨します。

インポート時の照合・更新ルールは次のとおりです：

• （Source ID、Email）をキーとして upsert します。既存のコンタクトに一致した場合は名前／電話番号／Query Metadata を更新します（空白セルは変更しません）。一致しなければ作成します

• API Credentials は（コンタクト、ツール）をキーとして upsert します。ファイルに記載されていないツールの認証情報は変更しません

• バッチ全体を1つのトランザクションで処理します。いずれかの行に形式エラー（フィールド名の不一致、不正な JSON など）がある場合は、バッチ全体を書き込みません。エラーメッセージには行番号を表示します

インポートは紐付けと属性の設定のみを行います。ユーザーの Token 認証情報は、引き続きログインフローの ID 同期 API でログインのたびに更新します。

グラフィカルインターフェースでのコンタクト作成

少数のコンタクトは、管理画面で手動追加するか、Excel で一括インポートできます（プレビューに対応します）。手順はユーザーマニュアルのコンタクトの追加とコンタクトの一括インポートを参照してください。作成後、コンタクト一覧からコンタクト ID をコピーできます。これが Web Chat 初期化パラメータの contactId です。

コンタクトに設定された ID 情報は、クエリ時に対応する query_metadata 条件の組み合わせを生成するために使用します。

👉 Query Metadata の詳細

実装上の推奨事項

1. 会員テーブルに紐付け用フィールドを追加します（例：maiagent_contact_id、nullable な UUID）。作成・更新日時も記録し、企業の user ID ↔ Contact ID の紐付けを追跡できるようにします

2. 冪等性を実装します：作成前に紐付けを確認するか、ID 同期 API を直接使用します（sourceId は冪等で、再実行しても重複コンタクトは作成されません）

3. API 呼び出しログを記録します：紐付けの異常を調査しやすくなります

4. 非同期で呼び出します：コンタクト関連 API をログインフローの他のリクエストと並行して実行します。失敗してもログインを妨げず、次回ログイン時に再試行します