連絡先

連絡先一覧の取得

GET /api/contacts/

パラメータ

パラメータ名	必須	型	説明
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	全文検索

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "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"?: object // 任意
      "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
      "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}

レスポンスサンプル値

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    [
      {
        "id": "user1_uuid",
        "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": "self defined query metadata",
        "createdAt": "1751875400000",
        "updatedAt": "1751875400000"
      }
    ]
  ]
}

---

連絡先一覧の取得

GET /api/v1/contacts/

パラメータ

パラメータ名	必須	型	説明
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	全文検索

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "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"?: object // 任意
      "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
      "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}

レスポンスサンプル値

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    [
      {
        "id": "user1_uuid",
        "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": "self defined query metadata",
        "createdAt": "1751875400000",
        "updatedAt": "1751875400000"
      }
    ]
  ]
}

---

連絡先の作成

POST /api/contacts/

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/contacts/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "inbox_uuid"
      }
    ],
    "name": "user1",
    "avatar": "",
    "phoneNumber": 912345678,
    "email": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/contacts/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

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

# リクエスト内容 (payload)
data = {
      "inboxes": [
        {
          "id": "inbox_uuid"
        }
      ],
      "name": "user1",
      "avatar": "",
      "phoneNumber": 912345678,
      "email": "[e-mail]",
      "sourceId": "self defined source id",
      "queryMetadata": "self defined query metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/contacts/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "inbox_uuid"
                }
            ],
            "name": "user1",
            "avatar": "",
            "phoneNumber": 912345678,
            "email": "[e-mail]",
            "sourceId": "self defined source id",
            "queryMetadata": "self defined query metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 201

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先の作成

POST /api/v1/contacts/

コード例

Shell/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": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata",
    "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);
  });

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": "[e-mail]",
      "sourceId": "self defined source id",
      "queryMetadata": "self defined query metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "sourceId": "self defined source id",
            "queryMetadata": "self defined query metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 201

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先詳細の取得

GET /api/contacts/{id}/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.

コード例

Shell/Bash

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

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "id": string (uuid)
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先詳細の取得

GET /api/v1/contacts/{id}/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.

コード例

Shell/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 を置き換え、リクエストデータをご確認ください。

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);
  });

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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先の更新

PUT /api/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
sourceId	string	いいえ	ソース ID
queryMetadata	string	いいえ	クエリメタデータ
metadata	array[object]	いいえ	カスタム連絡先属性リスト

リクエスト構造例

{
  "name"?: string // 連絡先の氏名 (任意)
  "inboxes"?: [ // 会話プラットフォームリスト（新版形式） (任意)
    {
      "id": string (uuid) // 会話プラットフォーム ID
    }
  ]
  "inbox"?: { // 単一の会話プラットフォーム（旧版形式、下位互換用） (任意)
  {
    "id": string (uuid) // 会話プラットフォーム ID
  }
  }
  "avatar"?: string // アバター URL (任意)
  "sourceId"?: string // ソース ID (任意)
  "queryMetadata"?: string // クエリメタデータ (任意)
  "metadata"?: [ // カスタム連絡先属性リスト (任意)
    {
      "key": string // 属性名
      "value": string // 属性値
      "updatedAt"?: string // 更新日時（ISO 形式、任意。未指定の場合は自動的に補完されます） (任意)
    }
  ]
}

リクエストサンプル値

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "顧客ランク",
      "value": "VVIP"
    },
    {
      "key": "希望言語",
      "value": "日本語"
    }
  ]
}

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  };

axios.put("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエスト内容 (payload)
data = {
      "inboxes": [
        {
          "id": "new_inbox_uuid"
        }
      ],
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "phoneNumber": 987654321,
      "email": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "new_inbox_uuid"
                }
            ],
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "phoneNumber": 987654321,
            "email": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VVIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先の更新

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
sourceId	string	いいえ	ソース ID
queryMetadata	string	いいえ	クエリメタデータ
metadata	array[object]	いいえ	カスタム連絡先属性リスト

リクエスト構造例

{
  "name"?: string // 連絡先の氏名 (任意)
  "inboxes"?: [ // 会話プラットフォームリスト（新版形式） (任意)
    {
      "id": string (uuid) // 会話プラットフォーム ID
    }
  ]
  "inbox"?: { // 単一の会話プラットフォーム（旧版形式、下位互換用） (任意)
  {
    "id": string (uuid) // 会話プラットフォーム ID
  }
  }
  "avatar"?: string // アバター URL (任意)
  "sourceId"?: string // ソース ID (任意)
  "queryMetadata"?: string // クエリメタデータ (任意)
  "metadata"?: [ // カスタム連絡先属性リスト (任意)
    {
      "key": string // 属性名
      "value": string // 属性値
      "updatedAt"?: string // 更新日時（ISO 形式、任意。未指定の場合は自動的に補完されます） (任意)
    }
  ]
}

リクエストサンプル値

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "顧客ランク",
      "value": "VVIP"
    },
    {
      "key": "希望言語",
      "value": "日本語"
    }
  ]
}

コード例

Shell/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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "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);
  });

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": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VVIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先の部分更新

PATCH /api/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
sourceId	string	いいえ	ソース ID
queryMetadata	string	いいえ	クエリメタデータ
metadata	array[object]	いいえ	カスタム連絡先属性リスト

リクエスト構造例

{
  "name"?: string // 連絡先の氏名 (任意)
  "inboxes"?: [ // 会話プラットフォームリスト（新版形式） (任意)
    {
      "id": string (uuid) // 会話プラットフォーム ID
    }
  ]
  "inbox"?: { // 単一の会話プラットフォーム（旧版形式、下位互換用） (任意)
  {
    "id": string (uuid) // 会話プラットフォーム ID
  }
  }
  "avatar"?: string // アバター URL (任意)
  "sourceId"?: string // ソース ID (任意)
  "queryMetadata"?: string // クエリメタデータ (任意)
  "metadata"?: [ // カスタム連絡先属性リスト (任意)
    {
      "key": string // 属性名
      "value": string // 属性値
      "updatedAt"?: string // 更新日時（ISO 形式、任意。未指定の場合は自動的に補完されます） (任意)
    }
  ]
}

リクエストサンプル値

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "顧客ランク",
      "value": "VVIP"
    },
    {
      "key": "希望言語",
      "value": "日本語"
    }
  ]
}

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  };

axios.patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエスト内容 (payload)
data = {
      "inboxes": [
        {
          "id": "new_inbox_uuid"
        }
      ],
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "phoneNumber": 987654321,
      "email": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "new_inbox_uuid"
                }
            ],
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "phoneNumber": 987654321,
            "email": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VVIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "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
sourceId	string	いいえ	ソース ID
queryMetadata	string	いいえ	クエリメタデータ
metadata	array[object]	いいえ	カスタム連絡先属性リスト

リクエスト構造例

{
  "name"?: string // 連絡先の氏名 (任意)
  "inboxes"?: [ // 会話プラットフォームリスト（新版形式） (任意)
    {
      "id": string (uuid) // 会話プラットフォーム ID
    }
  ]
  "inbox"?: { // 単一の会話プラットフォーム（旧版形式、下位互換用） (任意)
  {
    "id": string (uuid) // 会話プラットフォーム ID
  }
  }
  "avatar"?: string // アバター URL (任意)
  "sourceId"?: string // ソース ID (任意)
  "queryMetadata"?: string // クエリメタデータ (任意)
  "metadata"?: [ // カスタム連絡先属性リスト (任意)
    {
      "key": string // 属性名
      "value": string // 属性値
      "updatedAt"?: string // 更新日時（ISO 形式、任意。未指定の場合は自動的に補完されます） (任意)
    }
  ]
}

リクエストサンプル値

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "顧客ランク",
      "value": "VVIP"
    },
    {
      "key": "希望言語",
      "value": "日本語"
    }
  ]
}

コード例

Shell/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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "顧客ランク",
        "value": "VVIP"
      },
      {
        "key": "希望言語",
        "value": "日本語"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "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);
  });

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": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata",
      "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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata",
            "metadata": [
                {
                    "key": "顧客ランク",
                    "value": "VVIP"
                },
                {
                    "key": "希望言語",
                    "value": "日本語"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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"?: object // 任意
  "metadata"?: object // カスタムの顧客情報。会話ページの顧客情報セクションに表示されます (任意)
  "mcpCredentials": string // 連絡先の MCP 認証クレデンシャルのリスト
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

連絡先の削除

DELETE /api/contacts/{id}/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.

コード例

Shell/Bash

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

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// リクエスト内容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード	説明
204	No response body
400	連絡先に関連する会話が残っているため、削除できません

---

連絡先の削除

DELETE /api/v1/contacts/{id}/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.

コード例

Shell/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 を置き換え、リクエストデータをご確認ください。

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);
  });

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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

レスポンス内容

ステータスコード	説明
204	No response body
400	連絡先に関連する会話が残っているため、削除できません

---

連絡先の会話一覧の取得

GET /api/contacts/{id}/conversations/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.
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

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "contact": { // Conversation List view 用の軽量級 Contact Serializer。

List view に必要なフィールドのみを含み、N+1 クエリ問題を避けるために
inboxes と mcp_credentials を除外しています
      {
        "id": string (uuid)
        "name": string
        "avatar"?: string (uri) // 任意
        "sourceId"?: string // 任意
      }
      }
      "inbox": {
      {
        "id": string (uuid)
        "name": string
        "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
        "unreadConversationsCount"?: integer // 任意
        "signAuth"?:  // 任意
        {
          "id": string (uuid)
          "signSource": string (uuid)
          "signParams": {
          {
            "keycloak": 
            {
              "clientId": string
              "url": string
              "realm": string
            }
            "line": 
            {
              "liffId": string
            }
            "ad": 
            {
              "saml": string
            }
          }
          }
        }
      }
      }
      "title": string
      "lastMessage"?: { // 任意
      {
        "id": string (uuid)
        "type"?: string // 任意
        "content"?: string // 任意
        "contentPayload"?: object // 任意
        "feedback": 
        {
          "id": string (uuid)
          "type": 
          {
          }
          "suggestion"?: string // 任意
          "updatedAt": string (timestamp)
        }
        "createdAt": string (timestamp)
        "queryMetadata"?: object // 任意
      }
      }
      "lastMessageCreatedAt": string (timestamp)
      "unreadMessagesCount": integer
      "autoReplyEnabled": boolean
      "isAutoReplyNow": boolean
      "lastReadAt": string (timestamp)
      "createdAt": string (timestamp)
      "isGroupChat": boolean
      "enableGroupMention"?: boolean // 任意
      "queryMetadata"?: object // 任意
      "toolMask"?: object // 各ツールの有効/無効状態を記録 {tool_id: bool} (任意)
      "connectorMask"?: object // 各コネクタの有効/無効状態を記録 {connector_id: bool} (任意)
      "thinkingConfig"?: object // None=未設定(chatbot の設定を使用), {}=明示的に無効, {...}=カスタム上書き (任意)
      "thinkingConfigSchema": object
      "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.
      "llm": string (uuid)
      "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
      {
      }
      "ipAddress": string
      "ipCountryCode": string
      "ipRecordedAt": string (timestamp)
    }
  ]
}

レスポンスサンプル値

{
  "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": "https://example.com/file.jpg",
        "sourceId": "レスポンス文字列"
      },
      "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": "レスポンス文字列"
            }
          }
        }
      },
      "title": "レスポンス文字列",
      "lastMessage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "レスポンス文字列",
        "content": "レスポンス文字列",
        "contentPayload": null,
        "feedback": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "suggestion": "レスポンス文字列",
          "updatedAt": "レスポンス文字列"
        },
        "createdAt": "レスポンス文字列",
        "queryMetadata": null
      },
      "lastMessageCreatedAt": "レスポンス文字列",
      "unreadMessagesCount": 456,
      "autoReplyEnabled": false,
      "isAutoReplyNow": false,
      "lastReadAt": "レスポンス文字列",
      "createdAt": "レスポンス文字列",
      "isGroupChat": false,
      "enableGroupMention": false,
      "queryMetadata": null,
      "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": {},
      "ipAddress": "レスポンス文字列",
      "ipCountryCode": "レスポンス文字列",
      "ipRecordedAt": "レスポンス文字列"
    }
  ]
}

---

連絡先の会話一覧の取得

GET /api/v1/contacts/{id}/conversations/

パラメータ

パラメータ名	必須	型	説明
id	✅	string	A UUID string identifying this Contact.
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

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "contact": { // Conversation List view 用の軽量級 Contact Serializer。

List view に必要なフィールドのみを含み、N+1 クエリ問題を避けるために
inboxes と mcp_credentials を除外しています
      {
        "id": string (uuid)
        "name": string
        "avatar"?: string (uri) // 任意
        "sourceId"?: string // 任意
      }
      }
      "inbox": {
      {
        "id": string (uuid)
        "name": string
        "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
        "unreadConversationsCount"?: integer // 任意
        "signAuth"?:  // 任意
        {
          "id": string (uuid)
          "signSource": string (uuid)
          "signParams": {
          {
            "keycloak": 
            {
              "clientId": string
              "url": string
              "realm": string
            }
            "line": 
            {
              "liffId": string
            }
            "ad": 
            {
              "saml": string
            }
          }
          }
        }
      }
      }
      "title": string
      "lastMessage"?: { // 任意
      {
        "id": string (uuid)
        "type"?: string // 任意
        "content"?: string // 任意
        "contentPayload"?: object // 任意
        "feedback": 
        {
          "id": string (uuid)
          "type": 
          {
          }
          "suggestion"?: string // 任意
          "updatedAt": string (timestamp)
        }
        "createdAt": string (timestamp)
        "queryMetadata"?: object // 任意
      }
      }
      "lastMessageCreatedAt": string (timestamp)
      "unreadMessagesCount": integer
      "autoReplyEnabled": boolean
      "isAutoReplyNow": boolean
      "lastReadAt": string (timestamp)
      "createdAt": string (timestamp)
      "isGroupChat": boolean
      "enableGroupMention"?: boolean // 任意
      "queryMetadata"?: object // 任意
      "toolMask"?: object // 各ツールの有効/無効状態を記録 {tool_id: bool} (任意)
      "connectorMask"?: object // 各コネクタの有効/無効状態を記録 {connector_id: bool} (任意)
      "thinkingConfig"?: object // None=未設定(chatbot の設定を使用), {}=明示的に無効, {...}=カスタム上書き (任意)
      "thinkingConfigSchema": object
      "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.
      "llm": string (uuid)
      "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
      {
      }
      "ipAddress": string
      "ipCountryCode": string
      "ipRecordedAt": string (timestamp)
    }
  ]
}

レスポンスサンプル値

{
  "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": "https://example.com/file.jpg",
        "sourceId": "レスポンス文字列"
      },
      "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": "レスポンス文字列"
            }
          }
        }
      },
      "title": "レスポンス文字列",
      "lastMessage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "レスポンス文字列",
        "content": "レスポンス文字列",
        "contentPayload": null,
        "feedback": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "suggestion": "レスポンス文字列",
          "updatedAt": "レスポンス文字列"
        },
        "createdAt": "レスポンス文字列",
        "queryMetadata": null
      },
      "lastMessageCreatedAt": "レスポンス文字列",
      "unreadMessagesCount": 456,
      "autoReplyEnabled": false,
      "isAutoReplyNow": false,
      "lastReadAt": "レスポンス文字列",
      "createdAt": "レスポンス文字列",
      "isGroupChat": false,
      "enableGroupMention": false,
      "queryMetadata": null,
      "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": {},
      "ipAddress": "レスポンス文字列",
      "ipCountryCode": "レスポンス文字列",
      "ipRecordedAt": "レスポンス文字列"
    }
  ]
}

---

連絡先の最新会話の取得

GET /api/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	会話内のメッセージ内容を検索（大文字・小文字を区別しない）

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータをご確認ください。

JavaScript

const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/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);
  });

Python

import requests

url = "https://api.maiagent.ai/api/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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/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();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "id": string (uuid)
  "contact": { // Conversation List view 用の軽量級 Contact Serializer。

List view に必要なフィールドのみを含み、N+1 クエリ問題を避けるために
inboxes と mcp_credentials を除外しています
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 任意
    "sourceId"?: string // 任意
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
    "unreadConversationsCount"?: integer // 任意
    "signAuth"?:  // 任意
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
  }
  }
  "title": string
  "lastMessage"?: { // 任意
  {
    "id": string (uuid)
    "type"?: string // 任意
    "content"?: string // 任意
    "contentPayload"?: object // 任意
    "feedback": 
    {
      "id": string (uuid)
      "type": 
      {
      }
      "suggestion"?: string // 任意
      "updatedAt": string (timestamp)
    }
    "createdAt": string (timestamp)
    "queryMetadata"?: object // 任意
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // 任意
  "queryMetadata"?: object // 任意
  "toolMask"?: object // 各ツールの有効/無効状態を記録 {tool_id: bool} (任意)
  "connectorMask"?: object // 各コネクタの有効/無効状態を記録 {connector_id: bool} (任意)
  "thinkingConfig"?: object // None=未設定(chatbot の設定を使用), {}=明示的に無効, {...}=カスタム上書き (任意)
  "thinkingConfigSchema": object
  "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.
  "llm": string (uuid)
  "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
  {
  }
  "ipAddress": string
  "ipCountryCode": string
  "ipRecordedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンス文字列",
    "avatar": "https://example.com/file.jpg",
    "sourceId": "レスポンス文字列"
  },
  "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": "レスポンス文字列"
        }
      }
    }
  },
  "title": "レスポンス文字列",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "レスポンス文字列",
    "content": "レスポンス文字列",
    "contentPayload": null,
    "feedback": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "suggestion": "レスポンス文字列",
      "updatedAt": "レスポンス文字列"
    },
    "createdAt": "レスポンス文字列",
    "queryMetadata": null
  },
  "lastMessageCreatedAt": "レスポンス文字列",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "isGroupChat": false,
  "enableGroupMention": false,
  "queryMetadata": null,
  "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": {},
  "ipAddress": "レスポンス文字列",
  "ipCountryCode": "レスポンス文字列",
  "ipRecordedAt": "レスポンス文字列"
}

ステータスコード: 404 - No response body

---

連絡先の最新会話の取得

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	会話内のメッセージ内容を検索（大文字・小文字を区別しない）

コード例

Shell/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 を置き換え、リクエストデータをご確認ください。

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);
  });

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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "id": string (uuid)
  "contact": { // Conversation List view 用の軽量級 Contact Serializer。

List view に必要なフィールドのみを含み、N+1 クエリ問題を避けるために
inboxes と mcp_credentials を除外しています
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 任意
    "sourceId"?: string // 任意
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
    "unreadConversationsCount"?: integer // 任意
    "signAuth"?:  // 任意
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
  }
  }
  "title": string
  "lastMessage"?: { // 任意
  {
    "id": string (uuid)
    "type"?: string // 任意
    "content"?: string // 任意
    "contentPayload"?: object // 任意
    "feedback": 
    {
      "id": string (uuid)
      "type": 
      {
      }
      "suggestion"?: string // 任意
      "updatedAt": string (timestamp)
    }
    "createdAt": string (timestamp)
    "queryMetadata"?: object // 任意
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // 任意
  "queryMetadata"?: object // 任意
  "toolMask"?: object // 各ツールの有効/無効状態を記録 {tool_id: bool} (任意)
  "connectorMask"?: object // 各コネクタの有効/無効状態を記録 {connector_id: bool} (任意)
  "thinkingConfig"?: object // None=未設定(chatbot の設定を使用), {}=明示的に無効, {...}=カスタム上書き (任意)
  "thinkingConfigSchema": object
  "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.
  "llm": string (uuid)
  "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
  {
  }
  "ipAddress": string
  "ipCountryCode": string
  "ipRecordedAt": string (timestamp)
}

レスポンスサンプル値

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンス文字列",
    "avatar": "https://example.com/file.jpg",
    "sourceId": "レスポンス文字列"
  },
  "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": "レスポンス文字列"
        }
      }
    }
  },
  "title": "レスポンス文字列",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "レスポンス文字列",
    "content": "レスポンス文字列",
    "contentPayload": null,
    "feedback": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "suggestion": "レスポンス文字列",
      "updatedAt": "レスポンス文字列"
    },
    "createdAt": "レスポンス文字列",
    "queryMetadata": null
  },
  "lastMessageCreatedAt": "レスポンス文字列",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "isGroupChat": false,
  "enableGroupMention": false,
  "queryMetadata": null,
  "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": {},
  "ipAddress": "レスポンス文字列",
  "ipCountryCode": "レスポンス文字列",
  "ipRecordedAt": "レスポンス文字列"
}

ステータスコード: 404 - No response body

---

一斉送信

POST /api/contacts/broadcast-message/

リクエスト内容

リクエストパラメータ

フィールド	型	必須	説明
contactIds	array[string]	いいえ	[正方向指定モード] メッセージを送信する contact ID のリスト
inboxId	string (uuid)	いいえ	[逆方向除外/全件送信モード] Inbox ID。その inbox 配下のすべての contacts に送信されます
excludeContactIds	array[string]	いいえ	[逆方向除外モード] 除外する contact ID のリスト。inbox_id と併せて使用します
message	string	はい	送信するメッセージ内容

リクエスト構造例

{
  "contactIds"?: [ // [正方向指定モード] メッセージを送信する contact ID のリスト (任意)
    string (uuid)
  ]
  "inboxId"?: string (uuid) // [逆方向除外/全件送信モード] Inbox ID。その inbox 配下のすべての contacts に送信されます (任意)
  "excludeContactIds"?: [ // [逆方向除外モード] 除外する contact ID のリスト。inbox_id と併せて使用します (任意)
    string (uuid)
  ]
  "message": string // 送信するメッセージ内容
}

リクエストサンプル値

{
  "contactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "inboxId": "550e8400-e29b-41d4-a716-446655440000",
  "excludeContactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "message": "これはサンプルメッセージです"
}

コード例

Shell/Bash

# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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 を置き換え、リクエストデータをご確認ください。

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/contacts/broadcast-message/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/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();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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 // 任意
}

レスポンスサンプル値

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

---

一斉送信

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	はい	送信するメッセージ内容

リクエスト構造例

{
  "contactIds"?: [ // [正方向指定モード] メッセージを送信する contact ID のリスト (任意)
    string (uuid)
  ]
  "inboxId"?: string (uuid) // [逆方向除外/全件送信モード] Inbox ID。その inbox 配下のすべての contacts に送信されます (任意)
  "excludeContactIds"?: [ // [逆方向除外モード] 除外する contact ID のリスト。inbox_id と併せて使用します (任意)
    string (uuid)
  ]
  "message": string // 送信するメッセージ内容
}

リクエストサンプル値

{
  "contactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "inboxId": "550e8400-e29b-41d4-a716-446655440000",
  "excludeContactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "message": "これはサンプルメッセージです"
}

コード例

Shell/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 を置き換え、リクエストデータをご確認ください。

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);
  });

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)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

レスポンス内容

ステータスコード: 200

レスポンス構造例

{
  "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 // 任意
}

レスポンスサンプル値

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

---