> 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/maiagent-tech-ja/authorization-integration/contacts.md).

# 連絡先（Contact）の紹介と連携

## コンタクトとは？

### 基本的な定義

コンタクト（Contact）は MaiAgent における重要な情報の担い手であり、企業が顧客データを MaiAgent サービスと同期させることを可能にします。これにより、正確な権限管理とパーソナライズされたサービスを実現し、個別化された対話サービスを確保します。

コンタクトの動作の仕組みは以下の図のとおりです。

{% tabs %}
{% tab title="企業が外部の消費者向けに連携する場合" %}

<figure><img src="/files/CUy2K5qD6vhmiMHQBdXn" alt=""><figcaption></figcaption></figure>
{% endtab %}

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

<figure><img src="/files/du2WUvlzdHw8fRUM8IVV" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

MaiAgent は、当該顧客の MaiAgent 内における企業の顧客データに対応したコンタクト情報（Contact）を通じて、MaiAgent API を連携する際に対応するコンタクト 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 User
    participant ES as 企業システム
    participant MA as MaiAgent
    CU ->> ES: ウェブサイト対話を起動（Source ID を保有）
    ES ->> ES: 対応する Contact ID が既に存在するか確認
    alt Contact ID あり
        ES ->> MA: コンタクト情報を更新 (PUT /api/contacts/{contact_id})
        MA -->> ES: 更新成功レスポンスを返却
    else 既存の Contact なし
        ES ->> MA: 新規コンタクトを作成 (POST /api/contacts)
        MA -->> ES: 新しい Contact ID を返却
    end
    ES ->> ES: Contact ID とユーザーの対応を保存
    ES ->> CU: Web Chat 埋め込みコードを読み込み (Contact ID を含む)
    CU ->> MA: MaiAgent Web Chat を起動（Contact ID で初期化）
    MA -->> CU: 対応する権限のチャット画面を表示
```

## システムアーキテクチャの概要 <a href="#e7-b3-bb-e7-b5-b1-e6-9e-b6-e6-a7-8b-e6-a6-82-e8-bf-b0" id="e7-b3-bb-e7-b5-b1-e6-9e-b6-e6-a7-8b-e6-a6-82-e8-bf-b0"></a>

* **企業システム**：メインシステムであり、ユーザー管理と Web Chat の統合を担当します
* **MaiAgent**：Web Chat 機能を提供するサービス側です
* **通信プロトコル**：RESTful API

## 連携フロー <a href="#e5-b0-8d-e6-8e-a5-e6-b5-81-e7-a8-8b" id="e5-b0-8d-e6-8e-a5-e6-b5-81-e7-a8-8b"></a>

### ステップ 1：ユーザー身元の確認 <a href="#e6-a-d-a5-e9-a9-9f-1-e7-94-a8-e6-88-b6-e8-ba-ab-e4-bb-bd-e6-aa-a2-e6-9f-a5" id="e6-a-d-a5-e9-a9-9f-1-e7-94-a8-e6-88-b6-e8-ba-ab-e4-bb-bd-e6-aa-a2-e6-9f-a5"></a>

企業システムは、現在のユーザーが MaiAgent システム内で既に Contact として登録されているかどうかを確認する必要があります。

### ステップ 2：Contact の作成または更新 <a href="#e6-a-d-a5-e9-a9-9f-2-e5-bb-ba-e7-ab-8b-e6-88-96-e6-9b-b4-e6-96-b0-contact" id="e6-a-d-a5-e9-a9-9f-2-e5-bb-ba-e7-ab-8b-e6-88-96-e6-9b-b4-e6-96-b0-contact"></a>

ステップ 1 の結果に基づき、新規コンタクトを作成するかどうかを決定します。

<table><thead><tr><th width="58.999969482421875"></th><th width="311.3333740234375">新規コンタクトの作成</th><th width="423.21990966796875">既存コンタクトの更新</th></tr></thead><tbody><tr><td><strong>適用される状況</strong></td><td>初回訪問であり、企業システム内にまだ対応する Contact がない場合。例：<br>1. ユーザーが初めて Web Chat を通じて企業とやり取りする場合<br>2. 訪問者が企業の正式な会員へと移行し、訪問者時代の対話や権限を共有しないよう専用のコンタクトを作成する必要がある場合</td><td>会員が企業システム内で氏名、Email、携帯電話番号などの情報を変更し、以降の対話でパーソナライズされた内容が正しく反映されるよう MaiAgent のコンタクト情報を同期して更新する必要がある場合。<br>企業会員において権限やアカウント状態の変更があった場合も、Web Chat の権限が正しく対応するようコンタクト情報を更新する必要があります</td></tr><tr><td><strong>API エンドポイント</strong></td><td><code>POST /api/contacts/</code> API を使用するほか、<a href="#tu-xing-hua-jie-mian-jian-li-lian-luo-ren">グラフィカルインターフェースでコンタクトを作成</a>することもできます</td><td><code>PUT /api/contacts/{contact_id}/</code></td></tr><tr><td><strong>機能</strong></td><td>新しいコンタクトを作成して対応付けに使用し、パーソナライズされた対話サービスをスムーズにします</td><td>既存コンタクトのデータを更新します。例：Query Metadata の権限管理、更新された会員データなど</td></tr><tr><td><strong>パラメータ</strong></td><td>作成するコンタクトの名前 (name) を指定する必要があります。対応する会員データがない場合はデフォルトで「匿名」となります (例：ウェブ訪問者)</td><td><code>contact_id</code> を指定する必要があります</td></tr><tr><td><strong>レスポンス</strong></td><td>新しく作成された <code>contact_id</code> を返却します</td><td>更新成功の確認メッセージを返却します</td></tr></tbody></table>

> 詳細な schema の内容は [**🌐 API ドキュメント-コンタクト↗**](https://docs.maiagent.ai/api/lian-luo-ren) を参照してください

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

1. コンタクト管理画面に入ります

<figure><img src="/files/pAM0h9TGPm84qpL6UDZX" alt=""><figcaption></figcaption></figure>

2. 「コンタクトを追加」をクリックします

<figure><img src="/files/E4RSC5EZwdYOV3BIBTMg" alt=""><figcaption><p>コンタクトページ</p></figcaption></figure>

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

<figure><img src="/files/aEfqk7f7rEiw6iSAJz90" alt=""><figcaption><p>コンタクト編集ページ</p></figcaption></figure>

コンタクトの氏名を追加し、対話プラットフォームを指定するとコンタクト情報を作成できます。コピーボタンをクリックすると、コンタクト ID (Web Chat の初期化パラメータ ContactId) をコピーできます。

<figure><img src="/files/VtP1gAf6GtWzK4Z545Py" alt=""><figcaption></figcaption></figure>

***

{% hint style="info" %}
コンタクト Contact に設定された身元情報は、クエリ時に対応する `query_metadata` の条件の組み合わせを生成するために使用されます。

[**👉 Query Metadata について理解する**](/tech/maiagent-tech-ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)
{% endhint %}

**処理ロジック：**

* 企業システムは、返却された `contact_id`（Create 時）を適切に保存する必要があります
* `contact_id` を企業システムのユーザー ID と関連付けて保存することを推奨します
* Update 時には、URL パスに既存の `contact_id` を指定する必要があります

### ステップ 3：Web Chat の初期化 <a href="#e6-a-d-a5-e9-a9-9f-3-e5-88-9d-e5-a7-8b-e5-8c-96-web-chat" id="e6-a-d-a5-e9-a9-9f-3-e5-88-9d-e5-a7-8b-e5-8c-96-web-chat"></a>

ステップ 2 で取得した Contact ID を Web Chat の初期化に渡すパラメータに追加し、初期化スクリプトを実行します。

{% hint style="info" %}
[🌐Web Chat の初期化↗](/tech/maiagent-tech-ja/api-integration/web-chat-sdk.md) を参照して、Web Chat の初期化を行ってください。
{% endhint %}

## 利用方法の説明 <a href="#e4-bd-bf-e7-94-a8-e8-aa-aa-e6-98-8e" id="e4-bd-bf-e7-94-a8-e8-aa-aa-e6-98-8e"></a>

#### 企業はさまざまな対話ニーズに応じて、当該コンタクトが閲覧できるデータなどの権限を自由に設定できます。Contact の対話権限機能は、主に以下のシーンで利用されます。

* **企業内部の権限管理**：Contact 設定を通じて、異なるユーザーの対話権限の範囲を管理します
* **Web Chat の埋め込み**：Web Chat を企業のウェブサイトに埋め込んだ後、MaiAgent の会員データがない状況でも、企業は contact の連携設定を通じて対話の権限管理を実現できます
* **会員作成のスキップ**：対話プラットフォームのユーザーは MaiAgent プラットフォームに登録する必要がなく、MaiAgent メンバーの作成や役割の割り当てを省略して、Contact ID を通じて直接対話権限を管理できます

この機能は、きめ細かな権限制御を必要とする企業のアプリケーションシーンに特に適しています。

### 実装上の推奨事項 <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. **企業システム内に Contact ID 管理表を作成することを推奨します**。以下を含みます：
   * 企業ユーザー ID
   * MaiAgent Contact ID

     MaiAgent と接続を確立する際に、企業ユーザーデータと MaiAgent のコンタクトを正しく紐付けるのに役立ちます
   * 作成日時
   * 最終更新日時
2. **冪等性チェックを実装し**、Contact の重複作成を回避します
3. **ログ記録の仕組みを構築し**、API 呼び出しの状況を追跡します
4. **非同期処理の実装を検討し**、ユーザー体験を向上させます。上記の Contact 関連 API とシステムの他の 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/maiagent-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.