聯絡人

創建聯絡人

POST /api/contacts

請求內容

請求參數

欄位名稱	必填	類型	說明
name	是	string	用戶名稱，用於識別此聯絡人
avatar	否	string (URL)	用戶頭像圖片的 URL，可選填
source_id	否	string	外部系統用戶唯一識別碼（如：企業的用戶 ID）
inbox	是	string	MaiAgent 的對話平台 ID
query_metadata	否	object	權限控制用的查詢條件設定，詳細說明如下

query_metadata

欄位名稱	必填	類型	說明
label_relations	否	object	查詢所需標籤條件，可設定單層或巢狀 AND/OR 條件邏輯
label_relations.operator	否	string	主邏輯運算子，支援 "AND" 或 "OR"
label_relations.conditions	否	array	條件陣列，可為單一 label_id 或巢狀邏輯組合
label_relations.conditions[].label_id	否	string (UUID)	指定的標籤 ID
label_relations.conditions[].operator	否	string	巢狀邏輯的運算子（"AND" 或 "OR"）
label_relations.conditions[].conditions	否	array	巢狀邏輯條件的子項陣列
knowledge_bases	否	array	指定可存取的知識庫清單（如不設定則無法查詢）
knowledge_bases[].knowledge_base_id	否	string (UUID)	指定的知識庫 ID
knowledge_bases[].chatbot_file_ids	否	array of string (UUID)	該知識庫下可查詢的 chatbot 檔案清單
knowledge_bases[].faq_ids	否	array of string (UUID)	該知識庫下可查詢的 FAQ 文件清單
knowledge_bases[].has_user_selected_all	否	string ("True" / "False")	使用者是否選擇查詢此知識庫下所有內容（字串格式布林值）

請求結構範例

{
  "name": string,             // 必填
  "avatar"?: string,
  "source_id"?: string,
  "inbox": string,            // 必填
  "query_metadata"?: {
    "label_relations"?: {
      "operator": string,     // 必填
      "conditions": [         // 必填
        {
          "label_id": string  // 必填
        },
        {
          "operator": string,    // 必填
          "conditions": [        // 必填
            {
              "label_id": string // 必填
            }
          ]
        }
      ]
    },
    "knowledge_bases"?: [
      {
        "knowledge_base_id": string,       // 必填
        "chatbot_file_ids"?: string[],
        "faq_ids"?: string[],
        "has_user_selected_all"?: string   // "True" or "False"
      }
    ]
  }
}

請求範例值

{
  "name": "王小明",
  "avatar": "https://example.com/avatar.jpg",
  "source_id": "user_123456",
  "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
  "query_metadata": {
    "label_relations": {
      "operator": "OR",
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" },
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
        ],
        "has_user_selected_all": "False"
      }
    ]
  }
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/contacts" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "王小明",
    "avatar": "https://example.com/avatar.jpg",
    "source_id": "user_123456",
    "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
    "query_metadata": {
      "label_relations": {
        "operator": "OR",
        "conditions": [
          { "label_id": "11111111-2222-3333-4444-555555555555" },
          {
            "operator": "AND",
            "conditions": [
              { "label_id": "66666666-7777-8888-9999-000000000000" },
              { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
            ]
          }
        ]
      },
      "knowledge_bases": [
        {
          "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
          "chatbot_file_ids": ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
          "faq_ids": ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
          "has_user_selected_all": "False"
        }
      ]
    }
  }'

JavaScript

const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

const data = {
  name: "王小明",
  avatar: "https://example.com/avatar.jpg",
  source_id: "user_123456",
  inbox: "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
  query_metadata: {
    label_relations: {
      operator: "OR",
      conditions: [
        { label_id: "11111111-2222-3333-4444-555555555555" },
        {
          operator: "AND",
          conditions: [
            { label_id: "66666666-7777-8888-9999-000000000000" },
            { label_id: "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
    knowledge_bases: [
      {
        knowledge_base_id: "123e4567-e89b-12d3-a456-426614174000",
        chatbot_file_ids: ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
        faq_ids: ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
        has_user_selected_all: "False"
      }
    ]
  }
};

axios.post("https://api.maiagent.ai/api/contacts", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "name": "王小明",
    "avatar": "https://example.com/avatar.jpg",
    "source_id": "user_123456",
    "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
    "query_metadata": {
        "label_relations": {
            "operator": "OR",
            "conditions": [
                {"label_id": "11111111-2222-3333-4444-555555555555"},
                {
                    "operator": "AND",
                    "conditions": [
                        {"label_id": "66666666-7777-8888-9999-000000000000"},
                        {"label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee"}
                    ]
                }
            ]
        },
        "knowledge_bases": [
            {
                "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
                "chatbot_file_ids": ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
                "faq_ids": ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
                "has_user_selected_all": "False"
            }
        ]
    }
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/contacts", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            "name" => "王小明",
            "avatar" => "https://example.com/avatar.jpg",
            "source_id" => "user_123456",
            "inbox" => "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
            "query_metadata" => [
                "label_relations" => [
                    "operator" => "OR",
                    "conditions" => [
                        [ "label_id" => "11111111-2222-3333-4444-555555555555" ],
                        [
                            "operator" => "AND",
                            "conditions" => [
                                [ "label_id" => "66666666-7777-8888-9999-000000000000" ],
                                [ "label_id" => "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" ]
                            ]
                        ]
                    ]
                ],
                "knowledge_bases" => [
                    [
                        "knowledge_base_id" => "123e4567-e89b-12d3-a456-426614174000",
                        "chatbot_file_ids" => ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
                        "faq_ids" => ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
                        "has_user_selected_all" => "False"
                    ]
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": "string",                    // 聯絡人 ID（MaiAgent 生成）
  "inboxName": "string",            // 對話平台名稱
  "name": "string",                 // 使用者名稱
  "avatar": "string",               // 使用者頭像 URL
  "sourceId": "string",             // 企業系統中的使用者 ID
  "queryMetadata": { ... } or null, // 使用者查詢條件 metadata（未設定則為 null）
  "createdAt": "string",            // 建立時間
  "updatedAt": "string"             // 更新時間
}

回應範例值

{
            "id": "4f56d00f-c089-468d-9b34-475cc91d609e",
            "inboxName": "聊天助理",
            "name": "小明",
            "avatar": null,
            "sourceId": "",
            "queryMetadata": null,
            "createdAt": "1751708039000",
            "updatedAt": "1751708039000"
        }

更新聯絡人

PUT /api/contacts/{contact_id}

參數

參數名稱	必填	類型	說明
contact_id	是	string	MaiAgent 生成的聯絡人 ID

請求內容

請求參數

欄位名稱	必填	類型	說明
name	是	string	用戶名稱，用於識別此聯絡人
avatar	否	string (URL)	用戶頭像圖片的 URL，可選填
source_id	否	string	外部系統用戶唯一識別碼（如：企業的用戶 ID）
inbox	是	string	MaiAgent 的對話平台 ID
query_metadata	否	object	權限控制用的查詢條件設定，詳細說明如下

query_metadata

欄位名稱	必填	類型	說明
label_relations	否	object	查詢所需標籤條件，可設定單層或巢狀 AND/OR 條件邏輯
label_relations.operator	否	string	主邏輯運算子，支援 "AND" 或 "OR"
label_relations.conditions	否	array	條件陣列，可為單一 label_id 或巢狀邏輯組合
label_relations.conditions[].label_id	否	string (UUID)	指定的標籤 ID
label_relations.conditions[].operator	否	string	巢狀邏輯的運算子（"AND" 或 "OR"）
label_relations.conditions[].conditions	否	array	巢狀邏輯條件的子項陣列
knowledge_bases	否	array	指定可存取的知識庫清單（如不設定則無法查詢）
knowledge_bases[].knowledge_base_id	否	string (UUID)	指定的知識庫 ID
knowledge_bases[].chatbot_file_ids	否	array of string (UUID)	該知識庫下可查詢的 chatbot 檔案清單
knowledge_bases[].faq_ids	否	array of string (UUID)	該知識庫下可查詢的 FAQ 文件清單
knowledge_bases[].has_user_selected_all	否	string ("True" / "False")	使用者是否選擇查詢此知識庫下所有內容（字串格式布林值）

請求結構範例

{
  "name": string,             // 必填
  "avatar"?: string,
  "source_id"?: string,
  "inbox": string,            // 必填
  "query_metadata"?: {
    "label_relations"?: {
      "operator": string,     // 必填
      "conditions": [         // 必填
        {
          "label_id": string  // 必填
        },
        {
          "operator": string,    // 必填
          "conditions": [        // 必填
            {
              "label_id": string // 必填
            }
          ]
        }
      ]
    },
    "knowledge_bases"?: [
      {
        "knowledge_base_id": string,       // 必填
        "chatbot_file_ids"?: string[],
        "faq_ids"?: string[],
        "has_user_selected_all"?: string   // "True" or "False"
      }
    ]
  }
}

請求範例值

{
  "name": "王小明",
  "avatar": "https://example.com/avatar.jpg",
  "source_id": "user_123456",
  "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
  "query_metadata": {
    "label_relations": {
      "operator": "OR",
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" },
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
        ],
        "has_user_selected_all": "False"
      }
    ]
  }
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/contacts/{contact_id}/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "王小明",
    "avatar": "https://example.com/avatar.jpg",
    "source_id": "user_123456",
    "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
    "query_metadata": {
      "label_relations": {
        "operator": "OR",
        "conditions": [
          { "label_id": "11111111-2222-3333-4444-555555555555" },
          {
            "operator": "AND",
            "conditions": [
              { "label_id": "66666666-7777-8888-9999-000000000000" },
              { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
            ]
          }
        ]
      },
      "knowledge_bases": [
        {
          "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
          "chatbot_file_ids": ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
          "faq_ids": ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
          "has_user_selected_all": "False"
        }
      ]
    }
  }'

JavaScript

const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

const data = {
  name: "王小明",
  avatar: "https://example.com/avatar.jpg",
  source_id: "user_123456",
  inbox: "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
  query_metadata: {
    label_relations: {
      operator: "OR",
      conditions: [
        { label_id: "11111111-2222-3333-4444-555555555555" },
        {
          operator: "AND",
          conditions: [
            { label_id: "66666666-7777-8888-9999-000000000000" },
            { label_id: "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
    knowledge_bases: [
      {
        knowledge_base_id: "123e4567-e89b-12d3-a456-426614174000",
        chatbot_file_ids: ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
        faq_ids: ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
        has_user_selected_all: "False"
      }
    ]
  }
};

axios.put("https://api.maiagent.ai/api/contacts/{contact_id}/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/{contact_id}//"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "name": "王小明",
    "avatar": "https://example.com/avatar.jpg",
    "source_id": "user_123456",
    "inbox": "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
    "query_metadata": {
        "label_relations": {
            "operator": "OR",
            "conditions": [
                {"label_id": "11111111-2222-3333-4444-555555555555"},
                {
                    "operator": "AND",
                    "conditions": [
                        {"label_id": "66666666-7777-8888-9999-000000000000"},
                        {"label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee"}
                    ]
                }
            ]
        },
        "knowledge_bases": [
            {
                "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
                "chatbot_file_ids": ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
                "faq_ids": ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
                "has_user_selected_all": "False"
            }
        ]
    }
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/contacts/{contact_id}/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            "name" => "王小明",
            "avatar" => "https://example.com/avatar.jpg",
            "source_id" => "user_123456",
            "inbox" => "8a2b1c3d-4e5f-6789-abcd-ef0123456789",
            "query_metadata" => [
                "label_relations" => [
                    "operator" => "OR",
                    "conditions" => [
                        [ "label_id" => "11111111-2222-3333-4444-555555555555" ],
                        [
                            "operator" => "AND",
                            "conditions" => [
                                [ "label_id" => "66666666-7777-8888-9999-000000000000" ],
                                [ "label_id" => "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" ]
                            ]
                        ]
                    ]
                ],
                "knowledge_bases" => [
                    [
                        "knowledge_base_id" => "123e4567-e89b-12d3-a456-426614174000",
                        "chatbot_file_ids" => ["9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e"],
                        "faq_ids" => ["a1b2c3d4-e5f6-7890-abcd-1234567890ab"],
                        "has_user_selected_all" => "False"
                    ]
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": "string",                    // 聯絡人 ID（MaiAgent 生成）
  "inboxName": "string",            // 對話平台名稱
  "name": "string",                 // 使用者名稱
  "avatar": "string",               // 使用者頭像 URL
  "sourceId": "string",             // 企業系統中的使用者 ID
  "queryMetadata": { ... } or null, // 使用者查詢條件 metadata（未設定則為 null）
  "createdAt": "string",            // 建立時間
  "updatedAt": "string"             // 更新時間
}

回應範例值

{
            "id": "4f56d00f-c089-468d-9b34-475cc91d609e",
            "inboxName": "聊天助理",
            "name": "小明",
            "avatar": null,
            "sourceId": "",
            "queryMetadata": null,
            "createdAt": "1751708039000",
            "updatedAt": "1751708039000"
        }