> 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/dui-hua-he-xun-xi.md).
# 会話とメッセージ
### メッセージを送信（ストリーミング）
POST `/api/v1/chatbots/{chatbotId}/completions/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ----------- | -- | ------ | -- |
| `chatbotId` | ✅ | string | |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ---------------------- | ---------------------------------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversation | string (uuid) | いいえ | 会話の一意の識別子です。空の場合は新しい会話を作成します（任意） |
| message | object (8 個のプロパティを含む: content, contentPayload, queryMetadata...) | はい | 送信するメッセージの内容です |
| message.content | string | はい | メッセージのテキスト内容です。添付ファイルがある場合は空文字列にできます |
| message.contentPayload | object | いいえ | メッセージの追加コンテンツペイロードです。JSON 形式です（任意） |
| message.queryMetadata | object | いいえ | クエリメタデータです。JSON 形式です（任意） |
| message.metadata | object | いいえ | タイムゾーンなど、メッセージの環境メタデータです。JSON 形式です（任意） |
| message.attachments | array\[AttachmentInput] | いいえ | メッセージの添付ファイルリストです（任意） |
| message.toolIds | array\[string] | いいえ | このメッセージで有効にするツール ID のリストです（任意） |
| message.clientTools | array\[any] | いいえ | このメッセージでクライアント（Chrome extension など）が提供するツール定義のリストです（任意）。各項目には name(str)、description(str)、input\_schema(dict) が必要です。LLM 呼び出し時にバックエンドは実行せず、clientToolCall の内容を返してこのターンを終了します。 |
| message.sender | string (uuid) | いいえ | 送信者の Contact ID です（任意） |
| isStreaming | boolean | いいえ | ストリーミングモードで応答するかどうかを指定します。デフォルトは false です（任意） |
| waitForAttachments | boolean | いいえ | 添付ファイルの処理完了を待ってから agent workflow に進むかどうかを指定します。デフォルトは true です（任意） |
**リクエスト構造の例**
```typescript
{
"conversation"?: string (uuid) // 会話の一意の識別子です。空の場合は新しい会話を作成します（任意） (任意)
"message": // 送信するメッセージの内容です
{
"content": string // メッセージのテキスト内容です。添付ファイルがある場合は空文字列にできます
"contentPayload"?: object // メッセージの追加コンテンツペイロードです。JSON 形式です（任意） (任意)
"queryMetadata"?: object // クエリメタデータです。JSON 形式です（任意） (任意)
"metadata"?: object // タイムゾーンなど、メッセージの環境メタデータです。JSON 形式です（任意） (任意)
"attachments"?: [ // メッセージの添付ファイルリストです（任意） (任意)
{
"id": string (uuid) // 添付ファイルの一意の識別子です
"type": // 添付ファイルの種類です。指定可能な値：image（画像）、video（動画、開発中で未対応）、audio（音声）、sticker（ステッカー、開発中で未対応）、other（その他）
* `image` - Image
* `video` - Video
* `audio` - Audio
* `sticker` - Sticker
* `other` - Other
{
}
"filename": string // 添付ファイル名です
"file": string (uri) // 添付ファイルの URL です
}
]
"toolIds"?: [ // このメッセージで有効にするツール ID のリストです（任意） (任意)
string (uuid)
]
"clientTools"?: [ // このメッセージでクライアント（Chrome extension など）が提供するツール定義のリストです（任意）。各項目には name(str)、description(str)、input_schema(dict) が必要です。LLM 呼び出し時にバックエンドは実行せず、clientToolCall の内容を返してこのターンを終了します。 (任意)
object
]
"sender"?: string (uuid) // 送信者の Contact ID です（任意） (任意)
}
"isStreaming"?: boolean // ストリーミングモードで応答するかどうかを指定します。デフォルトは false です（任意） (任意)
"waitForAttachments"?: boolean // 添付ファイルの処理完了を待ってから agent workflow に進むかどうかを指定します。デフォルトは true です（任意） (任意)
}
```
**リクエスト値の例**
```json
{
"message": {
"content": "こんにちは、自己紹介をしてください"
},
"is_streaming": true
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": {
"content": "こんにちは、自己紹介をしてください"
},
"is_streaming": true
}'
# 実行前に 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 = {
"message": {
"content": "こんにちは、自己紹介をしてください"
},
"is_streaming": true
};
axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", 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/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ（payload）
data = {
"message": {
"content": "こんにちは、自己紹介をしてください"
},
"is_streaming": true
}
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/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"message": {
"content": "こんにちは、自己紹介をしてください"
},
"is_streaming": true
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
| ステータスコード | 説明 |
| -------- | -------------------------------------------------- |
| 200 | 会話の応答内容です。ストリーミングの場合はイベントストリームです |
| 400 | リクエストパラメータが不正です。Contact ID が該当する組織に属していない場合などがあります |
***
### メッセージを送信（作成）
POST `/api/v1/messages/`
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| --------------------------------------- | ------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| conversation | string (uuid) | はい | |
| type | string | いいえ | |
| content | string | いいえ | |
| contentPayload | object | いいえ | |
| attachments | array\[AttachmentCreateInput] | いいえ | |
| canvas | object | いいえ | |
| canvas.name | string | はい | |
| canvas.canvasType | object | はい | |
| canvas.title | string | はい | |
| canvas.content | string | はい | |
| slideTemplate | object (3 個のプロパティを含む: slug, displayName, thumbnailUrls) | いいえ | |
| slideTemplate.slug | string | はい | |
| slideTemplate.displayName | string | はい | |
| slideTemplate.thumbnailUrls | array\[string] | いいえ | |
| queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください |
| 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 | object | いいえ | Message metadata, such as timezone and other environment information |
| broadcast | boolean | いいえ | |
| skipCopilotTrigger | boolean | いいえ | |
| suggestedForId | string (uuid) | いいえ | |
| skillIds | array\[string] | いいえ | Per-message selected skill IDs from the WebChat client (camelCase: skillIds). |
| toolIds | array\[string] | いいえ | Per-message selected tool IDs from the WebChat client (camelCase: toolIds). |
| templateId | string (uuid) | いいえ | Document/sheet template ID for file-level compilation (camelCase: templateId). |
**リクエスト構造の例**
```typescript
{
"conversation": string (uuid)
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"attachments"?: [ // 任意
{
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"conversation"?: string (uuid) // 任意
}
]
"canvas"?: { // 任意
{
"name": string
"canvasType":
{
}
"title": string
"content": string
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"suggestedForId"?: string (uuid) // 任意
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
}
```
**リクエスト値の例**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システム構成図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
}
````
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
````bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/messages/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システム構成図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
}'
# 実行前に 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 = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システム構成図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
};
axios.post("https://api.maiagent.ai/api/v1/messages/", 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/messages/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ（payload）
data = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システム構成図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
}
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/messages/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システム構成図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
````
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 201**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"conversation": string (uuid)
"sender":
{
"id": string (uuid)
"name": string
"avatar": string
"email"?: string (email) // 任意
"phoneNumber"?: string // 任意
}
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"attachments"?: [ // 任意
{
"id": string (uuid)
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"expiresAt": string // ISO datetime when this attachment will be auto-deleted.
For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
"conversation"?: string (uuid) // 任意
}
]
"citations": [
{
"id": string (uuid)
"filename": string // ファイル名
"file": string (uri) // アップロードするファイル
"fileType": string
"knowledgeBase"?: // 任意
{
"id": string (uuid)
"name": string
}
"size": integer
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 任意
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (任意)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"previewUrl": string // プレゼンテーション（pptx/ppt）の場合は、プレビュー可能な派生 PDF ファイルの URL（フロントエンドの PDF ビューアーで表示）を返します。それ以外は None です。
`file` フィールドと同じ CustomizedFileFieldSerializer を使用して URL を生成し、各
storage provider の presign/host ルールを含めて形式を統一します。get_absolute_url() は誤った URL 形式を生成するため、使用しないでください。
"createdAt": string (timestamp)
}
]
"citationNodes": [
{
"chatbotTextNode": {
{
"id": string (uuid)
"charactersCount": integer
"hitsCount": integer
"text": string
"updatedAt": string (timestamp)
"filename": string
"chatbotFile": object // フロントエンドでの画像プレビューをサポートするため、ファイル URL とタイプを含む完全な ChatbotFile 情報を返します
"knowledgeBaseFile": object // get_chatbot_file と同じ内容を後方互換性のために提供します
"pageNumber": integer // Backward-compatible alias of ``page_start``.
"pageStart": integer
"pageEnd": integer
"citationTitle": string // inline citation のホバーカードに表示するソースタイトル
"citationDescription": string // inline citation のホバーカードに表示するソースの説明
"citationQuote": string // inline citation のホバーカードに表示する引用テキストの抜粋
"hasImage": boolean // 画像が含まれているかを判定します（ファイルタイプまたは text 内の Markdown 画像を確認します）
"imageUrl": string // 画像 URL を抽出します（ファイル URL を優先し、それ以外の場合は Markdown から抽出します）
"displayText": string // 画像の Markdown マークアップを削除した完全なテキストを返します
"displayTitle": string // 表示タイトルを返します（fallback: citation_title -> filename）
"highlightedText": string // Return text with matched terms wrapped in ```` tags.
Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // ユーザーは metadata の key と value を独自に定義できます (任意)
"metadataEnabledForSearch": object // Map each user-defined metadata key on this node to whether it was sent into the LLM.
A key reaches the LLM only when its ``MetadataKey.enabled_for_search`` is True *and*
the node carries a value for it. Since this maps over ``raw_user_define_metadata``
(the keys the cited-documents block displays, all of which have a value),
``enabled_for_search`` alone decides the flag. The source of truth is the node's
knowledge base ``MetadataKey`` current setting, matching the AI Search indicator.
"startCharIdx": integer
"endCharIdx": integer
}
}
"score"?: number (double) // 任意
"displayScore": integer
"citationNumber"?: integer // Citation number matching the [1], [2] markers in the reply content (任意)
"highlightedText"?: string // ES/OpenSearch highlight result with tags (任意)
}
]
"canvas"?: { // 任意
{
"id": string (uuid)
"name": string
"canvasType":
{
}
"title": string
"content": string
"createdAt": string (timestamp)
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"recordId": string // Message に対応する ChatbotRecord ID を返します
Note:
保存されていない Message（streaming 中の仮想 Message など）の場合は None を直接返し、
OneToOneField の逆リレーションに対する DB クエリの発生（N+1 問題）を回避します。
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"activeRevisionNumber": integer
"revisions": [
{
"id": string (uuid)
"revisionNumber": integer
"content": string
"contentPayload": object
"isActive": boolean
"createdAt": string (timestamp)
}
]
"suggestedForId"?: string (uuid) // 任意
"suggestionStatus": string
"suggestionTriggerSource": string
"suggestionError": string
"retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
"videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}
```
**レスポンス値の例**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
},
"type": "incoming",
"content": "これはテストメッセージです",
"contentPayload": {
"content": "これはテストメッセージです",
"items": [
{
"type": "text",
"text": "これはテストメッセージです",
"startTimestamp": null,
"citations": []
}
],
"metadata": null
},
"feedback": "like",
"createdAt": "1748314926000",
"attachments": [],
"citations": [],
"citationNodes": [],
"canvas": {
"id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
"name": "system-architecture-diagram",
"canvasType": "markdown",
"title": "システムアーキテクチャ図",
"content": "```mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンドインターフェース]\n B --> C[API レイヤー]\n C --> D[データベース]\n```",
"createdAt": "1748314926000"
}
}
````
***
### アウトゴーイングメッセージを送信
POST `/api/v1/messages/outgoing/`
#### リクエスト内容
**リクエストパラメータ**
| フィールド | タイプ | 必須 | 説明 |
| --------------------------------------- | ------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversation | string (uuid) | はい | |
| type | string | いいえ | |
| content | string | いいえ | |
| contentPayload | object | いいえ | |
| attachments | array\[AttachmentCreateInput] | いいえ | |
| canvas | object | いいえ | |
| canvas.name | string | はい | |
| canvas.canvasType | object | はい | |
| canvas.title | string | はい | |
| canvas.content | string | はい | |
| slideTemplate | object (3 つのプロパティを含む: slug, displayName, thumbnailUrls) | いいえ | |
| slideTemplate.slug | string | はい | |
| slideTemplate.displayName | string | はい | |
| slideTemplate.thumbnailUrls | array\[string] | いいえ | |
| queryMetadata | object | いいえ | 検索可能なナレッジ範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください |
| 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 | object | いいえ | Message metadata, such as timezone and other environment information |
| broadcast | boolean | いいえ | |
| skipCopilotTrigger | boolean | いいえ | |
| suggestedForId | string (uuid) | いいえ | |
| skillIds | array\[string] | いいえ | Per-message selected skill IDs from the WebChat client (camelCase: skillIds). |
| toolIds | array\[string] | いいえ | Per-message selected tool IDs from the WebChat client (camelCase: toolIds). |
| templateId | string (uuid) | いいえ | Document/sheet template ID for file-level compilation (camelCase: templateId). |
**リクエスト構造の例**
```typescript
{
"conversation": string (uuid)
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"attachments"?: [ // 任意
{
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"conversation"?: string (uuid) // 任意
}
]
"canvas"?: { // 任意
{
"name": string
"canvasType":
{
}
"title": string
"content": string
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"suggestedForId"?: string (uuid) // 任意
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
}
```
**リクエスト値の例**
```json
{
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"type": "サンプル文字列",
"content": "こんにちは！製品情報について詳しく知りたいです。",
"contentPayload": null,
"attachments": [
{
"type": {},
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"canvas": {
"name": "サンプル名",
"canvasType": {},
"title": "サンプル名",
"content": "こんにちは！製品情報について詳しく知りたいです。"
},
"slideTemplate": {
"slug": "サンプル文字列",
"displayName": "サンプル文字列",
"thumbnailUrls": [
"サンプル文字列"
]
},
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"metadata": null,
"broadcast": true,
"skipCopilotTrigger": true,
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例（Shell）
curl -X POST "https://api.maiagent.ai/api/v1/messages/outgoing/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"type": "サンプル文字列",
"content": "こんにちは！製品情報について詳しく知りたいです。",
"contentPayload": null,
"attachments": [
{
"type": {},
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"canvas": {
"name": "サンプル名",
"canvasType": {},
"title": "サンプル名",
"content": "こんにちは！製品情報について詳しく知りたいです。"
},
"slideTemplate": {
"slug": "サンプル文字列",
"displayName": "サンプル文字列",
"thumbnailUrls": [
"サンプル文字列"
]
},
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"metadata": null,
"broadcast": true,
"skipCopilotTrigger": true,
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000"
}'
# 実行前に 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 = {
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"type": "サンプル文字列",
"content": "こんにちは！製品情報について詳しく知りたいです。",
"contentPayload": null,
"attachments": [
{
"type": {},
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"canvas": {
"name": "サンプル名",
"canvasType": {},
"title": "サンプル名",
"content": "こんにちは！製品情報について詳しく知りたいです。"
},
"slideTemplate": {
"slug": "サンプル文字列",
"displayName": "サンプル文字列",
"thumbnailUrls": [
"サンプル文字列"
]
},
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"metadata": null,
"broadcast": true,
"skipCopilotTrigger": true,
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000"
};
axios.post("https://api.maiagent.ai/api/v1/messages/outgoing/", 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/messages/outgoing/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエスト内容（payload）
data = {
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"type": "サンプル文字列",
"content": "こんにちは！製品情報について詳しく知りたいです。",
"contentPayload": null,
"attachments": [
{
"type": {},
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"canvas": {
"name": "サンプル名",
"canvasType": {},
"title": "サンプル名",
"content": "こんにちは！製品情報について詳しく知りたいです。"
},
"slideTemplate": {
"slug": "サンプル文字列",
"displayName": "サンプル文字列",
"thumbnailUrls": [
"サンプル文字列"
]
},
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"metadata": null,
"broadcast": true,
"skipCopilotTrigger": true,
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000"
}
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/messages/outgoing/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"type": "サンプル文字列",
"content": "こんにちは！製品情報について詳しく知りたいです。",
"contentPayload": null,
"attachments": [
{
"type": {},
"filename": "document.pdf",
"file": "https://example.com/file.jpg",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"canvas": {
"name": "サンプル名",
"canvasType": {},
"title": "サンプル名",
"content": "こんにちは！製品情報について詳しく知りたいです。"
},
"slideTemplate": {
"slug": "サンプル文字列",
"displayName": "サンプル文字列",
"thumbnailUrls": [
"サンプル文字列"
]
},
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"metadata": null,
"broadcast": true,
"skipCopilotTrigger": true,
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000"
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 201**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"conversation": string (uuid)
"sender":
{
"id": string (uuid)
"name": string
"avatar": string
"email"?: string (email) // 任意
"phoneNumber"?: string // 任意
}
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"attachments"?: [ // 任意
{
"id": string (uuid)
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"expiresAt": string // ISO datetime when this attachment will be auto-deleted.
For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
"conversation"?: string (uuid) // 任意
}
]
"citations": [
{
"id": string (uuid)
"filename": string // ファイル名
"file": string (uri) // アップロードするファイル
"fileType": string
"knowledgeBase"?: // 任意
{
"id": string (uuid)
"name": string
}
"size": integer
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 任意
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (任意)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー可能な派生 PDF ファイルの URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外の場合は None です。
`file` フィールドと同じ CustomizedFileFieldSerializer を使用して URL を生成し、形式の一貫性を確保します（各
storage provider の presign/host ルールを含みます）。get_absolute_url() は使用しないでください。生成される URL の形式が正しくありません。
"createdAt": string (timestamp)
}
]
"citationNodes": [
{
"chatbotTextNode": {
{
"id": string (uuid)
"charactersCount": integer
"hitsCount": integer
"text": string
"updatedAt": string (timestamp)
"filename": string
"chatbotFile": object // フロントエンドでの画像プレビューに対応するため、ファイル URL とタイプを含む ChatbotFile の完全な情報を返します
"knowledgeBaseFile": object // get_chatbot_file と同じ内容で、後方互換性のために提供します
"pageNumber": integer // Backward-compatible alias of ``page_start``.
"pageStart": integer
"pageEnd": integer
"citationTitle": string // inline citation のホバーカードに表示するソースタイトルです
"citationDescription": string // inline citation のホバーカードに表示するソースの説明です
"citationQuote": string // inline citation のホバーカードに表示する引用テキストです
"hasImage": boolean // 画像が含まれているかを判定します（ファイルタイプまたは text 内の Markdown 画像を確認します）
"imageUrl": string // 画像 URL を抽出します（ファイル URL を優先し、それ以外の場合は Markdown から抽出します）
"displayText": string // 画像の Markdown マークアップを削除した全文を返します
"displayTitle": string // 表示タイトルを返します（fallback: citation_title -> filename）
"highlightedText": string // Return text with matched terms wrapped in ```` tags.
Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // ユーザーは metadata の key と value を独自に定義できます (任意)
"metadataEnabledForSearch": object // Map each user-defined metadata key on this node to whether it was sent into the LLM.
A key reaches the LLM only when its ``MetadataKey.enabled_for_search`` is True *and*
the node carries a value for it. Since this maps over ``raw_user_define_metadata``
(the keys the cited-documents block displays, all of which have a value),
``enabled_for_search`` alone decides the flag. The source of truth is the node's
knowledge base ``MetadataKey`` current setting, matching the AI Search indicator.
"startCharIdx": integer
"endCharIdx": integer
}
}
"score"?: number (double) // 任意
"displayScore": integer
"citationNumber"?: integer // Citation number matching the [1], [2] markers in the reply content (任意)
"highlightedText"?: string // ES/OpenSearch highlight result with tags (任意)
}
]
"canvas"?: { // 任意
{
"id": string (uuid)
"name": string
"canvasType":
{
}
"title": string
"content": string
"createdAt": string (timestamp)
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"recordId": string // Message に対応する ChatbotRecord ID を返します
Note:
保存されていない Message（streaming 中の仮想 Message など）の場合は None を直接返し、
OneToOneField の reverse relation による DB クエリ（N+1 問題）が発生しないようにします。
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"activeRevisionNumber": integer
"revisions": [
{
"id": string (uuid)
"revisionNumber": integer
"content": string
"contentPayload": object
"isActive": boolean
"createdAt": string (timestamp)
}
]
"suggestedForId"?: string (uuid) // 任意
"suggestionStatus": string
"suggestionTriggerSource": string
"suggestionError": string
"retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
"videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"avatar": "レスポンス文字列",
"email": "response@example.com",
"phoneNumber": "レスポンス文字列"
},
"type": "レスポンス文字列",
"content": "レスポンス文字列",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"attachments": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"expiresAt": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"citations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"fileType": "レスポンス文字列",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "レスポンス文字列",
"customName": "レスポンス文字列",
"displayName": "レスポンス文字列"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"previewUrl": "レスポンス文字列",
"createdAt": "レスポンス文字列"
}
],
"citationNodes": [
{
"chatbotTextNode": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"charactersCount": 456,
"hitsCount": 456,
"text": "レスポンス文字列",
"updatedAt": "レスポンス文字列",
"filename": "レスポンス文字列",
"chatbotFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"knowledgeBaseFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"pageNumber": 456,
"pageStart": 456,
"pageEnd": 456,
"citationTitle": "レスポンス文字列",
"citationDescription": "レスポンス文字列",
"citationQuote": "レスポンス文字列",
"hasImage": false,
"imageUrl": "レスポンス文字列",
"displayText": "レスポンス文字列",
"displayTitle": "レスポンス文字列",
"highlightedText": "レスポンス文字列",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"metadataEnabledForSearch": {
"key1": "value1",
"key2": "value2",
"createdAt": "2025-01-01T00:00:00.000Z"
},
"startCharIdx": 456,
"endCharIdx": 456
},
"score": 456,
"displayScore": 456,
"citationNumber": 456,
"highlightedText": "レスポンス文字列"
}
],
"canvas": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"canvasType": {},
"title": "レスポンス文字列",
"content": "レスポンス文字列",
"createdAt": "レスポンス文字列"
},
"slideTemplate": {
"slug": "レスポンス文字列",
"displayName": "レスポンス文字列",
"thumbnailUrls": [
"レスポンス文字列"
]
},
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"metadata": null,
"recordId": "レスポンス文字列",
"broadcast": false,
"skipCopilotTrigger": false,
"activeRevisionNumber": 456,
"revisions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"revisionNumber": 456,
"content": "レスポンス文字列",
"contentPayload": null,
"isActive": false,
"createdAt": "レスポンス文字列"
}
],
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"suggestionStatus": "レスポンス文字列",
"suggestionTriggerSource": "レスポンス文字列",
"suggestionError": "レスポンス文字列",
"retryCount": 456,
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000",
"videoGeneration": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
}
```
***
### 新しい会話を作成
POST `/api/v1/conversations/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# 実行前に 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 = {};
axios.post("https://api.maiagent.ai/api/v1/conversations/", 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/conversations/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {}
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/conversations/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 201**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"contact":
{
"id": string (uuid)
"name": string
"sourceId"?: string // 任意
}
"lastMessageCreatedAt": string (timestamp)
"autoReplyEnabled": boolean
"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.
Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
"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
"callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"sourceId": "レスポンス文字列"
},
"lastMessageCreatedAt": "レスポンス文字列",
"autoReplyEnabled": false,
"thinkingConfigSchema": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"effectiveThinkingConfig": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"deepResearchStatus": {},
"deepResearchOutputFormat": "canvas",
"callerOrganizationId": "レスポンス文字列"
}
```
***
### メッセージ一覧を取得
GET `/api/v1/messages/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| -------------- | -- | ------- | ------------------------------------- |
| `conversation` | ✅ | string | 会話 ID |
| `cursor` | ❌ | string | The pagination cursor value. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1" \
-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/messages/?conversation=example&cursor=example&pageSize=1", 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/messages/?conversation=example&cursor=example&pageSize=1"
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/messages/?conversation=example&cursor=example&pageSize=1", [
'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)
"conversation": string (uuid)
"sender":
{
"id": string (uuid)
"name": string
"avatar": string
"email"?: string (email) // 任意
"phoneNumber"?: string // 任意
}
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"attachments"?: [ // 任意
{
"id": string (uuid)
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"expiresAt": string // ISO datetime when this attachment will be auto-deleted.
For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
"conversation"?: string (uuid) // 任意
}
]
"citations": [
{
"id": string (uuid)
"filename": string // ファイル名
"file": string (uri) // アップロードするファイル
"fileType": string
"knowledgeBase"?: // 任意
{
"id": string (uuid)
"name": string
}
"size": integer
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 任意
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (任意)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー可能な派生 PDF ファイルの URL を返します（フロントエンドでは PDF ビューアーで表示します）。それ以外の場合は None です。
`file` フィールドと同じ CustomizedFileFieldSerializer を使用して URL を生成し、形式の一貫性を確保します（各
storage provider の presign/host ルールを含みます）。get_absolute_url() は誤った形式の URL を生成するため、使用しないでください。
"createdAt": string (timestamp)
}
]
"citationNodes": [
{
"chatbotTextNode": {
{
"id": string (uuid)
"charactersCount": integer
"hitsCount": integer
"text": string
"updatedAt": string (timestamp)
"filename": string
"chatbotFile": object // フロントエンドでの画像プレビューをサポートするため、ファイルの URL と種類を含む ChatbotFile の完全な情報を返します
"knowledgeBaseFile": object // get_chatbot_file と同じで、後方互換性のために提供されます
"pageNumber": integer // Backward-compatible alias of ``page_start``.
"pageStart": integer
"pageEnd": integer
"citationTitle": string // inline citation のホバーカードに表示するソースタイトルです
"citationDescription": string // inline citation のホバーカードに表示するソースの説明です
"citationQuote": string // inline citation のホバーカードに表示する引用テキストの抜粋です
"hasImage": boolean // 画像が含まれているかを判定します（ファイルの種類または text 内の Markdown 画像を確認します）
"imageUrl": string // 画像 URL を抽出します（ファイル URL を優先し、それ以外の場合は Markdown から抽出します）
"displayText": string // 画像の Markdown マークアップを削除した完全なテキストを返します
"displayTitle": string // 表示タイトルを返します（fallback: citation_title -> filename）
"highlightedText": string // Return text with matched terms wrapped in ```` tags.
Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // ユーザーが metadata の key と value を独自に定義できます (任意)
"metadataEnabledForSearch": object // Map each user-defined metadata key on this node to whether it was sent into the LLM.
A key reaches the LLM only when its ``MetadataKey.enabled_for_search`` is True *and*
the node carries a value for it. Since this maps over ``raw_user_define_metadata``
(the keys the cited-documents block displays, all of which have a value),
``enabled_for_search`` alone decides the flag. The source of truth is the node's
knowledge base ``MetadataKey`` current setting, matching the AI Search indicator.
"startCharIdx": integer
"endCharIdx": integer
}
}
"score"?: number (double) // 任意
"displayScore": integer
"citationNumber"?: integer // Citation number matching the [1], [2] markers in the reply content (任意)
"highlightedText"?: string // ES/OpenSearch highlight result with tags (任意)
}
]
"canvas"?: { // 任意
{
"id": string (uuid)
"name": string
"canvasType":
{
}
"title": string
"content": string
"createdAt": string (timestamp)
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"recordId": string // Message に対応する ChatbotRecord ID を返します
Note:
保存されていない Message（streaming 中の仮想 Message など）の場合は None を直接返し、
OneToOneField の reverse relation に対する DB クエリ（N+1 問題）が発生しないようにします。
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"activeRevisionNumber": integer
"revisions": [
{
"id": string (uuid)
"revisionNumber": integer
"content": string
"contentPayload": object
"isActive": boolean
"createdAt": string (timestamp)
}
]
"suggestedForId"?: string (uuid) // 任意
"suggestionStatus": string
"suggestionTriggerSource": string
"suggestionError": string
"retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
"videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}
]
}
```
**レスポンス値の例**
```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",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"avatar": "レスポンス文字列",
"email": "response@example.com",
"phoneNumber": "レスポンス文字列"
},
"type": "レスポンス文字列",
"content": "レスポンス文字列",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"attachments": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"expiresAt": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"citations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"fileType": "レスポンス文字列",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "レスポンス文字列",
"customName": "レスポンス文字列",
"displayName": "レスポンス文字列"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"previewUrl": "レスポンス文字列",
"createdAt": "レスポンス文字列"
}
],
"citationNodes": [
{
"chatbotTextNode": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"charactersCount": 456,
"hitsCount": 456,
"text": "レスポンス文字列",
"updatedAt": "レスポンス文字列",
"filename": "レスポンス文字列",
"chatbotFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
},
"knowledgeBaseFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
},
"pageNumber": 456,
"pageStart": 456,
"pageEnd": 456,
"citationTitle": "レスポンス文字列",
"citationDescription": "レスポンス文字列",
"citationQuote": "レスポンス文字列",
"hasImage": false,
"imageUrl": "レスポンス文字列",
"displayText": "レスポンス文字列",
"displayTitle": "レスポンス文字列",
"highlightedText": "レスポンス文字列",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"metadataEnabledForSearch": {
"key1": "value1",
"key2": "value2",
"createdAt": "2025-01-01T00:00:00.000Z"
},
"startCharIdx": 456,
"endCharIdx": 456
},
"score": 456,
"displayScore": 456,
"citationNumber": 456,
"highlightedText": "レスポンス文字列"
}
],
"canvas": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"canvasType": {},
"title": "レスポンス文字列",
"content": "レスポンス文字列",
"createdAt": "レスポンス文字列"
},
"slideTemplate": {
"slug": "レスポンス文字列",
"displayName": "レスポンス文字列",
"thumbnailUrls": [
"レスポンス文字列"
]
},
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
},
"metadata": null,
"recordId": "レスポンス文字列",
"broadcast": false,
"skipCopilotTrigger": false,
"activeRevisionNumber": 456,
"revisions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"revisionNumber": 456,
"content": "レスポンス文字列",
"contentPayload": null,
"isActive": false,
"createdAt": "レスポンス文字列"
}
],
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"suggestionStatus": "レスポンス文字列",
"suggestionTriggerSource": "レスポンス文字列",
"suggestionError": "レスポンス文字列",
"retryCount": 456,
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000",
"videoGeneration": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
}
}
]
}
```
***
### 特定のメッセージを取得
GET `/api/v1/messages/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| -------------- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Message. |
| `conversation` | ✅ | string | 会話 ID |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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)
"conversation": string (uuid)
"sender":
{
"id": string (uuid)
"name": string
"avatar": string
"email"?: string (email) // 任意
"phoneNumber"?: string // 任意
}
"type"?: string // 任意
"content"?: string // 任意
"contentPayload"?: object // 任意
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"attachments"?: [ // 任意
{
"id": string (uuid)
"type"?: // 任意
{
}
"filename": string
"file": string (uri)
"expiresAt": string // ISO datetime when this attachment will be auto-deleted.
For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
"conversation"?: string (uuid) // 任意
}
]
"citations": [
{
"id": string (uuid)
"filename": string // ファイル名
"file": string (uri) // アップロードするファイル
"fileType": string
"knowledgeBase"?: // 任意
{
"id": string (uuid)
"name": string
}
"size": integer
"status":
{
}
"parser":
{
"id": string (uuid)
"name": string
"provider":
{
}
"isTimestampSttProvider": boolean
}
"labels"?: [ // 任意
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 任意
"speakerLabels": [
{
"id": string (uuid)
"originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
"customName"?: string // User-defined speaker name (e.g., John) (任意)
"displayName": string
}
]
"vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
"chunksCount": integer // Number of chunks/nodes generated from this file
"waitingTime": number (double)
"processingTime": number (double)
"processingTimeDetails": object
"previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー可能な派生 PDF ファイルの URL を返します（フロントエンドでは PDF ビューアーで表示します）。それ以外の場合は None です。
`file` フィールドと同じ CustomizedFileFieldSerializer を使用して URL を生成し、形式の一貫性を確保します（各
storage provider の presign/host ルールを含みます）。get_absolute_url() は誤った形式の URL を生成するため、使用しないでください。
"createdAt": string (timestamp)
}
]
"citationNodes": [
{
"chatbotTextNode": {
{
"id": string (uuid)
"charactersCount": integer
"hitsCount": integer
"text": string
"updatedAt": string (timestamp)
"filename": string
"chatbotFile": object // フロントエンドでの画像プレビューをサポートするため、ファイルの URL と種類を含む ChatbotFile の完全な情報を返します
"knowledgeBaseFile": object // get_chatbot_file と同じで、後方互換性のために提供されます
"pageNumber": integer // Backward-compatible alias of ``page_start``.
"pageStart": integer
"pageEnd": integer
"citationTitle": string // inline citation のホバーカードに表示するソースタイトルです
"citationDescription": string // inline citation のホバーカードに表示するソースの説明です
"citationQuote": string // inline citation のホバーカードに表示する引用テキストの抜粋です
"hasImage": boolean // 画像が含まれているかを判定します（ファイルの種類または text 内の Markdown 画像を確認します）
"imageUrl": string // 画像 URL を抽出します（ファイル URL を優先し、それ以外の場合は Markdown から抽出します）
"displayText": string // 画像の Markdown マークアップを削除した完全なテキストを返します
"displayTitle": string // 表示タイトルを返します（fallback: citation_title -> filename）
"highlightedText": string // Return text with matched terms wrapped in ```` tags.
Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // ユーザーが metadata の key と value を独自に定義できます (任意)
"metadataEnabledForSearch": object // Map each user-defined metadata key on this node to whether it was sent into the LLM.
A key reaches the LLM only when its ``MetadataKey.enabled_for_search`` is True *and*
the node carries a value for it. Since this maps over ``raw_user_define_metadata``
(the keys the cited-documents block displays, all of which have a value),
``enabled_for_search`` alone decides the flag. The source of truth is the node's
knowledge base ``MetadataKey`` current setting, matching the AI Search indicator.
"startCharIdx": integer
"endCharIdx": integer
}
}
"score"?: number (double) // 任意
"displayScore": integer
"citationNumber"?: integer // Citation number matching the [1], [2] markers in the reply content (任意)
"highlightedText"?: string // ES/OpenSearch highlight result with tags (任意)
}
]
"canvas"?: { // 任意
{
"id": string (uuid)
"name": string
"canvasType":
{
}
"title": string
"content": string
"createdAt": string (timestamp)
}
}
"slideTemplate"?: // 任意
{
"slug": string
"displayName": string
"thumbnailUrls"?: [ // 任意
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 // Message metadata, such as timezone and other environment information (任意)
"recordId": string // Message に対応する ChatbotRecord ID を返します
Note:
未保存の Message（streaming 中の仮想 Message など）については、None を直接返し、
OneToOneField の逆リレーションによる DB クエリ（N+1 問題）の発生を回避します。
"broadcast"?: boolean // 任意
"skipCopilotTrigger"?: boolean // 任意
"activeRevisionNumber": integer
"revisions": [
{
"id": string (uuid)
"revisionNumber": integer
"content": string
"contentPayload": object
"isActive": boolean
"createdAt": string (timestamp)
}
]
"suggestedForId"?: string (uuid) // 任意
"suggestionStatus": string
"suggestionTriggerSource": string
"suggestionError": string
"retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
"skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意)
string (uuid)
]
"toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意)
string (uuid)
]
"templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意)
"videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"avatar": "レスポンス文字列",
"email": "response@example.com",
"phoneNumber": "レスポンス文字列"
},
"type": "レスポンス文字列",
"content": "レスポンス文字列",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"attachments": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"expiresAt": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000"
}
],
"citations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "レスポンス文字列",
"file": "https://example.com/file.jpg",
"fileType": "レスポンス文字列",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"size": 456,
"status": {},
"parser": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"provider": {},
"isTimestampSttProvider": false
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"speakerLabels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"originalLabel": "レスポンス文字列",
"customName": "レスポンス文字列",
"displayName": "レスポンス文字列"
}
],
"vectorStorageSize": 456,
"chunksCount": 456,
"waitingTime": 456,
"processingTime": 456,
"processingTimeDetails": null,
"previewUrl": "レスポンス文字列",
"createdAt": "レスポンス文字列"
}
],
"citationNodes": [
{
"chatbotTextNode": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"charactersCount": 456,
"hitsCount": 456,
"text": "レスポンス文字列",
"updatedAt": "レスポンス文字列",
"filename": "レスポンス文字列",
"chatbotFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"knowledgeBaseFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"pageNumber": 456,
"pageStart": 456,
"pageEnd": 456,
"citationTitle": "レスポンス文字列",
"citationDescription": "レスポンス文字列",
"citationQuote": "レスポンス文字列",
"hasImage": false,
"imageUrl": "レスポンス文字列",
"displayText": "レスポンス文字列",
"displayTitle": "レスポンス文字列",
"highlightedText": "レスポンス文字列",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
}
],
"rawUserDefineMetadata": null,
"metadataEnabledForSearch": {
"key1": "value1",
"key2": "value2",
"createdAt": "2025-01-01T00:00:00.000Z"
},
"startCharIdx": 456,
"endCharIdx": 456
},
"score": 456,
"displayScore": 456,
"citationNumber": 456,
"highlightedText": "レスポンス文字列"
}
],
"canvas": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"canvasType": {},
"title": "レスポンス文字列",
"content": "レスポンス文字列",
"createdAt": "レスポンス文字列"
},
"slideTemplate": {
"slug": "レスポンス文字列",
"displayName": "レスポンス文字列",
"thumbnailUrls": [
"レスポンス文字列"
]
},
"queryMetadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"metadata": null,
"recordId": "レスポンス文字列",
"broadcast": false,
"skipCopilotTrigger": false,
"activeRevisionNumber": 456,
"revisions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"revisionNumber": 456,
"content": "レスポンス文字列",
"contentPayload": null,
"isActive": false,
"createdAt": "レスポンス文字列"
}
],
"suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
"suggestionStatus": "レスポンス文字列",
"suggestionTriggerSource": "レスポンス文字列",
"suggestionError": "レスポンス文字列",
"retryCount": 456,
"skillIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"toolIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"templateId": "550e8400-e29b-41d4-a716-446655440000",
"videoGeneration": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
}
```
***
### 会話一覧を取得
GET `/api/v1/conversations/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------------------------ | -- | ------- | ------------------------------------------------------------- |
| `assignee` | ❌ | string | |
| `chatbot` | ❌ | string | |
| `contact` | ❌ | string | |
| `contactTags` | ❌ | array | Multiple values may be separated by commas. |
| `cursor` | ❌ | string | The pagination cursor value. |
| `endDate` | ❌ | string | |
| `externalConversationId` | ❌ | string | |
| `externalSource` | ❌ | string | |
| `inbox` | ❌ | string | |
| `isPinned` | ❌ | string | |
| `mine` | ❌ | boolean | |
| `mode` | ❌ | string | \`chat\`: Chat ; \`cowork\`: Cowork; |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `startDate` | ❌ | string | |
| `status` | ❌ | array | \`open\`: Open ; \`resolved\`: Resolved ; \`queued\`: Queued; |
| `tags` | ❌ | array | Multiple values may be separated by commas. |
| `unassigned` | ❌ | boolean | |
| `updatedAfter` | ❌ | string | |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z" \
-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/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z", 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/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z"
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/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z", [
'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 = unset (inherit the chatbot setting), {} = explicitly off, {...} = custom override (任意)
"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.
Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
"llm": string (uuid)
"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 // 引き継ぎ関係：継続先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title が含まれます。引き継ぎのない会話では null です
}
]
}
```
**レスポンス値の例**
```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": "レスポンス説明の例"
}
}
]
}
```
***
### 特定の会話を取得
GET `/api/v1/conversations/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Conversation. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/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/conversations/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/conversations/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/conversations/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)
"contact":
{
"id": string (uuid)
"name": string
"sourceId"?: string // 任意
}
"lastMessageCreatedAt": string (timestamp)
"autoReplyEnabled": boolean
"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.
Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
"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
"callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列",
"sourceId": "レスポンス文字列"
},
"lastMessageCreatedAt": "レスポンス文字列",
"autoReplyEnabled": false,
"thinkingConfigSchema": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
},
"effectiveThinkingConfig": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス名の例",
"description": "レスポンス説明の例"
},
"deepResearchStatus": {},
"deepResearchOutputFormat": "canvas",
"callerOrganizationId": "レスポンス文字列"
}
```
***
### 特定の会話を取得
GET `/api/v1/conversations/tab-counts/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/tab-counts/" \
-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/conversations/tab-counts/", 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/conversations/tab-counts/"
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/conversations/tab-counts/", [
'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 = unset (inherit the chatbot setting), {} = explicitly off, {...} = custom override (任意)
"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.
Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
"llm": string (uuid)
"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 // 引き継ぎの関連付け：継続先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title が含まれます。引き継ぎのない会話では null です
}
```
**レスポンス値の例**
```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": "レスポンス例の説明"
}
}
```
***
### 会話名の変更
PATCH `/api/v1/conversations/{id}/rename/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Conversation. |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contact | object | いいえ | Conversation List view 用の軽量 Contact Serializer です。List view に必要なフィールドのみを含め、N+1 クエリの問題を回避するため inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドであり、フロントエンドの会話サイドバーでの表示に必要ですが、N+1 コストは発生しません。 |
| contact.name | string | はい | |
| contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. |
| contact.email | object | いいえ | |
| contact.phoneNumber | string | いいえ | |
| contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page |
| contact.sourceId | string | いいえ | |
| inbox | object | いいえ | 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 em... |
| inbox.name | string | はい | |
| inbox.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+ ; \`lin... |
| inbox.unreadConversationsCount | integer | いいえ | |
| inbox.signAuth | object (8 個のプロパティを含む: id, signSource, signParams...) | いいえ | |
| inbox.signAuth.signSource | string (uuid) | はい | |
| inbox.signAuth.signParams | object | はい | |
| inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含む: clientId, url, realm) | はい | |
| inbox.signAuth.signParams.line | object (1 個のプロパティを含む: liffId) | はい | |
| inbox.signAuth.signParams.ad | object (1 個のプロパティを含む: saml) | はい | |
| inbox.signAuth.signParams.google | object (1 個のプロパティを含む: enabled) | いいえ | |
| inbox.signAuth.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. |
| inbox.signAuth.sourceIdVerifyMode | object | いいえ | "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 testin... |
| inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | 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; |
| inbox.signAuth.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-to... |
| inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to |
| inbox.enableAnalysis | boolean | いいえ | |
| lastMessage | object | いいえ | |
| lastMessage.type | string | いいえ | |
| lastMessage.content | string | いいえ | |
| enableGroupMention | boolean | いいえ | |
| queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください |
| queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです |
| queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合、ラベルによるフィルタリングは行いません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にはラベルフィルターが適用されません（制限なしと同等です） |
| queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法 |
| queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。ネストした operator/conditions の組み合わせをサポートします |
| toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} |
| connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} |
| thinkingConfig | object | いいえ | None = unset (inherit the chatbot setting), {} = explicitly off, {...} = custom override |
| status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; |
| firstResponseAt | string (timestamp) | いいえ | |
| queuedAt | string (timestamp) | いいえ | |
| assignedAt | string (timestamp) | いいえ | |
| transferReason | string | いいえ | |
**リクエスト構造の例**
```typescript
{
"contact"?: { // Conversation List view 用の軽量 Contact Serializer
List view に必要なフィールドのみを含め、N+1 クエリの問題を回避するため、
inboxes、mcp_credentials、api_credentials を除外します。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、
フロントエンドの会話サイドバーでの表示に必要ですが、N+1 コストは発生しません。 (任意)
{
"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 // 任意
}
}
"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``. (任意)
{
"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"?: // 任意
{
"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 // 任意
}
}
"lastMessage"?: { // 任意
{
"type"?: string // 任意
"content"?: string // 任意
}
}
"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 = unset (inherit the chatbot setting), {} = explicitly off, {...} = custom override (任意)
"status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (任意)
"firstResponseAt"?: string (timestamp) // 任意
"queuedAt"?: string (timestamp) // 任意
"assignedAt"?: string (timestamp) // 任意
"transferReason"?: string // 任意
}
```
**リクエスト値の例**
```json
{
"contact": {
"name": "サンプル名",
"avatar": "サンプル文字列",
"email": null,
"phoneNumber": "サンプル文字列",
"metadata": null,
"sourceId": "サンプル文字列"
},
"inbox": {
"name": "サンプル名",
"channelType": "line",
"unreadConversationsCount": 123,
"signAuth": {
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "サンプル文字列",
"url": "サンプル文字列",
"realm": "サンプル文字列"
},
"line": {
"liffId": "サンプル文字列"
},
"ad": {
"saml": "サンプル文字列"
},
"google": {
"enabled": true
}
},
"sourceIdAccessEnabled": true,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": true,
"keycloakTokenPassthroughAllowedHosts": [
"サンプル文字列"
]
},
"enableAnalysis": true
},
"lastMessage": {
"type": "サンプル文字列",
"content": "こんにちは！製品情報について知りたいです。"
},
"enableGroupMention": true,
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"status": "open",
"firstResponseAt": "サンプル文字列",
"queuedAt": "サンプル文字列",
"assignedAt": "サンプル文字列",
"transferReason": "サンプル文字列"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact": {
"name": "サンプル名",
"avatar": "サンプル文字列",
"email": null,
"phoneNumber": "サンプル文字列",
"metadata": null,
"sourceId": "サンプル文字列"
},
"inbox": {
"name": "サンプル名",
"channelType": "line",
"unreadConversationsCount": 123,
"signAuth": {
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "サンプル文字列",
"url": "サンプル文字列",
"realm": "サンプル文字列"
},
"line": {
"liffId": "サンプル文字列"
},
"ad": {
"saml": "サンプル文字列"
},
"google": {
"enabled": true
}
},
"sourceIdAccessEnabled": true,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": true,
"keycloakTokenPassthroughAllowedHosts": [
"サンプル文字列"
]
},
"enableAnalysis": true
},
"lastMessage": {
"type": "サンプル文字列",
"content": "こんにちは！製品情報について知りたいです。"
},
"enableGroupMention": true,
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"status": "open",
"firstResponseAt": "サンプル文字列",
"queuedAt": "サンプル文字列",
"assignedAt": "サンプル文字列",
"transferReason": "サンプル文字列"
}'
# 実行前に 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 = {
"contact": {
"name": "名前の例",
"avatar": "文字列の例",
"email": null,
"phoneNumber": "文字列の例",
"metadata": null,
"sourceId": "文字列の例"
},
"inbox": {
"name": "名前の例",
"channelType": "line",
"unreadConversationsCount": 123,
"signAuth": {
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "文字列の例",
"url": "文字列の例",
"realm": "文字列の例"
},
"line": {
"liffId": "文字列の例"
},
"ad": {
"saml": "文字列の例"
},
"google": {
"enabled": true
}
},
"sourceIdAccessEnabled": true,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": true,
"keycloakTokenPassthroughAllowedHosts": [
"文字列の例"
]
},
"enableAnalysis": true
},
"lastMessage": {
"type": "文字列の例",
"content": "こんにちは！製品情報について知りたいです。"
},
"enableGroupMention": true,
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"status": "open",
"firstResponseAt": "文字列の例",
"queuedAt": "文字列の例",
"assignedAt": "文字列の例",
"transferReason": "文字列の例"
};
axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", 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/conversations/550e8400-e29b-41d4-a716-446655440000/rename/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"contact": {
"name": "名前の例",
"avatar": "文字列の例",
"email": null,
"phoneNumber": "文字列の例",
"metadata": null,
"sourceId": "文字列の例"
},
"inbox": {
"name": "名前の例",
"channelType": "line",
"unreadConversationsCount": 123,
"signAuth": {
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "文字列の例",
"url": "文字列の例",
"realm": "文字列の例"
},
"line": {
"liffId": "文字列の例"
},
"ad": {
"saml": "文字列の例"
},
"google": {
"enabled": true
}
},
"sourceIdAccessEnabled": true,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": true,
"keycloakTokenPassthroughAllowedHosts": [
"文字列の例"
]
},
"enableAnalysis": true
},
"lastMessage": {
"type": "文字列の例",
"content": "こんにちは！製品情報について知りたいです。"
},
"enableGroupMention": true,
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"status": "open",
"firstResponseAt": "文字列の例",
"queuedAt": "文字列の例",
"assignedAt": "文字列の例",
"transferReason": "文字列の例"
}
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/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"contact": {
"name": "名前の例",
"avatar": "文字列の例",
"email": null,
"phoneNumber": "文字列の例",
"metadata": null,
"sourceId": "文字列の例"
},
"inbox": {
"name": "名前の例",
"channelType": "line",
"unreadConversationsCount": 123,
"signAuth": {
"signSource": "550e8400-e29b-41d4-a716-446655440000",
"signParams": {
"keycloak": {
"clientId": "文字列の例",
"url": "文字列の例",
"realm": "文字列の例"
},
"line": {
"liffId": "文字列の例"
},
"ad": {
"saml": "文字列の例"
},
"google": {
"enabled": true
}
},
"sourceIdAccessEnabled": true,
"sourceIdVerifyMode": {},
"sourceIdSignatureTtlMinutes": {},
"keycloakTokenPassthrough": true,
"keycloakTokenPassthroughAllowedHosts": [
"文字列の例"
]
},
"enableAnalysis": true
},
"lastMessage": {
"type": "文字列の例",
"content": "こんにちは！製品情報について知りたいです。"
},
"enableGroupMention": true,
"queryMetadata": {
"knowledgeBases": [
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"faqIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"hasUserSelectedAll": true
}
],
"labelRelations": {
"operator": "AND",
"conditions": [
null
]
}
},
"toolMask": null,
"connectorMask": null,
"thinkingConfig": null,
"status": "open",
"firstResponseAt": "文字列の例",
"queuedAt": "文字列の例",
"assignedAt": "文字列の例",
"transferReason": "文字列の例"
}
]);
$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 = unset (inherit the chatbot setting), {} = explicitly off, {...} = custom override (任意)
"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.
Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
"llm": string (uuid)
"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 // 引き継ぎ関係です。継続先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title が含まれます。引き継ぎのない会話では null です
}
```
**レスポンス値の例**
```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": "レスポンス説明の例"
}
}
```
***
### 会話を共有
POST `/api/v1/conversations/{conversationPk}/share/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ---------------- | -- | ------ | -- |
| `conversationPk` | ✅ | string | |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ----------- | ------------------------------------------ | --- | ----------------------------------------------------------------- |
| shareScope | string (enum: organization, group, member) | はい | `organization`: Organization ; `group`: Group ; `member`: Member; |
| permission | object | いいえ | |
| title | string | いいえ | |
| description | string | いいえ | |
| groupIds | array\[string] | いいえ | |
| memberIds | array\[string] | いいえ | |
**リクエスト構造の例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 任意
{
}
"title"?: string // 任意
"description"?: string // 任意
"groupIds"?: [ // 任意
string (uuid)
]
"memberIds"?: [ // 任意
string (uuid)
]
}
```
**リクエスト値の例**
```json
{
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 実行前に 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 = {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/", 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/conversations/{conversationPk}/share/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
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/conversations/{conversationPk}/share/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 201**
**レスポンス構造の例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 任意
{
}
"title"?: string // 任意
"description"?: string // 任意
"groupIds"?: [ // 任意
string (uuid)
]
"memberIds"?: [ // 任意
string (uuid)
]
}
```
**レスポンス値の例**
```json
{
"shareScope": "organization",
"permission": {},
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
***
### 会話をクイック共有
POST `/api/v1/conversations/{conversationPk}/share/quick/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ---------------- | -- | ------ | -- |
| `conversationPk` | ✅ | string | |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ----------- | ------------------------------------------ | --- | ----------------------------------------------------------------- |
| shareScope | string (enum: organization, group, member) | はい | `organization`: Organization ; `group`: Group ; `member`: Member; |
| permission | object | いいえ | |
| title | string | いいえ | |
| description | string | いいえ | |
| groupIds | array\[string] | いいえ | |
| memberIds | array\[string] | いいえ | |
**リクエスト構造の例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 任意
{
}
"title"?: string // 任意
"description"?: string // 任意
"groupIds"?: [ // 任意
string (uuid)
]
"memberIds"?: [ // 任意
string (uuid)
]
}
```
**リクエスト値の例**
```json
{
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 実行前に 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 = {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/", 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/conversations/{conversationPk}/share/quick/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
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/conversations/{conversationPk}/share/quick/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "名前の例",
"description": "文字列の例",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスを正常に取得しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンスボディ
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 任意
{
}
"title"?: string // 任意
"description"?: string // 任意
"groupIds"?: [ // 任意
string (uuid)
]
"memberIds"?: [ // 任意
string (uuid)
]
}
```
**レスポンス値の例**
```json
{
"shareScope": "organization",
"permission": {},
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
***
### 共有会話一覧
GET `/api/v1/shared-conversations/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ---------- | -- | ------- | ---------------------------------------------- |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1" \
-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/shared-conversations/?page=1&pageSize=1", 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/shared-conversations/?page=1&pageSize=1"
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/shared-conversations/?page=1&pageSize=1", [
'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)
"title": string // Custom title for the shared conversation
"description": string // Custom description for the shared conversation
"shareScope":
{
}
"permission":
{
}
"sharedBy":
{
"id": string (uuid)
"name": string
}
"messageCount": integer
"createdAt": string (timestamp)
}
]
}
```
**レスポンス値の例**
```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",
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"shareScope": {},
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"messageCount": 456,
"createdAt": "レスポンス文字列"
}
]
}
```
***
### 特定の共有会話を取得
GET `/api/v1/shared-conversations/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/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/shared-conversations/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/shared-conversations/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/shared-conversations/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)
"title": string // Custom title for the shared conversation
"description": string // Custom description for the shared conversation
"permission":
{
}
"sharedBy":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]}
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"conversationSnapshot": null
}
```
***
### 共有会話を更新
PATCH `/api/v1/shared-conversations/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### リクエスト内容
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ----------- | ----------------------------- | --- | ----------------------------------------- |
| title | string | いいえ | |
| description | string | いいえ | |
| permission | string (enum: readonly, copy) | いいえ | `readonly`: Read Only ; `copy`: Copyable; |
**リクエスト構造の例**
```typescript
{
"title"?: string // 任意
"description"?: string // 任意
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (任意)
}
```
**リクエスト値の例**
```json
{
"title": "サンプル名",
"description": "サンプル文字列",
"permission": "readonly"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "サンプル名",
"description": "サンプル文字列",
"permission": "readonly"
}'
# 実行前に 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 = {
"title": "サンプル名",
"description": "サンプル文字列",
"permission": "readonly"
};
axios.patch("https://api.maiagent.ai/api/v1/shared-conversations/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/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエスト内容 (payload)
data = {
"title": "サンプル名",
"description": "サンプル文字列",
"permission": "readonly"
}
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/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"title": "サンプル名",
"description": "サンプル文字列",
"permission": "readonly"
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"title"?: string // 任意
"description"?: string // 任意
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (任意)
}
```
**レスポンス値の例**
```json
{
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"permission": "readonly"
}
```
***
### 共有会話を削除
DELETE `/api/v1/shared-conversations/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/shared-conversations/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/shared-conversations/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/shared-conversations/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/shared-conversations/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 |
***
### 共有会話をコピー
POST `/api/v1/shared-conversations/{id}/fork/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ------ | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# 実行前に 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 = {};
axios.post("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", 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/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエスト内容 (payload)
data = {}
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/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"title": string // Custom title for the shared conversation
"description": string // Custom description for the shared conversation
"permission":
{
}
"sharedBy":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]}
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"conversationSnapshot": null
}
```
***
### 自分の共有一覧を取得
GET `/api/v1/shared-conversations/my-shares/`
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/my-shares/" \
-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/shared-conversations/my-shares/", 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/shared-conversations/my-shares/"
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/shared-conversations/my-shares/", [
'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)
"title": string // Custom title for the shared conversation
"description": string // Custom description for the shared conversation
"shareScope":
{
}
"permission":
{
}
"sharedBy":
{
"id": string (uuid)
"name": string
}
"messageCount": integer
"createdAt": string (timestamp)
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "レスポンス文字列",
"description": "レスポンス文字列",
"shareScope": {},
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"messageCount": 456,
"createdAt": "レスポンス文字列"
}
```
***
### メッセージフィードバックを作成
POST `/api/v1/messages/{messagePk}/feedback/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ----------- | -- | ------ | -- |
| `messagePk` | ✅ | string | |
#### リクエスト内容
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | --- | -- |
| type | object | はい | |
| suggestion | string | いいえ | |
**リクエスト構造の例**
```typescript
{
"type":
{
}
"suggestion"?: string // 任意
}
```
**リクエスト値の例**
```json
{
"type": {},
"suggestion": "サンプル文字列"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": {},
"suggestion": "サンプル文字列"
}'
# 実行前に 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 = {
"type": {},
"suggestion": "サンプル文字列"
};
axios.post("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/", 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/messages/{messagePk}/feedback/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエスト内容 (payload)
data = {
"type": {},
"suggestion": "サンプル文字列"
}
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/messages/{messagePk}/feedback/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "サンプル文字列"
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 201**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
**ステータスコード: 400 - このメッセージにはすでにフィードバックがあります。PATCH メソッドで更新してください**
***
### メッセージフィードバックを更新
PUT `/api/v1/messages/{messagePk}/feedback/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ----------- | -- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Message Feedback. |
| `messagePk` | ✅ | string | |
#### リクエスト内容
**リクエストパラメータ**
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | --- | -- |
| type | object | はい | |
| suggestion | string | いいえ | |
**リクエスト構造の例**
```typescript
{
"type":
{
}
"suggestion"?: string // 任意
}
```
**リクエスト値の例**
```json
{
"type": {},
"suggestion": "サンプル文字列"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": {},
"suggestion": "サンプル文字列"
}'
# 実行前に 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 = {
"type": {},
"suggestion": "サンプル文字列"
};
axios.put("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/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/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエスト内容 (payload)
data = {
"type": {},
"suggestion": "サンプル文字列"
}
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/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "サンプル文字列"
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンスの取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス内容
**ステータスコード: 200**
**レスポンス構造の例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
```
***
### メッセージフィードバックを削除
DELETE `/api/v1/messages/{messagePk}/feedback/{id}/`
#### パラメータ
| パラメータ名 | 必須 | 型 | 説明 |
| ----------- | -- | ------ | ------------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Message Feedback. |
| `messagePk` | ✅ | string | |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/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/messages/{messagePk}/feedback/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/messages/{messagePk}/feedback/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/messages/{messagePk}/feedback/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 | フィードバックが正常に削除されました |
| 400 | このフィードバックは指定されたメッセージに属していません |
***
### 会話レコード一覧の取得
GET `/api/v1/records/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| -------------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `callerMember` | ❌ | array | Multiple values may be separated by commas. |
| `chatbot` | ❌ | string | 特定の AI アシスタントで絞り込みます（UUID） |
| `endDate` | ❌ | string | 終了日（形式：YYYY-MM-DD、例：2025-01-31） |
| `endDatetime` | ❌ | string | |
| `errorType` | ❌ | array | Multiple values may be separated by commas. \`system\`: System ; \`llm\`: LLM ; \`embedding\`: Embedding ; \`reranker\`: Reranker ; \`vector\_db\`: Vector DB ; \`workflow\`: Workflow ; \`tool\`: Tool ; \`timeout\`: Ti... |
| `feedbackType` | ❌ | array | Multiple values may be separated by commas. \`like\`: Like ; \`dislike\`: Dislike; |
| `hasError` | ❌ | boolean | |
| `hasFeedback` | ❌ | boolean | |
| `keyword` | ❌ | string | キーワード検索（ユーザーのメッセージとチャットボットの回答内容を同時に検索します） |
| `largeLanguageModel` | ❌ | string | 特定の大規模言語モデルで絞り込みます（UUID） |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `source` | ❌ | string | レコードのソースをカンマ区切りで絞り込みます。省略した場合は両方のソースを返します。interactive = ユーザーとの会話、scheduled = スケジュール実行。 |
| `startDate` | ❌ | string | 開始日（形式：YYYY-MM-DD、例：2025-01-01） |
| `startDatetime` | ❌ | string | |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z" \
-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/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z", 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/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z"
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/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z", [
'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)
"senderName": string // ユーザーメッセージの送信者名を返します
"callerMemberId": string
"callerMemberName": string
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"inputMessage": string
"condenseMessage": string // チャット履歴とコンテキストを統合して調整されたユーザーメッセージ
"outputMessage": string
"faithfulnessScore": number (double) // チャットボットの回答がデータベースの内容と一致し、捏造されていないかを判定します
"displayFaithfulnessScore": integer
"answerRelevancyScore": number (double) // チャットボットの回答がユーザーの質問に関連しているかを判定します
"displayAnswerRelevancyScore": integer
"contextPrecisionScore": number (double) // チャットボットの回答が参照資料に関連しているかを判定します
"displayContextPrecisionScore": integer
"answerCorrectnessScore": number (double) // チャットボットの回答が正しいかを判定します（正解が必要です）
"displayAnswerCorrectnessScore": integer
"answerSimilarityScore": number (double) // チャットボットの回答が正解と類似しているかを判定します
"displayAnswerSimilarityScore": integer
"contextRecallScore": number (double) // チャットボットの回答が参照資料から関連情報を検索できるかを判定します
"displayContextRecallScore": integer
"replyTime": string
"createdAt": string (timestamp)
"error": string // 実行中に発生したエラーメッセージを保存します
"errorType": // 異なるタイプの場合があります
string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, hook_blocked, evaluation, other) // エラーの発生元（システム、LLM、Embedding、Reranker など）を区別します
* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `hook_blocked` - Hook Blocked
* `evaluation` - Evaluation
* `other` - Other
"processingTime": object // streaming_metrics の waterfall を含む、各処理段階の時間統計を返します
"usage": object // 文字数、トークン数、LLM 呼び出しごとのトークン明細を含む使用量統計を返します
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
"url": string
}
]
"inputHookLogs": [
{
"id": string (uuid)
"hook": string (uuid)
"hookName": string
"hookTypeLabel": string
"hookAction": string
"conversation": string (uuid)
"message": string (uuid)
"messageContent": string // Return the raw message text.
"chatbotId": string
"chatbotName": string
"metadata": object
"triggerPoint": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"outputHookLogs": [
{
"id": string (uuid)
"hook": string (uuid)
"hookName": string
"hookTypeLabel": string
"hookAction": string
"conversation": string (uuid)
"message": string (uuid)
"messageContent": string // Return the raw message text.
"chatbotId": string
"chatbotName": string
"metadata": object
"triggerPoint": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"instructionId": string
"llm":
{
"id": string (uuid)
"name": string
}
"effectiveMaxLlmOutputTokens": integer // この質疑応答で実際に使用された max_tokens の設定値です。Chatbot.custom_max_llm_output_tokens または LLM.max_tokens に由来する場合があります
"chatbot":
{
"id": string (uuid)
"name": string
}
"context": string
"conversationId": string (uuid)
"inboxId": string (uuid)
"botMessageId": string (uuid)
"userMessageId": string (uuid)
"creditCosts": [ // Return credit costs aggregated by item_code for credit-mode organizations.
object
]
"cacheSavedCredits": number (double) // Net credits saved by prompt caching for this reply; ``None`` outside credit mode.
Reuses the usage-statistics saving semantics (``compute_cache_saved_credits``)
on the reply's own billing batch, so the per-reply figure and the hourly
aggregate are defined by the same formula. The net value may be negative
(cache-creation premium exceeding read savings); the frontend hides
non-positive values by design.
"trace": object // Return the round trace timeline for the detail view; ``None`` for legacy records.
"llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory
"source": string // Origin discriminator for the unified /records/ response.
"schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here.
}
]
}
```
**レスポンス値の例**
```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",
"senderName": "レスポンス文字列",
"callerMemberId": "レスポンス文字列",
"callerMemberName": "レスポンス文字列",
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"inputMessage": "レスポンス文字列",
"condenseMessage": "レスポンス文字列",
"outputMessage": "レスポンス文字列",
"faithfulnessScore": 456,
"displayFaithfulnessScore": 456,
"answerRelevancyScore": 456,
"displayAnswerRelevancyScore": 456,
"contextPrecisionScore": 456,
"displayContextPrecisionScore": 456,
"answerCorrectnessScore": 456,
"displayAnswerCorrectnessScore": 456,
"answerSimilarityScore": 456,
"displayAnswerSimilarityScore": 456,
"contextRecallScore": 456,
"displayContextRecallScore": 456,
"replyTime": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"error": "レスポンス文字列",
"errorType": "system",
"processingTime": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"usage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"citationNodes": [
{
"id": "レスポンス文字列",
"text": "レスポンス文字列",
"chatbotFileId": "レスポンス文字列",
"fileName": "レスポンス文字列",
"url": "レスポンス文字列"
}
],
"inputHookLogs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"hook": "550e8400-e29b-41d4-a716-446655440000",
"hookName": "レスポンス文字列",
"hookTypeLabel": "レスポンス文字列",
"hookAction": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"message": "550e8400-e29b-41d4-a716-446655440000",
"messageContent": "レスポンス文字列",
"chatbotId": "レスポンス文字列",
"chatbotName": "レスポンス文字列",
"metadata": null,
"triggerPoint": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"outputHookLogs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"hook": "550e8400-e29b-41d4-a716-446655440000",
"hookName": "レスポンス文字列",
"hookTypeLabel": "レスポンス文字列",
"hookAction": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"message": "550e8400-e29b-41d4-a716-446655440000",
"messageContent": "レスポンス文字列",
"chatbotId": "レスポンス文字列",
"chatbotName": "レスポンス文字列",
"metadata": null,
"triggerPoint": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"instructionId": "レスポンス文字列",
"llm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"effectiveMaxLlmOutputTokens": 456,
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"context": "レスポンス文字列",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"botMessageId": "550e8400-e29b-41d4-a716-446655440000",
"userMessageId": "550e8400-e29b-41d4-a716-446655440000",
"creditCosts": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
],
"cacheSavedCredits": 456,
"trace": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"llmRawRequest": null,
"source": "レスポンス文字列",
"schedule": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
}
]
}
```
***
### 特定の会話レコードの取得
GET `/api/v1/records/{id}/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| ------ | -- | ------ | -------------------------------- |
| `id` | ✅ | string | この Chatbot レコードを識別する UUID 文字列です。 |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/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/records/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/records/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/records/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)
"senderName": string // ユーザーメッセージの送信者名を返します
"callerMemberId": string
"callerMemberName": string
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"inputMessage": string
"condenseMessage": string // チャット履歴とコンテキストを統合して調整されたユーザーメッセージ
"outputMessage": string
"faithfulnessScore": number (double) // チャットボットの回答がデータベースの内容と一致し、捏造されていないかを判定します
"displayFaithfulnessScore": integer
"answerRelevancyScore": number (double) // チャットボットの回答がユーザーの質問に関連しているかを判定します
"displayAnswerRelevancyScore": integer
"contextPrecisionScore": number (double) // チャットボットの回答が参照資料に関連しているかを判定します
"displayContextPrecisionScore": integer
"answerCorrectnessScore": number (double) // チャットボットの回答が正しいかを判定します（正解が必要です）
"displayAnswerCorrectnessScore": integer
"answerSimilarityScore": number (double) // チャットボットの回答が正解と類似しているかを判定します
"displayAnswerSimilarityScore": integer
"contextRecallScore": number (double) // チャットボットの回答が参照資料から関連情報を検索できるかを判定します
"displayContextRecallScore": integer
"replyTime": string
"createdAt": string (timestamp)
"error": string // 実行中に発生したエラーメッセージを保存します
"errorType": // 異なるタイプの場合があります
string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, hook_blocked, evaluation, other) // エラーの発生元（システム、LLM、Embedding、Reranker など）を区別します
* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `hook_blocked` - Hook Blocked
* `evaluation` - Evaluation
* `other` - Other
"processingTime": object // streaming_metrics の waterfall を含む、各処理段階の時間統計を返します
"usage": object // 文字数、トークン数、LLM 呼び出しごとのトークン明細を含む使用量統計を返します
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
"url": string
}
]
"inputHookLogs": [
{
"id": string (uuid)
"hook": string (uuid)
"hookName": string
"hookTypeLabel": string
"hookAction": string
"conversation": string (uuid)
"message": string (uuid)
"messageContent": string // Return the raw message text.
"chatbotId": string
"chatbotName": string
"metadata": object
"triggerPoint": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"outputHookLogs": [
{
"id": string (uuid)
"hook": string (uuid)
"hookName": string
"hookTypeLabel": string
"hookAction": string
"conversation": string (uuid)
"message": string (uuid)
"messageContent": string // Return the raw message text.
"chatbotId": string
"chatbotName": string
"metadata": object
"triggerPoint": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"instructionId": string
"llm":
{
"id": string (uuid)
"name": string
}
"effectiveMaxLlmOutputTokens": integer // この質疑応答で実際に使用された max_tokens の設定値です。Chatbot.custom_max_llm_output_tokens または LLM.max_tokens に由来する場合があります
"chatbot":
{
"id": string (uuid)
"name": string
}
"context": string
"conversationId": string (uuid)
"inboxId": string (uuid)
"botMessageId": string (uuid)
"userMessageId": string (uuid)
"creditCosts": [ // Return credit costs aggregated by item_code for credit-mode organizations.
object
]
"cacheSavedCredits": number (double) // Net credits saved by prompt caching for this reply; ``None`` outside credit mode.
Reuses the usage-statistics saving semantics (``compute_cache_saved_credits``)
on the reply's own billing batch, so the per-reply figure and the hourly
aggregate are defined by the same formula. The net value may be negative
(cache-creation premium exceeding read savings); the frontend hides
non-positive values by design.
"trace": object // Return the round trace timeline for the detail view; ``None`` for legacy records.
"llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory
"source": string // Origin discriminator for the unified /records/ response.
"schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here.
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"senderName": "レスポンス文字列",
"callerMemberId": "レスポンス文字列",
"callerMemberName": "レスポンス文字列",
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"inputMessage": "レスポンス文字列",
"condenseMessage": "レスポンス文字列",
"outputMessage": "レスポンス文字列",
"faithfulnessScore": 456,
"displayFaithfulnessScore": 456,
"answerRelevancyScore": 456,
"displayAnswerRelevancyScore": 456,
"contextPrecisionScore": 456,
"displayContextPrecisionScore": 456,
"answerCorrectnessScore": 456,
"displayAnswerCorrectnessScore": 456,
"answerSimilarityScore": 456,
"displayAnswerSimilarityScore": 456,
"contextRecallScore": 456,
"displayContextRecallScore": 456,
"replyTime": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"error": "レスポンス文字列",
"errorType": "system",
"processingTime": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"usage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"citationNodes": [
{
"id": "レスポンス文字列",
"text": "レスポンス文字列",
"chatbotFileId": "レスポンス文字列",
"fileName": "レスポンス文字列",
"url": "レスポンス文字列"
}
],
"inputHookLogs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"hook": "550e8400-e29b-41d4-a716-446655440000",
"hookName": "レスポンス文字列",
"hookTypeLabel": "レスポンス文字列",
"hookAction": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"message": "550e8400-e29b-41d4-a716-446655440000",
"messageContent": "レスポンス文字列",
"chatbotId": "レスポンス文字列",
"chatbotName": "レスポンス文字列",
"metadata": null,
"triggerPoint": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"outputHookLogs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"hook": "550e8400-e29b-41d4-a716-446655440000",
"hookName": "レスポンス文字列",
"hookTypeLabel": "レスポンス文字列",
"hookAction": "レスポンス文字列",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"message": "550e8400-e29b-41d4-a716-446655440000",
"messageContent": "レスポンス文字列",
"chatbotId": "レスポンス文字列",
"chatbotName": "レスポンス文字列",
"metadata": null,
"triggerPoint": "レスポンス文字列",
"createdAt": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
}
],
"instructionId": "レスポンス文字列",
"llm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"effectiveMaxLlmOutputTokens": 456,
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"context": "レスポンス文字列",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"botMessageId": "550e8400-e29b-41d4-a716-446655440000",
"userMessageId": "550e8400-e29b-41d4-a716-446655440000",
"creditCosts": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
],
"cacheSavedCredits": 456,
"trace": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"llmRawRequest": null,
"source": "レスポンス文字列",
"schedule": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
}
```
**ステータスコード: 404 - 指定された会話レコードが見つかりません**
***
### 特定の会話レコードを取得
GET `/api/v1/records/export-excel-requests/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| ----------- | -- | ------ | ------------------------------------------------ |
| `endDate` | ❌ | string | 終了日（形式：YYYY-MM-DD、例：2025-01-31） |
| `keyword` | ❌ | string | 特定キーワードを含む会話レコードを絞り込みます（ユーザーメッセージとボット応答を同時検索します） |
| `startDate` | ❌ | string | 開始日（形式：YYYY-MM-DD、例：2025-01-01） |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=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/records/export-excel-requests/?endDate=example&keyword=example&startDate=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/records/export-excel-requests/?endDate=example&keyword=example&startDate=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/records/export-excel-requests/?endDate=example&keyword=example&startDate=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 | Excel ファイルのダウンロード |
***
### 会話レコードのエクスポートリクエストを作成
POST `/api/v1/records/export-excel-requests/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| ----------- | -- | ------ | ------------------------------------------------ |
| `endDate` | ❌ | string | 終了日（形式：YYYY-MM-DD、例：2025-01-31） |
| `keyword` | ❌ | string | 特定キーワードを含む会話レコードを絞り込みます（ユーザーメッセージとボット応答を同時検索します） |
| `startDate` | ❌ | string | 開始日（形式：YYYY-MM-DD、例：2025-01-01） |
#### リクエストボディ
**リクエストパラメータ**
| フィールド | タイプ | 必須 | 説明 |
| ------------------ | ------------------ | --- | --------------------------------------------------------------------------------- |
| chatbot | string | いいえ | エクスポートする Chatbot UUID を指定します。カンマ区切りで複数指定できます。空欄の場合は組織内で権限のある全 Chatbot をエクスポートします。 |
| chatbotId | string (uuid) | いいえ | エクスポートする Chatbot UUID を指定します（chatbot の別名。単一 UUID のみ対応）。 |
| largeLanguageModel | string | いいえ | エクスポートする大規模言語モデル UUID を指定します。カンマ区切りで複数指定できます。 |
| startDatetime | string (timestamp) | いいえ | 正確な開始時刻（ISO 8601、この時点を含む）。一覧のドリルダウンフィルターと同じセマンティクスです。 |
| endDatetime | string (timestamp) | いいえ | 正確な終了時刻（ISO 8601、この時点を含まない）。一覧のドリルダウンフィルターと同じセマンティクスです。 |
| hasError | boolean | いいえ | エラーの有無で絞り込みます（true はエラーありのみ、false はエラーなしのみ）。 |
| errorType | string | いいえ | エラータイプで絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応し、値域は会話レコード一覧と同じです。 |
| hasFeedback | boolean | いいえ | ユーザー評価の有無で絞り込みます（true は高評価／低評価ありのみ、false は評価なしのみ）。 |
| feedbackType | string | いいえ | ユーザー評価タイプ（like / dislike）で絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応します。 |
| callerMember | string | いいえ | 発話メンバー UUID で絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応します。 |
**リクエスト構造の例**
```typescript
{
"chatbot"?: string // エクスポートする Chatbot UUID を指定します。カンマ区切りで複数指定できます。空欄の場合は組織内で権限のある全 Chatbot をエクスポートします。 (任意)
"chatbotId"?: string (uuid) // エクスポートする Chatbot UUID を指定します（chatbot の別名。単一 UUID のみ対応）。 (任意)
"largeLanguageModel"?: string // エクスポートする大規模言語モデル UUID を指定します。カンマ区切りで複数指定できます。 (任意)
"startDatetime"?: string (timestamp) // 正確な開始時刻（ISO 8601、この時点を含む）。一覧のドリルダウンフィルターと同じセマンティクスです。 (任意)
"endDatetime"?: string (timestamp) // 正確な終了時刻（ISO 8601、この時点を含まない）。一覧のドリルダウンフィルターと同じセマンティクスです。 (任意)
"hasError"?: boolean // エラーの有無で絞り込みます（true はエラーありのみ、false はエラーなしのみ）。 (任意)
"errorType"?: string // エラータイプで絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応し、値域は会話レコード一覧と同じです。 (任意)
"hasFeedback"?: boolean // ユーザー評価の有無で絞り込みます（true は高評価／低評価ありのみ、false は評価なしのみ）。 (任意)
"feedbackType"?: string // ユーザー評価タイプ（like / dislike）で絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応します。 (任意)
"callerMember"?: string // 発話メンバー UUID で絞り込みます。カンマ区切りの複数選択（OR ロジック）に対応します。 (任意)
}
```
**リクエスト値の例**
```json
{
"chatbot": "サンプル文字列",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "サンプル文字列",
"startDatetime": "サンプル文字列",
"endDatetime": "サンプル文字列",
"hasError": true,
"errorType": "サンプル文字列",
"hasFeedback": true,
"feedbackType": "サンプル文字列",
"callerMember": "サンプル文字列"
}
```
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbot": "サンプル文字列",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "サンプル文字列",
"largeLanguageModel": "サンプル文字列",
"startDate": "サンプル文字列",
"endDate": "サンプル文字列",
"startDatetime": "サンプル文字列",
"endDatetime": "サンプル文字列",
"hasError": true,
"errorType": "サンプル文字列",
"hasFeedback": true,
"feedbackType": "サンプル文字列",
"callerMember": "サンプル文字列"
}'
# 実行前に 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 = {
"chatbot": "サンプル文字列",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "サンプル文字列",
"largeLanguageModel": "サンプル文字列",
"startDate": "サンプル文字列",
"endDate": "サンプル文字列",
"startDatetime": "サンプル文字列",
"endDatetime": "サンプル文字列",
"hasError": true,
"errorType": "サンプル文字列",
"hasFeedback": true,
"feedbackType": "サンプル文字列",
"callerMember": "サンプル文字列"
};
axios.post("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", 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/records/export-excel-requests/?endDate=example&keyword=example&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# リクエストボディ（payload）
data = {
"chatbot": "サンプル文字列",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "サンプル文字列",
"largeLanguageModel": "サンプル文字列",
"startDate": "サンプル文字列",
"endDate": "サンプル文字列",
"startDatetime": "サンプル文字列",
"endDatetime": "サンプル文字列",
"hasError": true,
"errorType": "サンプル文字列",
"hasFeedback": true,
"feedbackType": "サンプル文字列",
"callerMember": "サンプル文字列"
}
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/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"chatbot": "サンプル文字列",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "サンプル文字列",
"largeLanguageModel": "サンプル文字列",
"startDate": "サンプル文字列",
"endDate": "サンプル文字列",
"startDatetime": "サンプル文字列",
"endDatetime": "サンプル文字列",
"hasError": true,
"errorType": "サンプル文字列",
"hasFeedback": true,
"feedbackType": "サンプル文字列",
"callerMember": "サンプル文字列"
}
]);
$data = json_decode($response->getBody(), true);
echo "レスポンス取得に成功しました:\n";
print_r($data);
} catch (Exception $e) {
echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### レスポンス
| ステータスコード | 説明 |
| -------- | ----------------- |
| 200 | Excel ファイルのダウンロード |
***
### 会話レコードのエクスポートステータスを取得
GET `/api/v1/records/export-excel-requests/{exportId}/`
#### パラメータ
| パラメータ名 | 必須 | タイプ | 説明 |
| ---------- | -- | ------ | -- |
| `exportId` | ✅ | string | |
#### コード例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/" \
-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/records/export-excel-requests/{exportId}/", 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/records/export-excel-requests/{exportId}/"
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/records/export-excel-requests/{exportId}/", [
'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)
"senderName": string // ユーザーメッセージ送信者の名前を返します
"callerMemberId": string
"callerMemberName": string
"inputMessage": string
"outputMessage": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"condenseMessage": string // チャット履歴とコンテキストを統合して調整されたユーザーメッセージ
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 任意
"updatedAt": string (timestamp)
}
"displayFaithfulnessScore": integer
"displayAnswerRelevancyScore": integer
"displayContextPrecisionScore": integer
"displayAnswerCorrectnessScore": integer
"displayAnswerSimilarityScore": integer
"displayContextRecallScore": integer
"replyTime": string
"processingTime": object // 一覧ページの処理時間統計を返します。詳細ページと同じ計算式ですが streaming_metrics waterfall は含みません
"usage": object // 文字数、token 数、各 LLM 呼び出しの token 明細を含む使用量統計を返します
"llm":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"conversationId": string (uuid)
"errorType": // 異なるタイプの場合があります
string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, hook_blocked, evaluation, other) // エラー元（システム、LLM、Embedding、Reranker など）を区別します
* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `hook_blocked` - Hook Blocked
* `evaluation` - Evaluation
* `other` - Other
"creditCosts": [
object
]
"source": string // Origin discriminator for the unified /records/ response.
"schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here.
}
```
**レスポンス値の例**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"senderName": "レスポンス文字列",
"callerMemberId": "レスポンス文字列",
"callerMemberName": "レスポンス文字列",
"inputMessage": "レスポンス文字列",
"outputMessage": "レスポンス文字列",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"condenseMessage": "レスポンス文字列",
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "レスポンス文字列",
"updatedAt": "レスポンス文字列"
},
"displayFaithfulnessScore": 456,
"displayAnswerRelevancyScore": 456,
"displayContextPrecisionScore": 456,
"displayAnswerCorrectnessScore": 456,
"displayAnswerSimilarityScore": 456,
"displayContextRecallScore": 456,
"replyTime": "レスポンス文字列",
"processingTime": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"usage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
},
"llm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス文字列"
},
"createdAt": "レスポンス文字列",
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"errorType": "system",
"creditCosts": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
],
"source": "レスポンス文字列",
"schedule": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "レスポンス例の名前",
"description": "レスポンス例の説明"
}
}
```
***
---
# 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 current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.maiagent.ai/api/ja/api-reference/dui-hua-he-xun-xi.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.