> 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/api/ja/api-reference/lian-luo-ren.md).
# 連絡先
### 連絡先の一覧を取得
GET `/api/v1/contacts/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------------ | -- | ------- | ---------------------------------------------- |
| `channels` | ❌ | array | Multiple values may be separated by commas. |
| `externalId` | ❌ | string | 外部ユーザー ID（完全一致） |
| `inbox` | ❌ | string | Deprecated: Use inboxes instead |
| `inboxes` | ❌ | string | 会話プラットフォーム ID（特定の inbox の連絡先を絞り込みます） |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | 名前またはソース ID で検索します |
| `search` | ❌ | string | 全文検索 |
| `tags` | ❌ | array | Multiple values may be separated by commas. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/?channels=example&externalId=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/contacts/?channels=example&externalId=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=example", config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストでエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/?channels=example&externalId=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=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)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/contacts/?channels=example&externalId=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=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();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"count": integer
"next"?: string (uri) // 任意
"previous"?: string (uri) // 任意
"results": [
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定した場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 複数の型を取り得ます (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (任意)
"phoneNumber"?: string // 任意
"email"?: // 複数の型を取り得ます (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID：呼び出し元システムのユーザー ID です。同じ組織内で一意である必要があり、削除済みの連絡先は対象外です。元の文字列との完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを利用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドを優先します） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツを選択し、一覧の項目を除外します。false の場合は一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // ラベルのフィルター条件です。conditions が空配列の場合はラベルで絞り込みません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルのフィルターは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です
"conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先のコネクタの OAuth 認可一覧です（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes のチャット開始前フォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングを使用し、フロントエンドで metadata の UUID キーを表示名に変換します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**レスポンスの値の例**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
[
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
},
{
"id": "user2_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user2",
"avatar": "avatar_url",
"sourceId": "self defined source id",
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "5f8c6a99-5515-43aa-8e83-fdeea327a3a2",
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "OR",
"conditions": [
{
"labelId": "957998f9-1824-4872-becd-b7f8a7962896"
}
]
}
},
"createdAt": "1751875400000",
"updatedAt": "1751875400000"
}
]
]
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先を作成
POST `/api/v1/contacts/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "5f8c6a99-5515-43aa-8e83-fdeea327a3a2",
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "OR",
"conditions": [
{
"labelId": "957998f9-1824-4872-becd-b7f8a7962896"
}
]
}
},
"metadata": [
{
"key": "顧客ランク",
"value": "VIP"
},
{
"key": "希望言語",
"value": "繁体字中国語"
}
]
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "5f8c6a99-5515-43aa-8e83-fdeea327a3a2",
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "OR",
"conditions": [
{
"labelId": "957998f9-1824-4872-becd-b7f8a7962896"
}
]
}
},
"metadata": [
{
"key": "顧客ランク",
"value": "VIP"
},
{
"key": "希望言語",
"value": "繁体字中国語"
}
]
};
axios.post("https://api.maiagent.ai/api/v1/contacts/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストでエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "5f8c6a99-5515-43aa-8e83-fdeea327a3a2",
"hasUserSelectedAll": True
}
],
"labelRelations": {
"operator": "OR",
"conditions": [
{
"labelId": "957998f9-1824-4872-becd-b7f8a7962896"
}
]
}
},
"metadata": [
{
"key": "顧客ランク",
"value": "VIP"
},
{
"key": "希望言語",
"value": "繁体字中国語"
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/contacts/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'inboxes' => [
[
'id' => 'inbox_uuid'
]
],
'name' => 'user1',
'avatar' => '',
'phoneNumber' => 912345678,
'email' => 'user1@example.com',
'sourceId' => 'self defined source id',
'queryMetadata' => [
'knowledgeBases' => [
[
'knowledgeBaseId' => '5f8c6a99-5515-43aa-8e83-fdeea327a3a2',
'hasUserSelectedAll' => true
]
],
'labelRelations' => [
'operator' => 'OR',
'conditions' => [
[
'labelId' => '957998f9-1824-4872-becd-b7f8a7962896'
]
]
]
],
'metadata' => [
[
'key' => '顧客ランク',
'value' => 'VIP'
],
[
'key' => '希望言語',
'value' => '繁体字中国語'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 201**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定した場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 複数の型を取り得ます (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (任意)
"phoneNumber"?: string // 任意
"email"?: // 複数の型を取り得ます (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID：呼び出し元システムのユーザー ID です。同じ組織内で一意である必要があり、削除済みの連絡先は対象外です。元の文字列との完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを利用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドを優先します） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツを選択し、一覧の項目を除外します。false の場合は一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // ラベルのフィルター条件です。conditions が空配列の場合はラベルで絞り込みません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルのフィルターは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です
"conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先のコネクタの OAuth 認可一覧です（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes のチャット開始前フォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングを使用し、フロントエンドで metadata の UUID キーを表示名に変換します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の詳細を取得
GET `/api/v1/contacts/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/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);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/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)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/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();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 後方互換性のためのフィールドです。単一の inbox を指定します。inboxes も指定されている場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型になる場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスに対応しています (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型になる場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID：呼び出し元システムのユーザー ID です。同じ組織内で一意である必要があります（削除済みの連絡先は除きます）。元の文字列と完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムの接頭辞を付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合、このフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合、ナレッジベースのすべてのコンテンツを選択し、一覧の項目を除外します。false の場合、一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可の一覧です（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes のチャット開始前フォームのフィールド設定です。{field_id: {label: {locale: text}}} の形式でマッピングし、フロントエンドで metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の更新
PUT `/api/v1/contacts/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| --------------------------------------- | ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | いいえ | 連絡先の名前 |
| inboxes | array\[object] | いいえ | 会話プラットフォームの一覧（新形式） |
| inbox | object | いいえ | 単一の会話プラットフォーム（旧形式、後方互換性あり） |
| inbox.id | string (uuid) | はい | 会話プラットフォーム ID |
| avatar | string | いいえ | アバター URL |
| phoneNumber | string | いいえ | 連絡先の電話番号 |
| email | string (email) | いいえ | 連絡先のメールアドレス |
| sourceId | string | いいえ | ソース ID |
| queryMetadata | object | いいえ | クエリメタデータ（Query Metadata）は、検索可能なナレッジの範囲を制御します。未指定または null は未設定（制限なし）を意味します。空のオブジェクト {} も制限なし（すべて選択）として扱われ、アクセス権限なしにはなりません。knowledgeBases が空の配列または null の場合は、すべて検索不可（アクセス権限なし）です。labelRelations.conditions が空の配列の場合は、タグで絞り込みません（アクセス権限なしにはなりません）。詳細はこのエンドポイントの説明を参照してください。 |
| queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません |
| queryMetadata.labelRelations | object | いいえ | タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） |
| queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | タグ条件の組み合わせ方法 |
| queryMetadata.labelRelations.conditions | array\[any] | いいえ | タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています |
| metadata | array\[object] | いいえ | 連絡先のカスタム属性の一覧 |
**リクエストスキーマの例**
```typescript
{
"name"?: string // 連絡先の名前 (任意)
"inboxes"?: [ // 会話プラットフォームの一覧（新形式） (任意)
{
"id": string (uuid) // 会話プラットフォーム ID
}
]
"inbox"?: { // 単一の会話プラットフォーム（旧形式、後方互換性あり） (任意)
{
"id": string (uuid) // 会話プラットフォーム ID
}
}
"avatar"?: string // アバター URL (任意)
"phoneNumber"?: string // 連絡先の電話番号 (任意)
"email"?: string (email) // 連絡先のメールアドレス (任意)
"sourceId"?: string // ソース ID (任意)
"queryMetadata"?: { // クエリメタデータ（Query Metadata）は、検索可能なナレッジの範囲を制御します。未指定または null は未設定（制限なし）を意味します。空のオブジェクト {} も制限なし（すべて選択）として扱われ、アクセス権限なしにはなりません。knowledgeBases が空の配列または null の場合は、すべて検索不可（アクセス権限なし）です。labelRelations.conditions が空の配列の場合は、タグで絞り込みません（アクセス権限なしにはなりません）。詳細はこのエンドポイントの説明を参照してください。 (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合、このフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合、ナレッジベースのすべてのコンテンツを選択し、一覧の項目を除外します。false の場合、一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: [ // 連絡先のカスタム属性の一覧 (任意)
{
"key": string // 属性名
"value": string // 属性値
"updatedAt"?: string // 更新日時です（ISO 形式、省略可能です。未指定の場合は自動で設定されます） (任意)
}
]
}
```
**リクエストの値の例**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
};
axios.put("https://api.maiagent.ai/api/v1/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);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
}
response = requests.put(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'inboxes' => [
[
'id' => 'new_inbox_uuid'
]
],
'name' => 'updated_user_name',
'avatar' => 'updated_avatar_url',
'phoneNumber' => 987654321,
'email' => 'updated@example.com',
'sourceId' => 'updated_source_id',
'queryMetadata' => [
'knowledgeBases' => []
],
'metadata' => [
[
'key' => '顧客ランク',
'value' => 'VVIP'
],
[
'key' => '希望言語',
'value' => '日本語'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 後方互換性のためのフィールドです。単一の inbox を指定します。inboxes も指定されている場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型になる場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスに対応しています (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型になる場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID：呼び出し元システムのユーザー ID です。同じ組織内で一意である必要があります（削除済みの連絡先は除きます）。元の文字列と完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムの接頭辞を付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合、このフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合、ナレッジベースのすべてのコンテンツを選択し、一覧の項目を除外します。false の場合、一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可の一覧です（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes のチャット開始前フォームのフィールド設定です。{field_id: {label: {locale: text}}} の形式でマッピングし、フロントエンドで metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の一部更新
PATCH `/api/v1/contacts/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| --------------------------------------- | ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | いいえ | 連絡先の名前 |
| inboxes | array\[object] | いいえ | 会話プラットフォームの一覧（新形式） |
| inbox | object | いいえ | 単一の会話プラットフォーム（旧形式、後方互換性あり） |
| inbox.id | string (uuid) | はい | 会話プラットフォーム ID |
| avatar | string | いいえ | アバター URL |
| phoneNumber | string | いいえ | 連絡先の電話番号 |
| email | string (email) | いいえ | 連絡先のメールアドレス |
| sourceId | string | いいえ | ソース ID |
| queryMetadata | object | いいえ | クエリメタデータ（Query Metadata）は、検索可能なナレッジの範囲を制御します。未指定または null は未設定（制限なし）を意味します。空のオブジェクト {} も制限なし（すべて選択）として扱われ、アクセス権限なしにはなりません。knowledgeBases が空の配列または null の場合は、すべて検索不可（アクセス権限なし）です。labelRelations.conditions が空の配列の場合は、タグで絞り込みません（アクセス権限なしにはなりません）。詳細はこのエンドポイントの説明を参照してください。 |
| queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません |
| queryMetadata.labelRelations | object | いいえ | タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） |
| queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | タグ条件の組み合わせ方法 |
| queryMetadata.labelRelations.conditions | array\[any] | いいえ | タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています |
| metadata | array\[object] | いいえ | 連絡先のカスタム属性の一覧 |
**リクエストスキーマの例**
```typescript
{
"name"?: string // 連絡先の名前 (任意)
"inboxes"?: [ // 会話プラットフォームの一覧（新形式） (任意)
{
"id": string (uuid) // 会話プラットフォーム ID
}
]
"inbox"?: { // 単一の会話プラットフォーム（旧形式、後方互換性あり） (任意)
{
"id": string (uuid) // 会話プラットフォーム ID
}
}
"avatar"?: string // アバター URL (任意)
"phoneNumber"?: string // 連絡先の電話番号 (任意)
"email"?: string (email) // 連絡先のメールアドレス (任意)
"sourceId"?: string // ソース ID (任意)
"queryMetadata"?: { // クエリメタデータ（Query Metadata）は、検索可能なナレッジの範囲を制御します。未指定または null は未設定（制限なし）を意味します。空のオブジェクト {} も制限なし（すべて選択）として扱われ、アクセス権限なしにはなりません。knowledgeBases が空の配列または null の場合は、すべて検索不可（アクセス権限なし）です。labelRelations.conditions が空の配列の場合は、タグで絞り込みません（アクセス権限なしにはなりません）。詳細はこのエンドポイントの説明を参照してください。 (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（アクセス権限なし）となり、未指定の場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合、このフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外するか、指定したもののみを選択するかが決まります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合、ナレッジベースのすべてのコンテンツを選択し、一覧の項目を除外します。false の場合、一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしにはなりません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: [ // 連絡先のカスタム属性の一覧 (任意)
{
"key": string // 属性名
"value": string // 属性値
"updatedAt"?: string // 更新日時です（ISO 形式、省略可能です。未指定の場合は自動で設定されます） (任意)
}
]
}
```
**リクエストの値の例**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "希望言語",
"value": "日本語"
}
]
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "優先言語",
"value": "日本語"
}
]
};
axios.patch("https://api.maiagent.ai/api/v1/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);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": {
"knowledgeBases": []
},
"metadata": [
{
"key": "顧客ランク",
"value": "VVIP"
},
{
"key": "優先言語",
"value": "日本語"
}
]
}
response = requests.patch(url, json=data, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストでエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'inboxes' => [
[
'id' => 'new_inbox_uuid'
]
],
'name' => 'updated_user_name',
'avatar' => 'updated_avatar_url',
'phoneNumber' => 987654321,
'email' => 'updated@example.com',
'sourceId' => 'updated_source_id',
'queryMetadata' => [
'knowledgeBases' => []
],
'metadata' => [
[
'key' => '顧客ランク',
'value' => 'VVIP'
],
[
'key' => '優先言語',
'value' => '日本語'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持のためのフィールドです。単一の inbox を指定します。inboxes も指定された場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定します。同一組織内で一意である必要があります（削除済みの連絡先は除きます）。元の文字列を大文字と小文字を区別して完全一致で照合します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようなシステムのプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしとなります (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象となります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名称です。両方が指定された場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象となります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全内容を選択してリスト内の項目を除外します。false の場合はリスト内の項目のみを選択します (任意)
}
]
"labelRelations"?: { // ラベルのフィルター条件です。conditions が空配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同等です） (任意)
{
"operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です
"conditions"?: [ // ラベル条件のリストです。operator/conditions を入れ子にして組み合わせることができます (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報のリストです
object
]
"apiCredentials": [ // 連絡先の API 認証情報のリストです
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可のリストです（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が所属する inboxes の事前チャットフォームのフィールド設定です。{field_id: {label: {locale: text}}} の形式でマッピングされ、フロントエンドで metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の削除
DELETE `/api/v1/contacts/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```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/v1/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);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/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)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/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();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス
| ステータスコード | 説明 |
| -------- | ----------------------- |
| 204 | No response body |
| 400 | 連絡先に関連する会話があるため、削除できません |
***
### 連絡先の会話一覧を取得
GET `/api/v1/contacts/{id}/conversations/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------------ | -- | ------- | -------------------------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `channels` | ❌ | array | Multiple values may be separated by commas. |
| `externalId` | ❌ | string | 外部ユーザー ID（完全一致） |
| `inbox` | ❌ | string | 単一の inbox ID で絞り込みます（UUID 形式） |
| `inboxes` | ❌ | string | 複数の inbox ID で絞り込みます（uuid1,uuid2 のようにカンマで区切るか、inboxes パラメータを複数指定します） |
| `keyword` | ❌ | string | 会話内のメッセージ内容を検索します（大文字と小文字を区別しません） |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
| `tags` | ❌ | array | Multiple values may be separated by commas. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&externalId=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&externalId=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=example", config)
.then(response => {
console.log('レスポンスを正常に取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&externalId=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=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)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&externalId=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=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();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"count": integer
"next"?: string (uri) // 任意
"previous"?: string (uri) // 任意
"results": [
{
"id": string (uuid)
"contact": { // Conversation List view 用の軽量な Contact Serializer です
List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して、
N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、
フロントエンドの会話サイドバーに表示する必要がありますが、N+1 のコストは発生しません。
{
"id": string (uuid)
"name": string
"avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意)
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"phoneNumber"?: string // 任意
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"sourceId"?: string // 任意
"tags": [
{
"id": string (uuid)
"name": string
}
]
}
}
"inbox": { // Inbox summary embedded in a conversation payload.
``unread_conversations_count`` stays here because it is part of the
documented REST conversation API. It is an org-wide denormalized
counter, so WS emit paths must run the payload through
:func:`strip_org_wide_unread_count` before broadcasting it to rooms
that include members without ``GroupInbox.can_view_conversations``.
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
"unreadConversationsCount"?: integer // 任意
"signAuth"?: // 任意
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
"google"?: // 任意
{
"enabled": boolean
}
}
}
"sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
"sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.
* `signature` - Require signature verification
* `raw` - Source ID only (任意)
{
}
"sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.
* `1` - 1
* `5` - 5
* `15` - 15 (任意)
{
}
"keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
"keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
string
]
"organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
}
"enableAnalysis"?: boolean // 任意
}
}
"chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded.
``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature
gate) without comparing against the organization's ``maigpt_inbox`` id;
``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the
organization's file-library switch already applied).
"title": string
"lastMessage"?: { // 任意
{
"id": string (uuid)
"type"?: string // 任意
"content"?: string // 任意
"createdAt": string (timestamp)
}
}
"callRecord":
{
"id": string (uuid)
"status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated
* `ringing` - Ringing
* `in-progress` - In Progress
* `completed` - Completed
* `failed` - Failed
* `busy` - Busy
* `no-answer` - No Answer
* `canceled` - Canceled (任意)
"direction": string (enum: inbound, outbound) // * `inbound` - Inbound
* `outbound` - Outbound
"isActive": boolean
"canHangup": boolean
}
"lastMessageCreatedAt": string (timestamp)
"unreadMessagesCount": integer
"autoReplyEnabled": boolean
"isAutoReplyNow": boolean
"willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now.
The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the
inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat
is answered by the completions endpoint, which ignores the schedule, so there the
conversation switch alone decides. The channel is only looked up for a web inbox outside
its schedule.
Surfaces that ignore the schedule on any inbox answer from their own rule instead: the
completions endpoint continuing an existing conversation (``completions_progress_status``)
and voice turns, which the voice agent answers.
"lastReadAt": string (timestamp)
"createdAt": string (timestamp)
"isGroupChat": boolean
"enableGroupMention"?: boolean // 任意
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）を意味し、省略時は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方が指定された場合はこのフィールドを優先します） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true はナレッジベースの全内容から一覧内の項目を除外して選択し、false は一覧内の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合はタグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意)
"connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意)
"thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意)
"thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを意味します
{
"type"?: string // フォームの種類です。reasoning_effort に固定されています (任意)
"fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを低い順に列挙し、default は null に固定されています (任意)
"canDisable"?: boolean // このモデルの思考を無効にできるかを示します。true の場合、options に off が含まれます (任意)
"unsetBehavior"?: string (enum: off, model_default) // 会話にもアシスタントにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデルが自ら思考するか、プラットフォームのデフォルトレベルで思考が有効になることを意味します (任意)
"unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null の場合は思考パラメータを送信せず、モデル自体のデフォルトに従います (任意)
}
}
"effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping.
The stored choice resolves conversation > chatbot > the LLM row's default level; None means
the model sends no thinking parameter, so the provider default applies.
"llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model.
TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no
longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the
effective model. Read-only: displaying it never marks the conversation as explicitly selected;
only the update-llm endpoint does.
"deepResearchStatus": // Status of deep research for this conversation
* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
{
}
"deepResearchOutputFormat": // 異なる型を取る場合があります
string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed.
* `canvas` - Canvas
* `chat` - Chat reply
* `file` - Downloadable file
"ipAddress": string
"ipCountryCode": string
"ipRecordedAt": string (timestamp)
"assignee":
{
"id": string (uuid)
"name": string
"userId": string (uuid)
}
"status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (任意)
"tags": [
{
"id": string (uuid)
"name": string
"memberIds"?: [ // 任意
string (uuid)
]
}
]
"progressStatus": string
"firstResponseAt"?: string (timestamp) // 任意
"queuedAt"?: string (timestamp) // 任意
"assignedAt"?: string (timestamp) // 任意
"transferReason"?: string // 任意
"satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
"satisfactionComment": string
"satisfactionSubmittedAt": string (timestamp)
"latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).
Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
"clientPlatform": // Client platform that created this conversation (web, desktop)
* `web` - Web
* `desktop` - Desktop
{
}
"workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
"slideProjectId": string
"matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
"matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.
Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
"matchedMessageId": string
"pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
"folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation.
"hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume.
Lets the frontend know it should proactively re-request the browser
panel (emit ``browser:start``) after a page reload, instead of only
ever showing the panel when a live ``browser:frame`` push happens to
arrive first.
"callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound
"handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継がれる元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます
"displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています）
"autoSplitReason": string // 会話の自動分割でこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）を取ります。分割で作成されていない場合は null です
"continuedFrom": object // 分割で作成された会話の引き継ぎ元です。{id, last_message_at, deleted} を含みます。元の会話が削除されている場合は id=null、deleted=true です
"continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を含みます。存在しない場合は null です
"continuationSummary": object // 引き継ぎ要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を含みます（items は新しい順です）。分割で作成されていない場合は null です
"conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat
}
]
}
```
**レスポンス値の例**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"avatar": "レスポンス文字列",
"email": "response@example.com",
"phoneNumber": "レスポンス文字列",
"metadata": null,
"sourceId": "レスポンス文字列",
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
]
},
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"channelType": "line",
"unreadConversationsCount": 456,
"signAuth": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "レスポンス文字列",
"url": "レスポンス文字列",
"realm": "レスポンス文字列"
},
"line": {
"liffId": "レスポンス文字列"
},
"ad": {
"saml": "レスポンス文字列"
},
"google": {
"enabled": false
}
},
"sourceIdAccessEnabled": false,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": false,
"keycloakTokenPassthroughAllowedHosts": [
"レスポンス文字列"
],
"organizationLogin": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
},
"enableAnalysis": false
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"title": "レスポンス文字列",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "レスポンス文字列",
"content": "レスポンス文字列",
"createdAt": "レスポンス文字列"
},
"callRecord": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "initiated",
"direction": "inbound",
"isActive": false,
"canHangup": false
},
"lastMessageCreatedAt": "レスポンス文字列",
"unreadMessagesCount": 456,
"autoReplyEnabled": false,
"isAutoReplyNow": false,
"willAiReplyNow": false,
"lastReadAt": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"isGroupChat": false,
"enableGroupMention": false,
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"thinkingConfigSchema": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"effectiveThinkingConfig": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"llm": "550e8400-e29b-41d4-a716-446655440000",
"deepResearchStatus": {},
"deepResearchOutputFormat": "canvas",
"ipAddress": "レスポンス文字列",
"ipCountryCode": "レスポンス文字列",
"ipRecordedAt": "レスポンス文字列",
"assignee": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"userId": "550e8400-e29b-41d4-a716-446655440000"
},
"status": "open",
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
],
"progressStatus": "レスポンス文字列",
"firstResponseAt": "レスポンス文字列",
"queuedAt": "レスポンス文字列",
"assignedAt": "レスポンス文字列",
"transferReason": "レスポンス文字列",
"satisfactionScore": 456,
"satisfactionComment": "レスポンス文字列",
"satisfactionSubmittedAt": "レスポンス文字列",
"latestAnalysisSummary": "レスポンス文字列",
"clientPlatform": {},
"workingDirectory": "レスポンス文字列",
"slideProjectId": "レスポンス文字列",
"matchedField": "レスポンス文字列",
"matchedSnippet": "レスポンス文字列",
"matchedMessageId": "レスポンス文字列",
"pinnedAt": "レスポンス文字列",
"folder": "550e8400-e29b-41d4-a716-446655440000",
"hasActiveBrowserSession": false,
"callerOrganizationId": "レスポンス文字列",
"handoff": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"displayContextUsage": false,
"autoSplitReason": "レスポンス文字列",
"continuedFrom": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"continuedTo": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"continuationSummary": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"conversationKind": "レスポンス文字列"
}
]
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の最新の会話を取得
GET `/api/v1/contacts/{id}/conversations/latest/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| --------- | -- | ------ | ---------------------------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `inbox` | ❌ | string | 単一の inbox ID（UUID 形式）で絞り込みます |
| `inboxes` | ❌ | string | 複数の inbox ID で絞り込みます（uuid1,uuid2 のようにカンマで区切るか、複数の inboxes パラメータを使用します） |
| `keyword` | ❌ | string | 会話内のメッセージ内容を検索します（大文字と小文字は区別しません） |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=example", config)
.then(response => {
console.log('レスポンスを正常に取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"contact": { // Conversation List view 用の軽量な Contact Serializer です
List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して、
N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、
フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。
{
"id": string (uuid)
"name": string
"avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意)
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"phoneNumber"?: string // 任意
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"sourceId"?: string // 任意
"tags": [
{
"id": string (uuid)
"name": string
}
]
}
}
"inbox": { // Inbox summary embedded in a conversation payload.
``unread_conversations_count`` stays here because it is part of the
documented REST conversation API. It is an org-wide denormalized
counter, so WS emit paths must run the payload through
:func:`strip_org_wide_unread_count` before broadcasting it to rooms
that include members without ``GroupInbox.can_view_conversations``.
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
"unreadConversationsCount"?: integer // 任意
"signAuth"?: // 任意
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
"google"?: // 任意
{
"enabled": boolean
}
}
}
"sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
"sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.
* `signature` - Require signature verification
* `raw` - Source ID only (任意)
{
}
"sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.
* `1` - 1
* `5` - 5
* `15` - 15 (任意)
{
}
"keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
"keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
string
]
"organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
}
"enableAnalysis"?: boolean // 任意
}
}
"chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded.
``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature
gate) without comparing against the organization's ``maigpt_inbox`` id;
``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the
organization's file-library switch already applied).
"title": string
"lastMessage"?: { // 任意
{
"id": string (uuid)
"type"?: string // 任意
"content"?: string // 任意
"createdAt": string (timestamp)
}
}
"callRecord":
{
"id": string (uuid)
"status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated
* `ringing` - Ringing
* `in-progress` - In Progress
* `completed` - Completed
* `failed` - Failed
* `busy` - Busy
* `no-answer` - No Answer
* `canceled` - Canceled (任意)
"direction": string (enum: inbound, outbound) // * `inbound` - Inbound
* `outbound` - Outbound
"isActive": boolean
"canHangup": boolean
}
"lastMessageCreatedAt": string (timestamp)
"unreadMessagesCount": integer
"autoReplyEnabled": boolean
"isAutoReplyNow": boolean
"willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now.
The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the
inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat
is answered by the completions endpoint, which ignores the schedule, so there the
conversation switch alone decides. The channel is only looked up for a web inbox outside
its schedule.
Surfaces that ignore the schedule on any inbox answer from their own rule instead: the
completions endpoint continuing an existing conversation (``completions_progress_status``)
and voice turns, which the voice agent answers.
"lastReadAt": string (timestamp)
"createdAt": string (timestamp)
"isGroupChat": boolean
"enableGroupMention"?: boolean // 任意
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、省略時は制限なしを意味します (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true はリスト内の項目を除くナレッジベースの全内容を選択し、false はリスト内の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグの絞り込み条件です。conditions が空の配列の場合、タグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にタグの絞り込みは適用されません（制限なしと同等です） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です
"conditions"?: [ // タグ条件のリストです。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意)
"connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意)
"thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意)
"thinkingConfigSchema": { // このモデルの思考設定フォームです。null は、このモデルに思考設定がないことを示します
{
"type"?: string // フォームの種類です。reasoning_effort に固定されています (任意)
"fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを弱い順に列挙し、default は null に固定されています (任意)
"canDisable"?: boolean // このモデルで思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意)
"unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントのどちらにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデル自身の判断、またはプラットフォームのデフォルトレベルによる思考の有効化を意味します (任意)
"unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null は思考パラメータを送信せず、モデル自身のデフォルトに任せることを示します (任意)
}
}
"effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping.
The stored choice resolves conversation > chatbot > the LLM row's default level; None means
the model sends no thinking parameter, so the provider default applies.
"llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model.
TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no
longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the
effective model. Read-only: displaying it never marks the conversation as explicitly selected;
only the update-llm endpoint does.
"deepResearchStatus": // Status of deep research for this conversation
* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
{
}
"deepResearchOutputFormat": // 異なる型を取る場合があります
string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed.
* `canvas` - Canvas
* `chat` - Chat reply
* `file` - Downloadable file
"ipAddress": string
"ipCountryCode": string
"ipRecordedAt": string (timestamp)
"assignee":
{
"id": string (uuid)
"name": string
"userId": string (uuid)
}
"status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (任意)
"tags": [
{
"id": string (uuid)
"name": string
"memberIds"?: [ // 任意
string (uuid)
]
}
]
"progressStatus": string
"firstResponseAt"?: string (timestamp) // 任意
"queuedAt"?: string (timestamp) // 任意
"assignedAt"?: string (timestamp) // 任意
"transferReason"?: string // 任意
"satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
"satisfactionComment": string
"satisfactionSubmittedAt": string (timestamp)
"latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).
Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
"clientPlatform": // Client platform that created this conversation (web, desktop)
* `web` - Web
* `desktop` - Desktop
{
}
"workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
"slideProjectId": string
"matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
"matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.
Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
"matchedMessageId": string
"pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
"folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation.
"hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume.
Lets the frontend know it should proactively re-request the browser
panel (emit ``browser:start``) after a page reload, instead of only
ever showing the panel when a live ``browser:frame`` push happens to
arrive first.
"callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound
"handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます
"displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています）
"autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）です。分割による作成でない場合は null です
"continuedFrom": object // 分割で作成された会話の引き継ぎ元を示します：{id, last_message_at, deleted}。元の会話が削除済みの場合は id=null、deleted=true です
"continuedTo": object // この会話から分割された最新の会話です：{id, created_at}。該当する会話がない場合は null です
"continuationSummary": object // 引き継ぎ要約です：{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]}（items は新しい順です）。分割による作成でない場合は null です
"conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"avatar": "レスポンス文字列",
"email": "response@example.com",
"phoneNumber": "レスポンス文字列",
"metadata": null,
"sourceId": "レスポンス文字列",
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
]
},
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"channelType": "line",
"unreadConversationsCount": 456,
"signAuth": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "レスポンス文字列",
"url": "レスポンス文字列",
"realm": "レスポンス文字列"
},
"line": {
"liffId": "レスポンス文字列"
},
"ad": {
"saml": "レスポンス文字列"
},
"google": {
"enabled": false
}
},
"sourceIdAccessEnabled": false,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": false,
"keycloakTokenPassthroughAllowedHosts": [
"レスポンス文字列"
],
"organizationLogin": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
},
"enableAnalysis": false
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"title": "レスポンス文字列",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "レスポンス文字列",
"content": "レスポンス文字列",
"createdAt": "レスポンス文字列"
},
"callRecord": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "initiated",
"direction": "inbound",
"isActive": false,
"canHangup": false
},
"lastMessageCreatedAt": "レスポンス文字列",
"unreadMessagesCount": 456,
"autoReplyEnabled": false,
"isAutoReplyNow": false,
"willAiReplyNow": false,
"lastReadAt": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"isGroupChat": false,
"enableGroupMention": false,
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"thinkingConfigSchema": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"effectiveThinkingConfig": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"llm": "550e8400-e29b-41d4-a716-446655440000",
"deepResearchStatus": {},
"deepResearchOutputFormat": "canvas",
"ipAddress": "レスポンス文字列",
"ipCountryCode": "レスポンス文字列",
"ipRecordedAt": "レスポンス文字列",
"assignee": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"userId": "550e8400-e29b-41d4-a716-446655440000"
},
"status": "open",
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
],
"progressStatus": "レスポンス文字列",
"firstResponseAt": "レスポンス文字列",
"queuedAt": "レスポンス文字列",
"assignedAt": "レスポンス文字列",
"transferReason": "レスポンス文字列",
"satisfactionScore": 456,
"satisfactionComment": "レスポンス文字列",
"satisfactionSubmittedAt": "レスポンス文字列",
"latestAnalysisSummary": "レスポンス文字列",
"clientPlatform": {},
"workingDirectory": "レスポンス文字列",
"slideProjectId": "レスポンス文字列",
"matchedField": "レスポンス文字列",
"matchedSnippet": "レスポンス文字列",
"matchedMessageId": "レスポンス文字列",
"pinnedAt": "レスポンス文字列",
"folder": "550e8400-e29b-41d4-a716-446655440000",
"hasActiveBrowserSession": false,
"callerOrganizationId": "レスポンス文字列",
"handoff": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"displayContextUsage": false,
"autoSplitReason": "レスポンス文字列",
"continuedFrom": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"continuedTo": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"continuationSummary": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"conversationKind": "レスポンス文字列"
}
```
**ステータスコード: 404 - No response body**
***
### メッセージを一斉送信
POST `/api/v1/contacts/broadcast-message/`
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ----------------- | -------------- | --- | ----------------------------------------------------------- |
| contactIds | array\[string] | いいえ | \[宛先指定モード] メッセージを送信する contact ID の一覧です |
| inboxId | string (uuid) | いいえ | \[除外／全件送信モード] Inbox ID です。この inbox に属するすべての contacts に送信します |
| excludeContactIds | array\[string] | いいえ | \[除外モード] 除外する contact ID の一覧です。inbox\_id と併用する必要があります |
| message | string | はい | 送信するメッセージの内容です |
**リクエストスキーマの例**
```typescript
{
"contactIds"?: [ // [宛先指定モード] メッセージを送信する contact ID の一覧です (任意)
string (uuid)
]
"inboxId"?: string (uuid) // [除外／全件送信モード] Inbox ID です。この inbox に属するすべての contacts に送信します (任意)
"excludeContactIds"?: [ // [除外モード] 除外する contact ID の一覧です。inbox_id と併用する必要があります (任意)
string (uuid)
]
"message": string // 送信するメッセージの内容です
}
```
**リクエストの値の例**
```json
{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "これはサンプルメッセージです"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/broadcast-message/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "これはサンプルメッセージです"
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "これはサンプルメッセージです"
};
axios.post("https://api.maiagent.ai/api/v1/contacts/broadcast-message/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/broadcast-message/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "これはサンプルメッセージです"
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/contacts/broadcast-message/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'contactIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'inboxId' => '550e8400-e29b-41d4-a716-446655440000',
'excludeContactIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'message' => 'これはサンプルメッセージです'
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"results"?: [ // 任意
{
"contactId"?: string (uuid) // 任意
"conversationId"?: string (uuid) // 任意
"messageId"?: string (uuid) // 任意
"status"?: string // 任意
}
]
"errors"?: [ // 任意
{
"contactId"?: string (uuid) // 任意
"error"?: string // 任意
}
]
"totalContacts"?: integer // 任意
"successCount"?: integer // 任意
"errorCount"?: integer // 任意
}
```
**レスポンスの値の例**
```json
{
"results": [
{
"contactId": "550e8400-e29b-41d4-a716-446655440000",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"messageId": "550e8400-e29b-41d4-a716-446655440000",
"status": "success"
}
],
"errors": [
{
"contactId": "550e8400-e29b-41d4-a716-446655440000",
"error": "レスポンス文字列"
}
],
"totalContacts": 456,
"successCount": 456,
"errorCount": 456
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の API 認証情報を作成
POST `/api/v1/contacts/{id}/api-credentials/`
{% hint style="info" %}
Agent がこの連絡先として API ツールを呼び出せるようにします。手順は技術マニュアルの[連絡先の認証情報の同期](https://docs.maiagent.ai/tech/authorization-integration/contact-credentials-sync)をご覧ください。
{% endhint %}
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ------- | ------------- | --- | -------------- |
| tool | string (uuid) | はい | API ツールの ID です |
| headers | object | いいえ | 認証ヘッダーの辞書です |
**リクエストスキーマの例**
```typescript
{
"tool": string (uuid) // API ツールの ID です
"headers"?: object // 認証ヘッダーの辞書です (任意)
}
```
**リクエストの値の例**
```json
{
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
};
axios.post("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'tool' => '550e8400-e29b-41d4-a716-446655440000',
'headers' => new \stdClass()
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 201**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定されている場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスに対応します (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID：呼び出し元システムのユーザー ID です。組織内で一意です（削除済みの連絡先は除きます）。元の文字列との完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの値で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを利用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることをお勧めします (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外または指定項目のみの選択に使います） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方指定された場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外または指定項目のみの選択に使います） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツから一覧の項目を除外し、false は一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // ラベルのフィルター条件です。conditions が空配列の場合、ラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定すると、ナレッジベース検索にラベルのフィルターが適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です
"conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応します (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先のコネクタの OAuth 認可一覧です（トークン本体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes のチャット開始前フォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングを使い、フロントエンドで metadata の UUID キーを表示名に変換します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 400 - No response body**
***
### 連絡先の API 認証情報を更新
PATCH `/api/v1/contacts/{id}/api-credentials/{credentialId}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| -------------- | -- | ------ | --------------------------------------- |
| `credentialId` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ------- | ------ | --- | ----------- |
| headers | object | いいえ | 認証ヘッダーの辞書です |
**リクエストスキーマの例**
```typescript
{
"headers"?: object // 認証ヘッダーの辞書です (任意)
}
```
**リクエストの値の例**
```json
{
"headers": {}
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"headers": {}
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"headers": {}
};
axios.patch("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"headers": {}
}
response = requests.patch(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'headers' => new \stdClass()
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 省略可
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定された場合、このフィールドは無視されます (省略可)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型になる場合があります (省略可)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (省略可)
"phoneNumber"?: string // 省略可
"email"?: // 異なる型になる場合があります (省略可)
string (email) // 省略可
"sourceId"?: string // 省略可
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定します。同じ組織内で一意である必要があります（削除済みの連絡先を除きます）。元の文字列との完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID を使って連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることをお勧めします (省略可)
"queryMetadata"?: { // 検索メタデータです。検索可能なナレッジの範囲を制御します。詳細は各エンドポイントの説明を参照してください (省略可)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしです (省略可)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象となります） (省略可)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方が指定された場合はこのフィールドが優先されます） (省略可)
string (uuid)
]
"faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象となります） (省略可)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツを選択し、リスト内の項目を除外します。false の場合はリスト内の項目のみを選択します (省略可)
}
]
"labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグによる絞り込みを行いません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にタグフィルターは適用されません（制限なしと同じです） (省略可)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です
"conditions"?: [ // タグ条件のリストです。operator/conditions のネストに対応しています (省略可)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (省略可)
"mcpCredentials": [ // 連絡先の MCP 認証情報のリストです
object
]
"apiCredentials": [ // 連絡先の API 認証情報のリストです
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可のリストです（トークン自体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が属する inboxes の pre-chat form フィールド設定です。マッピングは {field_id: {label: {locale: text}}} で、フロントエンドが metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスのサンプル値**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 404 - No response body**
***
### 連絡先の API 認証情報の削除
DELETE `/api/v1/contacts/{id}/api-credentials/{credentialId}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| -------------- | -- | ------ | --------------------------------------- |
| `credentialId` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```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/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/", data, config)
.then(response => {
console.log('レスポンスを正常に取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラー:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラー:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/api-credentials/{credentialId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス
| ステータスコード | 説明 |
| -------- | ---------------- |
| 204 | No response body |
| 404 | No response body |
***
### 連絡先の MCP 認証情報を作成
POST `/api/v1/contacts/{id}/mcp-credentials/`
#### パラメーター
| パラメーター名 | 必須 | 型 | 説明 |
| ------- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメーター**
| フィールド | 型 | 必須 | 説明 |
| ------- | ------------- | --- | ----------- |
| tool | string (uuid) | はい | MCP ツールの ID |
| headers | object | いいえ | 認証ヘッダーの辞書 |
**リクエストスキーマの例**
```typescript
{
"tool": string (uuid) // MCP ツールの ID
"headers"?: object // 認証ヘッダーの辞書 (任意)
}
```
**リクエスト値の例**
```json
{
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
};
axios.post("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"tool": "550e8400-e29b-41d4-a716-446655440000",
"headers": {}
}
response = requests.post(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'tool' => '550e8400-e29b-41d4-a716-446655440000',
'headers' => new \stdClass()
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 201**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定された場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定し、同じ組織内で一意である必要があります（削除済みの連絡先を除きます）。元の文字列と完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムを示すプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしです (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、指定項目を除外するか、指定項目のみを選択します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、指定項目を除外するか、指定項目のみを選択します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツから一覧の項目を除外して選択し、false の場合は一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグのフィルター条件です。conditions が空配列の場合はタグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にタグフィルターは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可の一覧です（トークン本体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が所属する inboxes の事前チャットフォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングで、フロントエンドが metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 400 - No response body**
***
### 連絡先の MCP 認証情報を更新
PATCH `/api/v1/contacts/{id}/mcp-credentials/{credentialId}/`
#### パラメーター
| パラメーター名 | 必須 | 型 | 説明 |
| -------------- | -- | ------ | --------------------------------------- |
| `credentialId` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### リクエストボディ
**リクエストパラメーター**
| フィールド | 型 | 必須 | 説明 |
| ------- | ------ | --- | --------- |
| headers | object | いいえ | 認証ヘッダーの辞書 |
**リクエストスキーマの例**
```typescript
{
"headers"?: object // 認証ヘッダーの辞書 (任意)
}
```
**リクエスト値の例**
```json
{
"headers": {}
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"headers": {}
}'
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// リクエストボディ (payload)
const data = {
"headers": {}
};
axios.patch("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/", data, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラーが発生しました:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"headers": {}
}
response = requests.patch(url, json=data, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラーが発生しました:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'headers' => new \stdClass()
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定された場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスを指定できます (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定し、同じ組織内で一意である必要があります（削除済みの連絡先を除きます）。元の文字列と完全一致で照合し、大文字と小文字を区別します。会話 API の message.externalUser.id はこの ID で連絡先を検索します。空文字列または空白のみの場合は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムを示すプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしです (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、指定項目を除外するか、指定項目のみを選択します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、指定項目を除外するか、指定項目のみを選択します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツから一覧の項目を除外して選択し、false の場合は一覧の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグのフィルター条件です。conditions が空配列の場合はタグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にタグフィルターは適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です
"conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報の一覧です
object
]
"apiCredentials": [ // 連絡先の API 認証情報の一覧です
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可の一覧です（トークン本体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が所属する inboxes の事前チャットフォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングで、フロントエンドが metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスの名前の例",
"description": "レスポンスの説明の例"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 404 - No response body**
***
### 連絡先の MCP 認証情報の削除
DELETE `/api/v1/contacts/{id}/mcp-credentials/{credentialId}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| -------------- | -- | ------ | --------------------------------------- |
| `credentialId` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```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/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/", data, config)
.then(response => {
console.log('レスポンスを正常に取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラー:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("レスポンスを正常に取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラー:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/mcp-credentials/{credentialId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス
| ステータスコード | 説明 |
| -------- | ---------------- |
| 204 | No response body |
| 404 | No response body |
***
### 連絡先の一括インポート用テンプレートをダウンロード
GET `/api/v1/contacts/bulk-import-template/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/bulk-import-template/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/contacts/bulk-import-template/", config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラー:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/bulk-import-template/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラー:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/contacts/bulk-import-template/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定した場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスに対応しています (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定します。同じ組織内で一意である必要があります（削除済みの連絡先は除きます）。元の文字列を大文字と小文字を区別して完全一致で照合します。会話 API の message.externalUser.id はこの ID を使って連絡先を検索します。空文字列または空白のみの文字列は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御する検索メタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空配列または null はすべて検索不可（権限なし）を意味し、省略した場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目を指定します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目を指定します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツからリスト内の項目を除外して選択します。false はリスト内の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグのフィルター条件です。conditions が空配列の場合、タグによる絞り込みは行いません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にはタグフィルターが適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件のリストです。operator/conditions のネストした組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報のリスト
object
]
"apiCredentials": [ // 連絡先の API 認証情報のリスト
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可のリストです（トークン本体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が所属する inboxes のチャット前フォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングで、フロントエンドが metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
### 連絡先の一括インポート
POST `/api/v1/contacts/bulk-import/`
{% hint style="info" %}
テンプレートに沿って入力した Excel ファイルをアップロードしてください。`dry_run=true` を指定すると、データを書き込まずに、作成または更新される件数のみを返します（`201` ではなく `200` を返します）。
{% endhint %}
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/bulk-import/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// FormData オブジェクトを作成します
const formData = new FormData();
// フォームフィールドを追加します
// リクエストヘッダーを設定します
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/contacts/bulk-import/", formData, config)
.then(response => {
console.log('レスポンスを取得しました:');
console.log(response.data);
})
.catch(error => {
console.error('リクエストエラー:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/contacts/bulk-import/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# ファイルとフォームデータを作成します
files = {
'file': ('example.pdf', open('example.pdf', 'rb'), 'application/pdf')
}
response = requests.post(url, files=files, headers=headers)
try:
print("レスポンスを取得しました:")
print(response.json())
except Exception as e:
print("リクエストエラー:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/contacts/bulk-import/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example.pdf', 'r'),
'filename' => 'example.pdf'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンススキーマの例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 互換性維持用のフィールドです。単一の inbox を指定します。inboxes も指定した場合、このフィールドは無視されます (任意)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: // 異なる型を取る場合があります (任意)
string (uri) // 連絡先のアバター URL です。完全な URL または相対パスに対応しています (任意)
"phoneNumber"?: string // 任意
"email"?: // 異なる型を取る場合があります (任意)
string (email) // 任意
"sourceId"?: string // 任意
"externalId"?: string // 外部ユーザー ID です。呼び出し元システムのユーザー ID を指定します。同じ組織内で一意である必要があります（削除済みの連絡先は除きます）。元の文字列を大文字と小文字を区別して完全一致で照合します。会話 API の message.externalUser.id はこの ID を使って連絡先を検索します。空文字列または空白のみの文字列は 400 を返します。値をクリアするには null を指定してください。複数の外部システムを使用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることを推奨します (任意)
"queryMetadata"?: { // 検索可能なナレッジの範囲を制御する検索メタデータです。詳細は各エンドポイントの説明を参照してください (任意)
{
"knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空配列または null はすべて検索不可（権限なし）を意味し、省略した場合は制限しません (任意)
{
"knowledgeBaseId": string (uuid) // ナレッジベース ID
"chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目を指定します） (任意)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意)
string (uuid)
]
"faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目を指定します） (任意)
string (uuid)
]
"hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツからリスト内の項目を除外して選択します。false はリスト内の項目のみを選択します (任意)
}
]
"labelRelations"?: { // タグのフィルター条件です。conditions が空配列の場合、タグによる絞り込みは行いません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にはタグフィルターが適用されません（制限なしと同じです） (任意)
{
"operator": string (enum: AND, OR) // タグ条件の組み合わせ方法
"conditions"?: [ // タグ条件のリストです。operator/conditions のネストした組み合わせに対応しています (任意)
object
]
}
}
}
}
"metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意)
"mcpCredentials": [ // 連絡先の MCP 認証情報のリスト
object
]
"apiCredentials": [ // 連絡先の API 認証情報のリスト
object
]
"contactConnectors": [ // 連絡先の Connector OAuth 認可のリストです（トークン本体は含みません）
object
]
"tags": [
{
"id": string (uuid)
"name": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"preChatFieldIndex": object // この Contact が所属する inboxes のチャット前フォームのフィールド設定です。{field_id: {label: {locale: text}}} のマッピングで、フロントエンドが metadata の UUID キーを表示名に変換するために使用します
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**レスポンスの値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"inboxes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"name": "レスポンス文字列",
"avatar": "https://example.com/file.jpg",
"phoneNumber": "レスポンス文字列",
"email": "response@example.com",
"sourceId": "レスポンス文字列",
"externalId": "レスポンス文字列",
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"metadata": null,
"mcpCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"apiCredentials": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"contactConnectors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
}
],
"tags": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"preChatFieldIndex": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンスのサンプル名",
"description": "レスポンスのサンプル説明"
},
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**
***
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/ja/api-reference/lian-luo-ren.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.