> 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 | 複数の値はカンマで区切って指定できます。 |
| `inbox` | ❌ | string | 非推奨です。代わりに inboxes を使用してください |
| `inboxes` | ❌ | string | 会話プラットフォーム ID (特定の inbox の連絡先を絞り込むために使用します) |
| `page` | ❌ | integer | ページ分割された結果セット内のページ番号です。 |
| `pageSize` | ❌ | integer | 1 ページあたりに返す結果の件数です。 |
| `query` | ❌ | string | 名前またはソース ID で検索します |
| `search` | ❌ | string | 全文検索 |
| `tags` | ❌ | array | 複数の値はカンマで区切って指定できます。 |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/?channels=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&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&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&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 // 任意
"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 // 会話ページの顧客パネルに表示するカスタム顧客情報です (任意)
"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
{
"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"
}
]
]
}
```
***
### 連絡先の作成
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 // 任意
"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 // 会話ページの顧客パネルに表示するカスタム顧客情報です (任意)
"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"
}
```
***
### 連絡先の詳細取得
GET `/api/v1/contacts/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | ---------------------------- |
| `id` | ✅ | string | この Contact を識別する UUID 文字列です。 |
#### コード例
{% 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 // 任意
"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 // 会話ページの顧客パネルに表示するカスタム顧客情報です (任意)
"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"
}
```
***
### 連絡先の詳細取得
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 // 任意
"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 のフィールド設定です。mapping {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": "レスポンス文字列",
"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": "レスポンス文字列"
}
```
***
### 連絡先の詳細を取得
GET `/api/v1/contacts/connector-management/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/connector-management/" \
-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/connector-management/", 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/connector-management/"
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/connector-management/", [
'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 | No response body |
***
### 連絡先を更新
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 // 任意
"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 のフィールド設定です。mapping {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"
}
```
***
### 連絡先を部分更新
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 // 任意
"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"
}
```
***
### 連絡先の削除
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. |
| `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&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&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&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&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
]
}
"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.
"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
"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": object
"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 です。引き継ぎの切り替え設定とは独立しています）
}
]
}
```
**レスポンス値の例**
```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": [
"レスポンス文字列"
]
},
"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,
"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
}
]
}
```
***
### 連絡先の最新の会話を取得
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
]
}
"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.
"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
"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": object
"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 です。引き継ぎの切り替え設定とは独立しています）
}
```
**レスポンスの値の例**
```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": [
"レスポンス文字列"
]
},
"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,
"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
}
```
**ステータスコード: 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"?: [ // 任意
{
"contact_id"?: string (uuid) // 任意
"conversation_id"?: string (uuid) // 任意
"message_id"?: string (uuid) // 任意
"status"?: string // 任意
}
]
"errors"?: [ // 任意
{
"contact_id"?: string (uuid) // 任意
"error"?: string // 任意
}
]
"total_contacts"?: integer // 任意
"success_count"?: integer // 任意
"error_count"?: integer // 任意
}
```
**レスポンスの値の例**
```json
{
"results": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "success"
}
],
"errors": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"error": "レスポンス文字列"
}
],
"total_contacts": 456,
"success_count": 456,
"error_count": 456
}
```
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the 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 `build a script that syncs our docs to a CMS` 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.