# 聯絡人 (Contact) 介紹及串接

## 聯絡人是什麼？

### 核心定義

聯絡人（Contact）是 MaiAgent 中一個重要的資訊載體，它讓企業能夠將客戶資料與 MaiAgent 服務進行同步，實現精確的權限管理和個性化服務，確保個人化對話服務。

聯絡人運作方式如下圖：

{% tabs %}
{% tab title="企業串接予外部消費者使用" %}

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

{% tab title="企業串接予內部員工使用" %}

<figure><img src="/files/lVzcxF9wnwPWOs0RQgWg" 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/5oAwxEszg1DMxHOApNm0" alt=""><figcaption></figcaption></figure>

2. 點擊「新增聯絡人」

<figure><img src="/files/gtAYOzT2sfxyxbpHmW89" alt=""><figcaption><p>聯絡人頁面</p></figcaption></figure>

點擊後會出現以下頁面：

<figure><img src="/files/V1TGP0y0c3w0MB1ir2UL" alt=""><figcaption><p>聯絡人編輯頁面</p></figcaption></figure>

新增聯絡人姓名、指定對話平台後即可建立聯絡人資訊，可點擊複製按鍵，複製聯絡人 ID (為 Web Chat 初始化參數 ContactId)

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

***

{% hint style="info" %}
聯絡人 Contact 所設定的身份資訊，將用於查詢時產生對應的 `query_metadata` 條件組合

[**👉 了解 Query Metadata**](/tech/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/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: 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:

```
GET https://docs.maiagent.ai/tech/authorization-integration/contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.