> 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/serve/contacts.md). # 連絡先（Contact）の概要と連携 コンタクト（Contact）の概要と連携 — sourceId による自社システムのユーザーとエンドユーザーの紐付け、コンタクトの作成・同期の4つの方法、Excel 一括インポート、実装上の推奨事項を説明します。 ## コンタクトとは？ コンタクト（Contact）は「Agent と対話する**エンドユーザー**」を表し、MaiAgent アカウントは不要です。企業が自社システムのユーザーを `sourceId` でコンタクトに紐付けると、AI は「誰からの質問か」を認識し、そのユーザーの対話履歴と権限設定を正しく参照できます。コンタクトの概念、匿名コンタクトと非匿名コンタクトの違い、管理画面での操作については、ユーザーマニュアルの[コンタクト](https://docs.maiagent.ai/serve/daily-operations/contact)を参照してください。メンバー・ロールとの違いは[ロールとコンタクトの違い](https://docs.maiagent.ai/org/roles/contact-role-comparison)を参照してください。本ページでは API 連携のみを説明します。 ### コンタクトに紐付けられる情報 | データ | 用途 | 詳細 | | ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 基本情報（`name`、`email`、`avatar`） | 管理画面のコンタクト一覧と対話記録に表示します | 本ページ下部の API 説明 | | カスタム属性（`metadata`） | 部署や会員ランクなどの背景情報です。**AI が読み取り、回答に反映します** | [コンタクトの ID 同期と Token 更新](/tech/ja/serve/contacts/contact-credentials-sync.md#sync-contact-profile) | | クエリメタデータ（`query_metadata`） | ユーザーが検索できるナレッジベース・ドキュメント・タグの範囲を制限します | [ナレッジ管理権限（Query Metadata）](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) | | MCP／API ツールの認証情報 | AI が**そのユーザーの ID と権限**で外部ツールを呼び出せます | [コンタクトの ID 同期と Token 更新](/tech/ja/serve/contacts/contact-credentials-sync.md) | | 対話履歴 | デバイスをまたいで対話を継続できます | フロントエンドで `contactId` を渡すと有効になります | ## コンタクトの作成・同期の4つの方法 | 方法 | 適した用途 | 説明 | | ------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ID 同期 API**（`setup-contact-credentials`） | ログイン時の同期、ツール認証情報の紐付け、既存システムで不足しているコンタクトの一括作成 | 冪等性があります（同じ `sourceId` では重複作成されません）。API Key は不要です。Web Chat フロントエンドの `auth` が自動呼び出しするバージョンもあります。**ほとんどの連携シナリオでこの方法を推奨します**。詳細は[コンタクトの ID 同期と Token 更新](/tech/ja/serve/contacts/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/api-reference/lian-luo-ren)を参照してください | | **一括インポート**（Excel） | 既存システムとの初回連携で、大量のユーザーをまとめて作成する場合 | 上限は 10,000 行です。query\_metadata と API ツールの認証情報も同時に設定できます。[下記の説明](#bulk-import)を参照してください | | **管理画面のグラフィカルインターフェース** | 少数のコンタクトを手動で管理する場合 | [下記の操作説明](#tu-xing-hua-jie-mian-jian-li-lian-luo-ren)を参照してください | 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 更新](/tech/ja/serve/contacts/contact-credentials-sync.md#sync-contact-profile)を参照してください | | `queryMetadata` | いいえ | ナレッジ検索範囲です。形式は [Query Metadata](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)を参照してください | 最小の有効なリクエストは `{"name": "山田太郎", "inboxes": [{"id": "<対話プラットフォーム ID>"}]}` です。`201` レスポンスには完全なコンタクトオブジェクトが含まれます。`mcpCredentials`、`apiCredentials`、`contactConnectors`、`tags` は読み取り専用フィールドです。認証情報の書き込みには、それぞれ専用のエンドポイントを使用してください。 ### コンタクトの所属と可視範囲 コンタクトは**組織**に所属し、作成に使用した API キーには所属しません。同じ組織内のキーは、紐付けられたメンバーがコンタクト権限を持っていれば、同じコンタクトの取得・更新・削除ができます。キーをローテーションしても `contactId` と `sourceId` は引き続き使用できます。他の組織からは一切参照できません（`404` を返します）。 ### メンバーはログインするとコンタクトになりますか？ はい。ただし、ログイン時ではありません。メンバー（SSO でログインするメンバーを含みます）が MaiGPT や管理画面のテスト対話などでプラットフォームアカウントを使って対話を開始すると、その対話プラットフォーム上に、`sourceId` がそのメンバーのユーザー ID と一致し、アカウントに紐付いたコンタクトが作成（または再利用）されます。API キーで `completions` を呼び出し、`sender` を渡さない場合も同じルールです（[`message.sender` 省略時の ID](/tech/ja/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md#anonymous-sender)を参照してください）。そのため、このコンタクトに設定された MCP／API ツールの認証情報と `queryMetadata` は、メンバー自身の対話でも有効です。コンタクトは対話プラットフォームごとに作成されるため、同じメンバーでもプラットフォームが異なれば別のコンタクトになります。メンバーのロール権限とコンタクト設定は独立しています。[ロール（Role）とコンタクト（Contact）の違い](/tech/ja/serve/contacts/role-vs-contact.md)を参照してください。 ## 連携フロー ```mermaid sequenceDiagram participant CU as ユーザー participant ES as 企業システム participant MA as MaiAgent CU ->> ES: Web サイトを開いてログインします（企業システムの user ID を使用します） ES ->> ES: 会員情報を確認します：対応する Contact ID はありますか？ alt 対応する ID がありません 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 を初期化します 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/serve/web-chat-sdk.md#identify-users)を参照してください {% hint style="info" %} 「ユーザーが企業システムにログインする際に、コンタクトの作成と Token 認証情報の更新を同期する」場合（例：AI がユーザーの権限で MCP ツールを呼び出す場合）は、[コンタクトの ID 同期と Token 更新](/tech/ja/serve/contacts/contact-credentials-sync.md)を参照してください。1回の呼び出しでコンタクトの作成と認証情報の紐付けを完了できます。 {% endhint %} ## コンタクトの一括インポート（Excel） 既存システムとの初回連携では、Excel で大量のコンタクトをまとめて作成（または更新）できます： {% stepper %} {% step %} ### テンプレートをダウンロードします `GET /api/v1/contacts/bulk-import-template/` で Excel テンプレート（ヘッダー行とサンプル行を含みます）をダウンロードします。 {% endstep %} {% step %} ### データを入力します | フィールド | 必須 | 説明 | | --------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Name(required)` | ✅ | コンタクトの表示名です | | `Email(required)` | ✅ | 照合キーの1つです（大文字・小文字を区別しません） | | `Phone Number` | | 電話番号です | | `Source ID(required)` | ✅ | 企業システムのユーザー識別子で、照合キーの1つです。推測できない値を使用してください（[ID 同期 API のセキュリティ上の注意](/tech/ja/serve/contacts/contact-credentials-sync.md#request-body)と同様です） | | `Query Metadata` | | JSON オブジェクトで、コンタクトのナレッジ検索範囲を設定します。**空白セルは既存の値を保持します**。形式は [JSON 形式ガイド](/tech/ja/identity-and-access/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 のリストです（1つ以上必要です）。後で Web Chat のログイン同期を使用する場合は、対応する Web Chat の受信トレイを含めてください * `inboxMode`（任意、デフォルトは `replace`）：`replace` では、インポートした各コンタクトの受信トレイ集合を `inboxes` で**すべて置き換えます**。`merge` では `inboxes` のみを追加し、既存の受信トレイを保持します * `dryRun`（任意、デフォルトは `false`）：`true` ではファイルの解析と検証のみを行い、作成・更新予定の件数を返します。データは書き込みません（`200` を返します。実際のインポートは `201` を返します） レスポンス：`{ "created": N, "updated": M, "dryRun": false }` まず `dryRun=true` で送信し、件数が想定どおりであることを確認してから、実際のインポートを行うことを推奨します。 {% endstep %} {% endstepper %} インポート時の照合・更新ルールは次のとおりです： * （`Source ID`、`Email`）をキーとして upsert します。既存のコンタクトに一致した場合は名前／電話番号／Query Metadata を更新します（空白セルは変更しません）。一致しなければ作成します * `API Credentials` は（コンタクト、ツール）をキーとして upsert します。ファイルに記載されていないツールの認証情報は変更しません * バッチ全体を1つのトランザクションで処理します。いずれかの行に形式エラー（フィールド名の不一致、不正な JSON など）がある場合は、バッチ全体を書き込みません。エラーメッセージには行番号を表示します {% hint style="info" %} インポートは紐付けと属性の設定のみを行います。ユーザーの Token 認証情報は、引き続きログインフローの [ID 同期 API](/tech/ja/serve/contacts/contact-credentials-sync.md) でログインのたびに更新します。 {% endhint %} ## グラフィカルインターフェースでのコンタクト作成 少数のコンタクトは、管理画面で手動追加するか、Excel で一括インポートできます（プレビューに対応します）。手順はユーザーマニュアルの[コンタクトの追加](https://docs.maiagent.ai/serve/daily-operations/contact#add-contact)と[コンタクトの一括インポート](https://docs.maiagent.ai/serve/daily-operations/contact#bulk-import-contacts)を参照してください。作成後、コンタクト一覧からコンタクト ID をコピーできます。これが Web Chat 初期化パラメータの `contactId` です。 {% hint style="info" %} コンタクトに設定された ID 情報は、クエリ時に対応する `query_metadata` 条件の組み合わせを生成するために使用します。 [**👉 Query Metadata の詳細**](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) {% endhint %} ## 実装上の推奨事項 1. **会員テーブルに紐付け用フィールドを追加します**（例：`maiagent_contact_id`、nullable な UUID）。作成・更新日時も記録し、企業の 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/ja/serve/contacts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.