> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/authorization-integration/contacts.md). # 連絡先（Contact）の紹介と連携 ## コンタクトとは？ コンタクト（Contact）は「AI アシスタントと対話する**エンドユーザー**」を表します。企業が自社システムのユーザーを MaiAgent のコンタクトに紐付けることで、AI は「誰が質問しているか」を識別できるようになります。これにより、**その人**の対話履歴と権限設定を正しく参照でき、他のユーザーのものと混同することがありません。 コンタクトは MaiAgent のアカウントを必要としません（これが[メンバー／ロール](/tech/ja/authorization-integration/role-vs-contact.md)との最大の違いです）。ユーザーがその存在を意識することもありません——コンタクトは、お客様のシステムと MaiAgent の間の ID マッピングです。 {% tabs %} {% tab title="企業が外部の消費者向けに連携" %}
{% endtab %} {% tab title="企業が社内従業員向けに連携" %}
{% endtab %} {% endtabs %} ### コンタクトに紐付けられる情報 | データ | 用途 | 詳細説明 | | ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | 基本情報（`name`、`email`、`avatar`） | 管理画面のコンタクト一覧と対話履歴に表示されます | 本ページ下部の API 説明 | | カスタム属性（`metadata`） | 部署、会員ランクなどの背景情報。**AI が読み取り、回答に反映します** | [コンタクト ID 同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md#sync-contact-profile) | | クエリメタデータ（`query_metadata`） | 該当ユーザーが検索可能なナレッジベース／ドキュメント／タグの範囲を制限します | [ナレッジ管理権限（Query Metadata）](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) | | MCP／API ツール認証情報 | AI が**該当ユーザーの ID と権限で**外部ツールを呼び出せるようにします | [コンタクト ID 同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md) | | 対話履歴 | デバイスをまたいで対話を継続できます | フロントエンドで `contactId` を渡すだけで有効になります | ## コンタクトの作成・同期方法は 3 通り | 方法 | 適したケース | 説明 | | ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ID 同期 API**（`setup-contact-credentials`） | ユーザーログイン時の同期、ツール認証情報のバインド、既存システムからの一括補完作成 | 冪等（同一 `sourceId` で重複作成されません）、API Key 不要。Web Chat フロントエンドの `auth` が自動呼び出しするバージョンも含まれます。**ほとんどの連携シナリオではこの方法を推奨します**。詳細は[コンタクト ID 同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md)をご覧ください | | **コンタクト API**（`POST /api/v1/contacts/`） | バックエンドでコンタクトのライフサイクルを完全に制御したい場合、作成時に query\_metadata を設定する必要がある場合 | API Key が必要です。更新には `PATCH /api/v1/contacts/{contact_id}/` を使用します（送信されたフィールドのみ更新されます）。スキーマは [API ドキュメント-コンタクト](https://docs.maiagent.ai/api/lian-luo-ren)をご参照ください | | **一括インポート**（Excel） | 既存システムとの初回連携時に、大量のユーザーを一括で補完作成する場合 | 上限 10,000 行。query\_metadata と API ツール認証情報を同時に設定できます。[下記の説明](#bulk-import)をご覧ください | | **管理画面（GUI）** | 少量のコンタクトを手動で管理する場合 | [下記の操作説明](#tu-xing-hua-jie-mian-jian-li-lian-luo-ren)をご覧ください | 4 通りの方法で作成されるコンタクトは同一のものであり、併用が可能です（例：初回連携時は一括インポート、日常のログイン時は ID 同期 API を使用）。 ## 連携フロー ```mermaid sequenceDiagram participant CU as ユーザー participant ES as 企業システム participant MA as MaiAgent CU ->> ES: Web サイトを開きログイン（企業システムの user ID を保持） ES ->> ES: 会員情報を確認：対応する Contact ID は存在するか？ alt 対応なし ES ->> MA: コンタクトを作成（ID 同期 API または POST /api/v1/contacts/） MA -->> ES: contactId を返却 ES ->> ES: contactId を会員情報テーブルに保存 end ES ->> CU: Web Chat 埋め込みコードを読み込み（config に contactId を設定） CU ->> MA: Web Chat が該当コンタクトの ID で初期化 MA -->> CU: 該当ユーザーの対話履歴と対応する権限を表示 ``` 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](/tech/ja/api-integration/web-chat-sdk.md#identify-users) をご覧ください {% hint style="info" %} 「ユーザーが企業システムにログインする際に、コンタクトを同期作成し Token 認証情報を更新する」シナリオ（例：AI がユーザーの権限で MCP ツールを呼び出す場合）については、[コンタクト ID 同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md)をご参照ください。1 回の呼び出しでコンタクトの作成と認証情報のバインドを同時に完了できます。 {% endhint %} ## コンタクトの一括インポート（Excel） 既存システムとの初回連携時に、Excel で大量のコンタクトを一括作成（または更新）できます： {% stepper %} {% step %} ### テンプレートのダウンロード `GET /api/v1/contacts/bulk-import-template/` で Excel テンプレート（ヘッダー行とサンプル行を含む）をダウンロードします。 {% endstep %} {% step %} ### データの入力 | フィールド | 必須 | 説明 | | --------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Name(required)` | ✅ | コンタクトの表示名 | | `Email(required)` | ✅ | マッチングキーの一つ（大文字・小文字を区別しません） | | `Phone Number` | | 電話番号 | | `Source ID(required)` | ✅ | 企業システムのユーザー識別コード、マッチングキーの一つ。推測困難な値を使用してください（[ID 同期 API のセキュリティに関する注意事項](/tech/ja/authorization-integration/contact-credentials-sync.md#request-body)と同様） | | `Query Metadata` | | JSON オブジェクト。コンタクトのナレッジ検索範囲に書き込まれます。**空白セル＝既存の値を保持**。フォーマットは [JSON フォーマットガイド](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)をご参照ください | | `API Credentials` | | JSON 配列 `[{"tool": "<ツール ID>", "headers": {...}}]`。API ツール認証情報をバインドします。空白＝既存の認証情報を保持 | | {% endstep %} | | | {% step %} ### アップロードしてインポート `POST /api/v1/contacts/bulk-import/`（`multipart/form-data`、`Authorization: Api-Key` 認証、コンタクト API と同様）： * `file`：入力済みの `.xlsx`（上限 10 MB、10,000 行） * `inboxes`：受信トレイの UUID リスト——**インポートされる各コンタクトの受信トレイセットは、このリストで丸ごと置き換えられます**。その後 Web Chat のログイン同期を行う場合は、対応する Web Chat の受信トレイが含まれていることを確認してください レスポンス：`{ "created": N, "updated": M }` {% endstep %} {% endstepper %} インポートのマッチングと更新ルール： * （`Source ID`、`Email`）をキーとして upsert を実行します。既存のコンタクトに一致した場合は氏名／電話番号／Query Metadata を更新し（空白セルは変更しません）、一致しなかった場合は新規作成します * `API Credentials` は（コンタクト、ツール）をキーとして upsert を実行します。ファイルに記載されていないツールの認証情報は影響を受けません * 全件が同一トランザクション内で処理されます。いずれかの行にフォーマットエラー（フィールド名の不一致、不正な JSON など）がある場合、全件が書き込まれず、エラーメッセージに行番号が表示されます {% hint style="info" %} インポートでは対応関係と属性のみが作成されます。ユーザーの Token 認証情報は、ログインフローの [ID 同期 API](/tech/ja/authorization-integration/contact-credentials-sync.md) によって毎回のログイン時に更新されます。 {% endhint %} ## GUI でのコンタクト作成 1. コンタクト管理画面に移動します
2. コンタクトを追加をクリックします

コンタクトページ

クリックすると以下のページが表示されます：

コンタクト編集ページ

コンタクト名を入力し、対話プラットフォームを指定すると作成できます。作成後、コピーボタンをクリックしてコンタクト ID（Web Chat の初期化パラメータ `contactId`）を取得できます。
*** {% hint style="info" %} コンタクトに設定された ID 情報は、クエリ時に対応する `query_metadata` の条件の組み合わせを生成するために使用されます。 [**👉 Query Metadata について詳しく見る**](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) {% endhint %} ## 実装に関する推奨事項 1. **会員情報テーブルに対応フィールドを追加します**（例：`maiagent_contact_id`、UUID、nullable）。作成／更新日時とともに記録し、企業の user ID と Contact ID の対応関係を追跡可能にします 2. **冪等性を実装します**：作成前に対応関係を確認するか、ID 同期 API を直接使用してください（`sourceId` による冪等性があり、再実行しても重複コンタクトは作成されません） 3. **API 呼び出しログを記録します**。対応関係の異常を調査する際に役立ちます 4. **非同期呼び出し**：コンタクト関連の API はログインフローの他のリクエストと並行して実行します。失敗してもユーザーのログインをブロックせず、次回のログイン時にリトライします --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/ja/authorization-integration/contacts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.