聯絡人

列出聯絡人

GET /api/contacts/

參數

參數名稱	必填	類型	說明
inbox	❌	string	對話平台 ID
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string	姓名或來源ID搜尋
search	❌	string	全文搜尋

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/?inbox=example&page=1&pageSize=1&query=example&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/?inbox=example&page=1&pageSize=1&query=example&search=example", 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/?inbox=example&page=1&pageSize=1&query=example&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, 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->get("https://api.maiagent.ai/api/contacts/?inbox=example&page=1&pageSize=1&query=example&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "inbox"?: object // 非必填
      "name": string
      "avatar"?: string (uri) // 非必填
      "sourceId"?: string // 非必填
      "queryMetadata"?: object // 非必填
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    [
      {
        "id": "user1_uuid",
        "inbox": {
          "id": "inbox_uuid",
          "name": "inbox_name"
        },
        "name": "user1",
        "avatar": "",
        "sourceId": null,
        "queryMetadata": null,
        "createdAt": "1751875361000",
        "updatedAt": "1751875361000"
      },
      {
        "id": "user2_uuid",
        "inbox": {
          "id": "inbox_uuid",
          "name": "inbox_name"
        },
        "name": "user2",
        "avatar": "avatar_url",
        "sourceId": "self defined source id",
        "queryMetadata": "self defined query metadata",
        "createdAt": "1751875400000",
        "updatedAt": "1751875400000"
      }
    ]
  ]
}

---

建立聯絡人

POST /api/contacts/

請求內容

請求參數

欄位	類型	必填	說明
inbox	object	否
name	string	是
avatar	string (uri)	否
sourceId	string	否
queryMetadata	object	否

請求結構範例

{
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
}

請求範例值

{
  "inbox": {
    "id": "inbox_uuid",
    "name": "inbox_name"
  },
  "name": "user1",
  "avatar": "",
  "sourceId": "self defined source id",
  "queryMetadata": "self defined query metadata"
}

程式碼範例

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 '{
    "inbox": {
      "id": "inbox_uuid",
      "name": "inbox_name"
    },
    "name": "user1",
    "avatar": "",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "inbox": {
      "id": "inbox_uuid",
      "name": "inbox_name"
    },
    "name": "user1",
    "avatar": "",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata"
  };

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"
}

# 請求內容 (payload)
data = {
      "inbox": {
        "id": "inbox_uuid",
        "name": "inbox_name"
      },
      "name": "user1",
      "avatar": "",
      "sourceId": "self defined source id",
      "queryMetadata": "self defined query metadata"
    }

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' => {
            "inbox": {
                "id": "inbox_uuid",
                "name": "inbox_name"
            },
            "name": "user1",
            "avatar": "",
            "sourceId": "self defined source id",
            "queryMetadata": "self defined query metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "inbox": {
    "id": "inbox_uuid",
    "name": "inbox_name"
  },
  "name": "user1",
  "avatar": "",
  "sourceId": "self defined source id",
  "queryMetadata": "self defined query metadata"
}

---

獲取聯絡人詳情

GET /api/contacts/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 聯絡人.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", 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/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, 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->get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "user1_uuid",
  "inbox": {
    "id": "inbox_uuid",
    "name": "inbox_name"
  },
  "name": "user1",
  "avatar": "",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

更新聯絡人

PUT /api/contacts/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 聯絡人.

請求內容

請求參數

欄位	類型	必填	說明
inbox	object	否
name	string	是
avatar	string (uri)	否
sourceId	string	否
queryMetadata	object	否

請求結構範例

{
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
}

請求範例值

{
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  };

axios.put("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", 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/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata"
    }

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/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

---

更新聯絡人

PATCH /api/contacts/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 聯絡人.

請求內容

請求參數

欄位	類型	必填	說明
inbox	object	否
name	string	否
avatar	string (uri)	否
sourceId	string	否
queryMetadata	object	否

請求結構範例

{
  "inbox"?: object // 非必填
  "name"?: string // 非必填
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
}

請求範例值

{
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  };

axios.patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", 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/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata"
    }

response = requests.patch(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->patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "inbox"?: object // 非必填
  "name": string
  "avatar"?: string (uri) // 非必填
  "sourceId"?: string // 非必填
  "queryMetadata"?: object // 非必填
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

---

刪除聯絡人

DELETE /api/contacts/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 聯絡人.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", 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/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, 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->delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
204	No response body
400	聯絡人還有關聯的對話，無法刪除

---