> 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）の概要と連携

## 連絡先とは？ <a href="#what-is-contact" id="what-is-contact"></a>

連絡先（Contact）は、「AI アシスタントと対話する**エンドユーザー**」を表します。企業が自社システムのユーザーを MaiAgent の連絡先に対応付けることで、AI は「誰が質問しているか」を識別し、他人のものではなく、**そのユーザー本人**の会話履歴と権限設定を正しく参照できます。

連絡先には MaiAgent アカウントは不要です（これが[メンバー／ロール](/tech/ja/authorization-integration/role-vs-contact.md)との最大の違いです）。また、ユーザーが連絡先の存在を意識することもありません。連絡先は、お客様のシステムと MaiAgent の間で ID を対応付けるためのものです。

{% tabs %}
{% tab title="企業が外部顧客向けに連携する場合" %}

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-d6af1ffa6f08908a0b45d4f328a7949a7647fe4b%2F%E5%B7%B2%E7%99%BB%E5%85%A5%E6%9C%83%E5%93%A1%20A%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="企業が社内従業員向けに連携する場合" %}

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-55af379e9fd20c7509ed2733bbedc7e47cc12177%2F%E4%BC%81%E6%A5%AD%E7%AB%AF%E8%81%AF%E7%B5%A1%E4%BA%BA%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### 連絡先に関連付けられる情報 <a href="#contact-capabilities" id="contact-capabilities"></a>

| データ                           | 用途                                       | 詳細                                                                                                                                       |
| ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 基本情報（`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` を渡すと有効になります                                                                                                        |

## 連絡先を作成・同期する4つの方法 <a href="#three-paths" id="three-paths"></a>

| 方法                                         | 適した用途                                                  | 説明                                                                                                                                                                                                                           |
| ------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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 同期を使用します）。

## 連携フロー <a href="#e5-ae-8c-e6-95-b4-e6-b5-81-e7-a8-8b-e5-9c-96" id="e5-ae-8c-e6-95-b4-e6-b5-81-e7-a8-8b-e5-9c-96"></a>

```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: その連絡先の ID で 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/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） <a href="#bulk-import" id="bulk-import"></a>

既存システムとの初回連携では、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/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`     |    | API ツールの認証情報を紐付ける JSON 配列 `[{"tool": "<ツール ID>", "headers": {...}}]` です。空白の場合は既存の認証情報を保持します                                                                                                                        |
| {% endstep %}         |    |                                                                                                                                                                                                                    |

{% step %}

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

連絡先 API と同様に、`multipart/form-data` および `Authorization: Api-Key` 認証を使用して `POST /api/v1/contacts/bulk-import/` を送信します。

* `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 します。ファイルに記載されていないツールの認証情報は変更されません
* バッチ全体を1つのトランザクションで処理します。フィールド名の不一致や不正な JSON など、いずれかの行に形式エラーがある場合は一切書き込まれず、エラーメッセージに該当する行番号が表示されます

{% hint style="info" %}
インポートで作成されるのは対応付けと属性のみです。ユーザーの Token 認証情報は、ログインのたびに[ID 同期 API](/tech/ja/authorization-integration/contact-credentials-sync.md)によって更新されます。
{% endhint %}

## GUI で連絡先を作成 <a href="#tu-xing-hua-jie-mian-jian-li-lian-luo-ren" id="tu-xing-hua-jie-mian-jian-li-lian-luo-ren"></a>

1. 連絡先管理画面を開きます

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-e1193c589be2e94dd3b408588d7ea9a426bb3d2a%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20165727.png?alt=media" alt=""><figcaption></figcaption></figure>

2. <mark style="color:blue;">連絡先を追加</mark>をクリックします

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-171e757ba0a247067dd74785a3369bd923346aa4%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-12%20151138.png?alt=media" alt=""><figcaption><p>連絡先ページ</p></figcaption></figure>

クリックすると、次のページが表示されます。

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-9394e2ab5bda81251ed624ff03bf4581adfc8750%2Fimage%20(4).png?alt=media" alt=""><figcaption><p>連絡先編集ページ</p></figcaption></figure>

連絡先の氏名を入力して会話プラットフォームを指定すると、連絡先を作成できます。作成後、コピーボタンをクリックして連絡先 ID（Web Chat の初期化パラメータ `contactId`）を取得できます。

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-07c83ea310e65aaed604a9564fa6916fd19f33a6%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-12%20151824.png?alt=media" alt=""><figcaption></figcaption></figure>

***

{% 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 %}

## 実装上の推奨事項 <a href="#e5-af-a6-e4-bd-9c-e5-bb-ba-e8-a-d-b0" id="e5-af-a6-e4-bd-9c-e5-bb-ba-e8-a-d-b0"></a>

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=<question>&goal=<endgoal>
```

`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.