> 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 (9 個のプロパティを含む: 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 拡張機能など）が提供するツール定義の一覧です（任意）。各定義には name(str)、description(str)、input\_schema(dict) が必要です。LLM がツールを呼び出すと、バックエンドはツールを実行せず、clientToolCall の内容を返してこのターンを終了します。 | | message.sender | string (uuid) | いいえ | 送信者の Contact ID です（任意）。externalUser とは同時に指定できません | | message.externalUser | object (4 個のプロパティを含む: id, name, email...) | いいえ | 呼び出し元システムのユーザーとして質問します（任意）。MaiAgent は外部ユーザー ID に基づいて連絡先を検索または作成し、会話をその連絡先に関連付けます。sender とは同時に指定できず、両方を指定すると 400 を返します | | message.externalUser.id | string | はい | 呼び出し元システムのユーザー ID です（必須）。元の文字列と完全一致で照合し、大文字と小文字を区別します。空文字列または空白のみの場合は 400 を返します。MaiAgent は（組織, 外部ユーザー ID）に基づいて連絡先を検索または作成します。同じ組織で複数の外部システムを使用する場合は、projects:usr\_123 のようにシステムのプレフィックスを付けることを推奨します | | message.externalUser.name | string | いいえ | 連絡先の名前です（任意）。指定すると更新し、省略、null、空文字列の場合は変更しません。新規作成時に省略すると外部ユーザー ID を名前に使用します | | message.externalUser.email | object | いいえ | 連絡先のメールアドレスです（任意）。指定すると更新し、省略、null、空文字列の場合は変更しません。空でなく形式が不正な場合は 400 を返します | | message.externalUser.metadata | object | いいえ | 連絡先のカスタム情報です（任意）。連絡先 API の metadata と同じ形式です。指定すると全体を上書きし、省略または null の場合は変更しません | | 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 拡張機能など）が提供するツール定義の一覧です（任意）。各定義には name(str)、description(str)、input_schema(dict) が必要です。LLM がツールを呼び出すと、バックエンドはツールを実行せず、clientToolCall の内容を返してこのターンを終了します。 (任意) object ] "sender"?: string (uuid) // 送信者の Contact ID です（任意）。externalUser とは同時に指定できません (任意) "externalUser"?: // 呼び出し元システムのユーザーとして質問します（任意）。MaiAgent は外部ユーザー ID に基づいて連絡先を検索または作成し、会話をその連絡先に関連付けます。sender とは同時に指定できず、両方を指定すると 400 を返します (任意) { "id": string // 呼び出し元システムのユーザー ID です（必須）。元の文字列と完全一致で照合し、大文字と小文字を区別します。空文字列または空白のみの場合は 400 を返します。MaiAgent は（組織, 外部ユーザー ID）に基づいて連絡先を検索または作成します。同じ組織で複数の外部システムを使用する場合は、projects:usr_123 のようにシステムのプレフィックスを付けることを推奨します "name"?: string // 連絡先の名前です（任意）。指定すると更新し、省略、null、空文字列の場合は変更しません。新規作成時に省略すると外部ユーザー ID を名前に使用します (任意) "email"?: // 異なる型を取る場合があります (任意) string (email) // 連絡先のメールアドレスです（任意）。指定すると更新し、省略、null、空文字列の場合は変更しません。空でなく形式が不正な場合は 400 を返します (任意) "metadata"?: object // 連絡先のカスタム情報です（任意）。連絡先 API の metadata と同じ形式です。指定すると全体を上書きし、省略または null の場合は変更しません (任意) } } "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 | 会話のレスポンス内容です。ストリーミングの場合はイベントストリームになります | | 202 | Attachments are still being indexed: the body \`status\` is \`pending\_attachments\`; retry later. | | 400 | リクエストパラメータが不正です。原因として、Contact ID がその組織に属していないことなどが考えられます Error codes (X-Error-Code): \`contact\_not\_found\`, \`contact\_organization\_mismatch\`, \`contact\_inbox\_not\_linked\`, \`contact\_permission\_denied\`, \`message\_content\_required\`, \`... | | 401 | Error codes (X-Error-Code): \`not\_authenticated\`, \`authentication\_failed\`. | | 402 | Error codes (X-Error-Code): \`insufficient\_credits\`, \`insufficient\_quota\`, \`no\_active\_plan\`. | | 403 | Error codes (X-Error-Code): \`permission\_denied\`. | | 404 | Error codes (X-Error-Code): \`conversation\_not\_found\`, \`not\_found\`. | | 429 | Error codes (X-Error-Code): \`throttled\`. | *** ### メッセージの送信（作成） POST `/api/v1/messages/` #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------- | ------------------------------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------- | | conversation | string (uuid) | はい | | | type | string | いいえ | | | content | string | いいえ | | | contentPayload | object | いいえ | | | attachments | array\[MessageAttachmentInput] | いいえ | | | 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"?: [ // 任意 { "id": string (uuid) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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": null, "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": null, "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": null, "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": None, "citations": [] } ], "metadata": None }, "feedback": None, "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' => null, 'createdAt' => '1748314926000', 'attachments' => [], 'citations' => [], 'citationNodes' => [], 'canvas' => [ 'id' => '034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd', 'name' => 'system-architecture-diagram', 'canvasType' => 'markdown', 'title' => 'システム構成図', 'content' => '~~~mermaid graph TD A[ユーザー] --> B[フロントエンド画面] B --> C[API レイヤー] C --> D[データベース] ~~~', '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) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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 // File size in bytes "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 "ocrStatus": string // スキャンページの OCR 結果です。done、skipped、partial、off のいずれかです。解析前または古いファイルでは null です "ocrSkippedReason": string // スキャンページで OCR を実行しなかった理由です。no_azure_settings、azure_unavailable、insufficient_credits、transient_error、time_budget、disabled のいずれかです。完了した場合は null です "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 // Source title shown on the inline citation hover card. "citationDescription": string // Source description shown on the inline citation hover card. "citationQuote": string // Quoted text snippet shown on the inline citation hover card. "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 keys and values defined by the user. (任意) "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（ストリーミング中の仮想 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). "isGreeting": boolean // Whether this message is a greeting message. } ``` **レスポンスのサンプル値** ```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": null, "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\[MessageAttachmentInput] | いいえ | | | 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"?: [ // 任意 { "id": string (uuid) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "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": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "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": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "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": None, "attachments": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "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": [ None ] } }, "metadata": None, "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' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000', 'type' => new \stdClass(), 'filename' => 'document.pdf', 'file' => 'https://example.com/file.jpg', 'conversation' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'canvas' => [ 'name' => 'サンプル名', 'canvasType' => new \stdClass(), '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) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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 // File size in bytes "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 "ocrStatus": string // スキャンページの OCR 結果です：done、skipped、partial、off。解析前または旧ファイルでは null です "ocrSkippedReason": string // スキャンページで OCR が実行されなかった理由です：no_azure_settings、azure_unavailable、insufficient_credits、transient_error、time_budget、disabled。OCR が完了した場合は null です "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 // Source title shown on the inline citation hover card. "citationDescription": string // Source description shown on the inline citation hover card. "citationQuote": string // Quoted text snippet shown on the inline citation hover card. "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 keys and values defined by the user. (任意) "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（ストリーミング中の仮想 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). "isGreeting": boolean // Whether this message is a greeting message. } ``` **レスポンス値の例** ```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, "ocrStatus": "レスポンス文字列", "ocrSkippedReason": "レスポンス文字列", "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": "レスポンスのサンプル説明" }, "isGreeting": false } ``` *** ### 新しい会話を作成 POST `/api/v1/conversations/` #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ---------------- | ------------- | --- | -- | | webChat | string (uuid) | はい | | | contact | string (uuid) | いいえ | | | clientPlatform | object | いいえ | | | workingDirectory | string | いいえ | | **リクエストスキーマの例** ```typescript { "webChat": string (uuid) "contact"?: string (uuid) // 任意 "clientPlatform"?: // 任意 { } "workingDirectory"?: string // 任意 } ``` **リクエスト値の例** ```json { "webChat": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` #### コード例 {% 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 '{ "webChat": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }' # 実行前に 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 = { "webChat": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }; 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 = { "webChat": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } 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' => [ 'webChat' => '3fa85f64-5717-4562-b3fc-2c963f66afa6' ] ]); $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": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドだけを含め、inboxes、mcp_credentials、api_credentials を除外して、 N+1 クエリの問題を防ぎます。email / phone_number / metadata は Contact 自身のスカラーフィールドで、 フロントエンドの会話サイドバーで表示するために必要ですが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型になる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、省略時は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツからリスト内の項目を除外し、false の場合はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合、ラベルでフィルタリングしません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にはラベルのフィルターが適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件のリストです。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを意味します { "type"?: string // フォームの種類です。常に reasoning_effort です (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを低い順に示します。default は常に null です (任意) "canDisable"?: boolean // このモデルで思考を無効にできるかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントのどちらにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデル自身の判断による思考、またはプラットフォームのデフォルトレベルでの思考の有効化を意味します (任意) "unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null の場合は思考パラメータを送信せず、モデル自身のデフォルトを使用します (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 型が異なる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）です。分割で作成されていない場合は null です "continuedFrom": object // 分割で作成されたこの会話の引き継ぎ元です。{id, last_message_at, deleted} を返します。元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を返します。該当する会話がない場合は null です "continuationSummary": object // 引き継ぎの要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を返します（items は新しい順です）。分割で作成されていない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### メッセージ一覧の取得 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) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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 // File size in bytes "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 "ocrStatus": string // スキャンページの OCR 結果です。done、skipped、partial、off のいずれかです。解析前または旧ファイルの場合は null です "ocrSkippedReason": string // スキャンページで OCR を実行しなかった理由です。no_azure_settings、azure_unavailable、insufficient_credits、transient_error、time_budget、disabled のいずれかです。完了した場合は null です "previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー用に生成した PDF の URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外は None です。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式を統一します（各 ストレージプロバイダーの 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 // Source title shown on the inline citation hover card. "citationDescription": string // Source description shown on the inline citation hover card. "citationQuote": string // Quoted text snippet shown on the inline citation hover card. "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 keys and values defined by the user. (任意) "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（ストリーミング中の仮想 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). "isGreeting": boolean // Whether this message is a greeting message. } ] } ``` **レスポンス値の例** ```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, "ocrStatus": "レスポンス文字列", "ocrSkippedReason": "レスポンス文字列", "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": "レスポンスの説明の例" }, "isGreeting": false } ] } ``` *** ### 特定のメッセージを取得 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) // ID of an already-uploaded attachment, as returned by the attachment upload endpoint. Required: a missing, null or non-UUID id is rejected with HTTP 400 and the message is not created. "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 // File size in bytes "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 "ocrStatus": string // スキャンページの OCR 結果です。done、skipped、partial、off のいずれかです。解析前または旧ファイルの場合は null です "ocrSkippedReason": string // スキャンページで OCR を実行しなかった理由です。no_azure_settings、azure_unavailable、insufficient_credits、transient_error、time_budget、disabled のいずれかです。完了した場合は null です "previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー用に生成した PDF の URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外は None です。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式を統一します（各 ストレージプロバイダーの 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 // Source title shown on the inline citation hover card. "citationDescription": string // Source description shown on the inline citation hover card. "citationQuote": string // Quoted text snippet shown on the inline citation hover card. "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 keys and values defined by the user. (任意) "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（ストリーミング中の仮想 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). "isGreeting": boolean // Whether this message is a greeting message. } ``` **レスポンスの値の例** ```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, "ocrStatus": "レスポンス文字列", "ocrSkippedReason": "レスポンス文字列", "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": "レスポンスの説明の例" }, "isGreeting": false } ``` *** ### 会話一覧を取得 GET `/api/v1/conversations/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------------------------ | -- | ------- | ------------------------------------------------------------- | | `assignee` | ❌ | string | | | `chatbot` | ❌ | string | | | `contact` | ❌ | string | 連絡先 ID | | `contactTags` | ❌ | array | Multiple values may be separated by commas. | | `cursor` | ❌ | string | The pagination cursor value. | | `endDate` | ❌ | string | | | `externalConversationId` | ❌ | string | | | `externalSource` | ❌ | string | | | `inbox` | ❌ | string | 受信トレイ ID | | `isPinned` | ❌ | string | | | `keyword` | ❌ | string | キーワード検索 | | `kind` | ❌ | string | \`chat\`: Chat ; \`secretary\`: Secretary; | | `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&keyword=example&kind=chat&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&keyword=example&kind=chat&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&keyword=example&kind=chat&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&keyword=example&kind=chat&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 ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツを選択して一覧内の項目を除外します。false は一覧内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合、ラベルで絞り込みません（権限なしではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にはラベルフィルターが適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応します (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを意味します { "type"?: string // フォームの種類です。reasoning_effort に固定されています (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを低い順に示し、default は null に固定されています (任意) "canDisable"?: boolean // このモデルで思考を無効にできるかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントの両方で思考レベルが未設定の場合の動作です。off は思考なし（最速）、model_default はモデルが自ら思考するか、プラットフォームのデフォルトレベルにより思考が有効になることを意味します (任意) "unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null の場合は思考パラメータを送信せず、モデル自体のデフォルトに従います (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型になる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかを示します（会話プラットフォームの切り替え設定です。MaiGPT は常に true で、引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割でこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）で、分割によって作成されていない場合は null です "continuedFrom": object // 分割で作成された会話の引き継ぎ元です。{id, last_message_at, deleted} を含み、元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を含み、存在しない場合は null です "continuationSummary": object // 引き継ぎ要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を含みます（items は新しい順です）。分割によって作成されていない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ] } ``` **レスポンスの値の例** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "conversationKind": "レスポンス文字列" } ] } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 特定の会話を取得 GET `/api/v1/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": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーに表示するために必要です。N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型になる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、省略時は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全内容からリスト内の項目を除外して選択し、false はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合、ラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件のリストです。operator/conditions を入れ子にして組み合わせられます (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null は、このモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。常に reasoning_effort です (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを低い順に列挙し、default は常に null です (任意) "canDisable"?: boolean // このモデルで思考を無効にできるかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントのどちらにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデルが思考を判断するか、プラットフォームのデフォルトレベルで思考を有効にします (任意) "unsetLevel"?: string // レベル未設定時にプラットフォームが実際に送信するレベルです。null の場合は思考パラメーターを送信せず、モデル自体のデフォルトに従います (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型の場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割でこの会話が作成された理由です。resolved（解決後）または idle（アイドル状態）です。分割で作成されていない場合は null です "continuedFrom": object // 分割で作成された会話の引き継ぎ元です：{id, last_message_at, deleted}。元の会話が削除済みの場合、id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です：{id, created_at}。該当する会話がなければ null です "continuationSummary": object // 引き継ぎサマリーです：{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]}（items は新しい順です）。分割で作成されていない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 会話の名前を変更 PATCH `/api/v1/conversations/{id}/rename/` #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | ----- | ------ | --- | -- | | title | string | いいえ | | **リクエスト構造の例** ```typescript { "title"?: string // 任意 } ``` **リクエスト値の例** ```json { "title": "名前の例" } ``` #### コード例 {% 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 '{ "title": "名前の例" }' # 実行前に 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": "名前の例" }; 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 = { "title": "名前の例" } 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' => [ 'title' => '名前の例' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外し、 N+1 クエリの問題を防ぎます。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーで表示する必要がありますが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツからリスト内の項目を除外して選択し、false はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合、ラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件のリストです。operator/conditions を入れ子にして組み合わせられます (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null は、このモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。reasoning_effort に固定されています (任意) "fields"?: object // reasoning_effort フィールドです。options にはこのモデルが受け付ける思考レベルが低い順に並び、default は null に固定されています (任意) "canDisable"?: boolean // このモデルの思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話にもアシスタントにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデル自身の判断、またはプラットフォームのデフォルトレベルによって思考が有効になることを示します (任意) "unsetLevel"?: string // レベル未設定時にプラットフォームが実際に送信するレベルです。null は思考パラメータを送信せず、モデル自身のデフォルトに従うことを示します (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型を取り得ます string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎ設定とは独立しています） "autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）のいずれかです。分割で作成されていない場合は null です "continuedFrom": object // 分割で作成された会話の引き継ぎ元です：{id, last_message_at, deleted}。以前の会話が削除されている場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です：{id, created_at}。該当する会話がない場合は null です "continuationSummary": object // 引き継ぎサマリーです：{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]}（items は新しい順です）。分割で作成されていない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 会話の削除 DELETE `/api/v1/conversations/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X DELETE "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' } }; // リクエスト内容 (payload) const data = null; axios.delete("https://api.maiagent.ai/api/v1/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/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/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 | | 4XX | Error response; X-Error-Code carries its code (see "Error codes"). | *** ### AI 応答の停止 POST `/api/v1/conversations/{conversationId}/stop-response/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ---------------- | -- | ------ | -- | | `conversationId` | ✅ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/stop-response/" \ -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.post("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/stop-response/", 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/stop-response/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.post(url, 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/550e8400-e29b-41d4-a716-446655440000/stop-response/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 | ステータスコード | 説明 | | -------- | ------------------------------------------------------------------ | | 200 | No response body | | 4XX | Error response; X-Error-Code carries its code (see "Error codes"). | *** ### 会話の満足度を送信 POST `/api/v1/conversations/{id}/satisfaction/` {% hint style="info" %} 満足度は会話ごとに1回だけ送信できます。 {% endhint %} #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ------------------- | ------- | --- | ------------------------------------------------------------------------------------------- | | satisfactionScore | integer | はい | Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) | | satisfactionComment | string | いいえ | | **リクエストスキーマの例** ```typescript { "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment"?: string // 任意 } ``` **リクエスト値の例** ```json { "satisfactionScore": 5, "satisfactionComment": "回答が明確で、問題が解決しました" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/satisfaction/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "satisfactionScore": 5, "satisfactionComment": "回答が明確で、問題が解決しました" }' # 実行前に 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 = { "satisfactionScore": 5, "satisfactionComment": "回答が明確で、問題が解決しました" }; axios.post("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/satisfaction/", 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/satisfaction/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "satisfactionScore": 5, "satisfactionComment": "回答が明確で、問題が解決しました" } 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/550e8400-e29b-41d4-a716-446655440000/satisfaction/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'satisfactionScore' => 5, 'satisfactionComment' => '回答が明確で、問題が解決しました' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 201** **レスポンススキーマの例** ```typescript { "satisfactionScore": integer "satisfactionComment"?: string // 任意 "satisfactionSubmittedAt": string // 送信日時を表す ISO 8601 形式の UTC 文字列です。例：2026-10-09T15:10:48.717193Z } ``` **レスポンス値の例** ```json { "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列" } ``` **ステータスコード: 409 - この会話の満足度はすでに送信されています** *** ### 会話イベントの一覧取得 GET `/api/v1/conversations/{id}/events/` {% hint style="info" %} 有人対応への引き継ぎフローのイベント記録（`event_type`：`transfer_triggered`／`human_assigned`／`returned_to_ai`／`queue_timeout`）です。Webhook と照合できます。フローについては、技術マニュアルの[カスタマーサポートシステム連携](https://docs.maiagent.ai/tech/api-integration/customer-service-system-integration)をご覧ください。 {% endhint %} #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | -------------------------------------------- | | `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/events/" \ -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/events/", 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/events/" 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/events/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス本文 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外することで、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要です。N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 複数の型を取る場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null＝すべて検索不可（権限なし）、未指定＝制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合は、このフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true＝ナレッジベースの全内容を選択し、一覧の項目を除外します。false＝一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグで絞り込みません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にタグのフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null は、このモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。reasoning_effort 固定です (任意) "fields"?: object // reasoning_effort フィールドです。options は、このモデルで指定可能な思考レベルを低い順に示します。default は null 固定です (任意) "canDisable"?: boolean // このモデルの思考を無効にできるかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話にもアシスタントにも思考レベルが設定されていない場合の動作です。off＝思考しません（最速）。model_default＝モデル自身が思考を判断するか、プラットフォームのデフォルトレベルで思考が有効になります (任意) "unsetLevel"?: string // レベルが設定されていない場合にプラットフォームが実際に送信するレベルです。null は思考パラメーターを送信せず、モデル自身のデフォルトに従うことを示します (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 複数の型を取る場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled=プラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）／idle（非アクティブ）です。分割による作成でない場合は null です "continuedFrom": object // 分割によって作成された会話の引き継ぎ元です。{id, last_message_at, deleted} の形式です。元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} の形式です。存在しない場合は null です "continuationSummary": object // 引き継ぎ要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} の形式です（items は新しい順です）。分割による作成でない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 会話をメンバーに割り当て PATCH `/api/v1/conversations/{id}/assign/` {% hint style="info" %} 引き継ぐメンバーを設定し、AI の自動返信を無効にします。待機中の会話は進行中に変わります。 {% endhint %} #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエスト本文 **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | -------------- | -------------- | --- | -- | | assignee | string (uuid) | いいえ | | | transferReason | string | いいえ | | | tagIds | array\[string] | いいえ | | **リクエストスキーマの例** ```typescript { "assignee"?: string (uuid) // 任意 "transferReason"?: string // 任意 "tagIds"?: [ // 任意 string (uuid) ] } ``` **リクエストの値の例** ```json { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/assign/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "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 = { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/assign/", 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/assign/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } 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/assign/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'assignee' => '550e8400-e29b-41d4-a716-446655440000', 'transferReason' => 'サンプル文字列', 'tagIds' => [ '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 { "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 // 自社のメディアを相対ストレージキーとして保存し、外部 CDN の URL はそのまま保存します。 (任意) "email"?: // 複数の型を取り得ます (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // 会話ページの顧客パネルに表示するカスタム顧客情報です (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // 会話のペイロードに埋め込まれる受信トレイの概要です。 ``unread_conversations_count`` は、ドキュメント化された REST 会話 API の一部のため、 ここに残します。これは組織全体の非正規化されたカウンターです。 そのため、WS の送信処理では、ペイロードを :func:`strip_org_wide_unread_count` に通してから、 ``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 // 有効にすると、Source ID を提示する埋め込みチャットの訪問者は、以下の検証モードに従って検証を受け、ログインフローを経ずにチャットできます。無効の場合は既存の動作をすべて維持します。 (任意) "sourceIdVerifyMode"?: // 「署名検証を必須にする」: 埋め込み先サイトがバックエンドで計算した HMAC 署名を送信する必要があります。「Source ID のみ」: Source ID を知っている人なら誰でもその連絡先として操作できます。テストまたは閉域ネットワークでのみ使用してください。 * `signature` - 署名検証を必須にする * `raw` - Source ID のみ (任意) { } "sourceIdSignatureTtlMinutes"?: // 署名を使って連絡先の識別情報を取得できる期間です。セッションの有効期間ではありません。交換後のセッションは既存の WebChat の仕組みに従います。 * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // 有効にすると、AI が訪問者に代わって MCP や API ツールを呼び出す際に、訪問者がログインに使用した Keycloak アクセストークンを Authorization ヘッダーとして転送するため、ツールごとのログインが不要になります。Keycloak の認証元でのみ使用できます。ツールが自身の認証情報から解決した Authorization ヘッダーは上書きしません。訪問者の識別にはログイン時に会話に紐づけられた組織メンバーを使用し、連絡先の Source ID は使用しません。 (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // 訪問者の Keycloak トークンの送信を許可するツールのホスト名（または "*.example.com" 形式のワイルドカード）です (任意) string ] "organizationLogin": object // 認証元が "organization" の場合の訪問者のログイン方法です（管理画面のログインに対応します）。他の認証元では null です } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // 会話の受信トレイから取得したチャットボット（エージェント）の概要です。事前読み込み済みです。 ``is_maigpt`` により、クライアントは組織の ``maigpt_inbox`` ID と比較せずに、 デフォルトの MaiGPT エージェントを識別できます（アイコン、機能の有効判定）。 ``file_workspace_mode`` は実効 P6 モードです（MaiGPT、blueprint、 組織のファイルライブラリスイッチを適用済みです）。 "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` - 開始済み * `ringing` - 呼び出し中 * `in-progress` - 通話中 * `completed` - 完了 * `failed` - 失敗 * `busy` - 話し中 * `no-answer` - 応答なし * `canceled` - キャンセル済み (任意) "direction": string (enum: inbound, outbound) // * `inbound` - 着信 * `outbound` - 発信 "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // 受信トレイに届いたテキストメッセージに、現時点で AI が返信するかどうかを示します。 メッセージングチャネルでは、``is_auto_reply_now``（自動返信が有効で、 受信トレイの自動返信スケジュール内であること）と、受信トレイにチャットボットがあることが条件になります。 チャットボットの API Web チャットは、スケジュールを無視する completions エンドポイントが応答するため、 会話のスイッチだけで判断します。チャネルを参照するのは、Web 受信トレイで スケジュール外の場合だけです。 どの受信トレイでもスケジュールを無視する処理は、独自のルールで応答します。 対象は既存の会話を継続する completions エンドポイント（``completions_progress_status``）と、 音声エージェントが応答する音声ターンです。 "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 // ツールごとの有効／無効状態です: {tool_id: bool} (任意) "connectorMask"?: object // コネクタごとの有効／無効状態です: {connector_id: bool} (任意) "thinkingConfig"?: object // None は未設定（チャットボットの設定を継承）です。それ以外は {"reasoning_effort": } です (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを意味します { "type"?: string // フォームの種類です。常に reasoning_effort です (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを弱い順に示し、default は常に null です (任意) "canDisable"?: boolean // このモデルで思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントの両方で思考レベルが未設定の場合の実際の動作です。off は思考なし（最速）、model_default はモデル自身による判断、またはプラットフォームのデフォルトレベルによる思考の有効化を意味します (任意) "unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null は思考パラメーターを送信せず、モデル自身のデフォルトに任せることを意味します (任意) } } "effectiveThinkingConfig": object // 有効条件の判定と範囲制限を適用した後、この会話のモデルに次の返信で送信するレベルです。 保存された設定は、会話 > チャットボット > LLM 行のデフォルトレベルの順に解決します。None の場合、 モデルには思考パラメーターを送信せず、プロバイダーのデフォルトを適用します。 "llm": string (uuid) // 次の返信で使用するモデルです。会話で固定されたモデルを使用し、未指定の場合はアシスタントの現在のモデルを使用します。 TC-0205: 保存された ``conversation.llm`` を返すと、モデルを固定していない会話では、 アシスタントのモデル変更後に使用しなくなったモデルが表示されます。一方、``thinking_config_schema`` はすでに 実効モデルに従っています。読み取り専用です。表示しても会話でモデルが明示的に選択されたことにはなりません。 明示的な選択として扱うのは update-llm エンドポイントだけです。 "deepResearchStatus": // この会話の Deep Research の状態です * `not_used` - 未使用 * `started` - 開始済み * `running` - 実行中 * `completed` - 完了 * `failed` - 失敗 { } "deepResearchOutputFormat": // 複数の型を取り得ます string (enum: canvas, chat, file) // 完成したレポートの出力形式です。ユーザーが調査開始前の選択カードで形式をクリックしたときだけ設定し、Deep Research を開始または再設定するたびに NULL に戻します。NULL は明示的な選択なし（または計画をスキップするリクエスト）を意味し、表示時には Canvas を使用します。ただし、canvas を明示的に選択した場合とは区別されるため、フロントエンドは実際に選択された場合にのみカードをロックできます。Canvas 固定の動作に戻すには、この値を NULL/canvas に強制設定してください。再デプロイは不要です。 * `canvas` - Canvas * `chat` - チャットで返信 * `file` - ダウンロード可能なファイル "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - 未解決 * `resolved` - 解決済み * `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 // 会話の満足度を 5 段階で評価します（1=非常に不満、5=非常に満足） "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // 会話の現在の分析要約です（有効な要約リビジョンです）。 `setup_eager_loading` が追加する `latest_analysis_summary` アノテーションを読み取り、 N+1 クエリを防ぎます。すべての読み取り経路（list / retrieve / create）で事前読み込みを行うため、 アノテーションが存在します。空文字列にフォールバックするのは、 `setup_eager_loading` の外で作成されたインスタンスだけです。 "clientPlatform": // この会話を作成したクライアントのプラットフォームです（web、desktop） * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // デスクトップ会話に紐づけられたローカルフォルダーの絶対パスです。デスクトップ会話でのみ設定され、Web 会話では null です。 "slideProjectId": string "matchedField": string // インスタンスごとにキャッシュします。``get_matched_message_id`` / ``get_matched_snippet`` は 両方ともこの値を読み取るため、一度解決すれば、シリアライズされる会話ごとにキーワードと タイトルの一致判定を 3 回繰り返すことを防げます。 "matchedSnippet": string // 一致したメッセージからキーワードを中心に抜粋した、省略記号付きのテキストです。 ``ConversationViewSet._annotate_keyword_match`` が追加した ``matched_message_content`` アノテーションを読み取ります。追加のクエリは発生しません。 "matchedMessageId": string "pinnedAt": string (timestamp) // 会話をピン留めした日時です。null はピン留めされていないことを意味します。 "folder": string (uuid) // この会話を分類する、ユーザー定義のサイドバーフォルダーです。null は未分類を意味します（期間別のグループに表示します）。フォルダーを削除すると、会話は削除せず、この値を null に戻します。 "hasActiveBrowserSession": boolean // 再開可能な browser_use セッションのスナップショットが存在するかどうかを示します。 ページの再読み込み後に、フロントエンドがブラウザーパネルを 再要求（``browser:start`` を送信）すべきことを知らせます。 これにより、ライブの ``browser:frame`` プッシュが偶然先に届いた場合だけ パネルを表示する状態を防ぎます。 "callerOrganizationId": string // 紐づけられた呼び出し元の組織です（会話開始時に記録します）。未設定の場合は null です "handoff": object // 引き継ぎ情報です。enabled はプラットフォームのスイッチです。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームのスイッチで、MaiGPT は常に true です。引き継ぎスイッチとは独立しています） "autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）です。分割によって作成されていない場合は null です "continuedFrom": object // 分割された会話の接続元です。{id, last_message_at, deleted} を返します。以前の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を返します。存在しない場合は null です "continuationSummary": object // 会話の継続用要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を返します（items は新しい順です）。分割によって作成されていない場合は null です "conversationKind": string // chat はエージェントとのチャット、secretary はメンバーの個人秘書の Work チャットです } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - エラーレスポンスです。X-Error-Code にエラーコードが含まれます（「エラーコード」を参照してください）。** *** ### 会話の担当を引き受ける PATCH `/api/v1/conversations/{id}/claim/` {% hint style="info" %} 呼び出し元本人を担当メンバーに設定します。「会話の割り当て」と同じ効果があります。 {% endhint %} #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | --------------------- | | `id` | ✅ | string | この会話を識別する UUID 文字列です。 | #### リクエストボディ **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | -------------- | -------------- | --- | -- | | transferReason | string | いいえ | | | tagIds | array\[string] | いいえ | | **リクエストスキーマの例** ```typescript { "transferReason"?: string // 任意 "tagIds"?: [ // 任意 string (uuid) ] } ``` **リクエスト値の例** ```json { "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/claim/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "transferReason": "サンプル文字列", "tagIds": [ "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 = { "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/claim/", 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/claim/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } 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/claim/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'transferReason' => 'サンプル文字列', 'tagIds' => [ '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 { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して N+1 クエリの問題を防ぎます。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 の負荷は発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、省略時は制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方指定された場合はこのフィールドを優先します） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツから一覧の項目を除外し、false の場合は一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にはタグフィルターが適用されず、制限なしとなります (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null は、このモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。reasoning_effort 固定です (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルが受け付ける思考レベルを低い順に列挙し、default は null 固定です (任意) "canDisable"?: boolean // このモデルで思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話にもアシスタントにも思考レベルが設定されていない場合の実際の動作です。off は思考なし（最速）、model_default はモデルが自ら判断するか、プラットフォームのデフォルトレベルによって思考が有効になります (任意) "unsetLevel"?: string // レベル未設定時にプラットフォームが実際に送信するレベルです。null の場合は思考パラメーターを送信せず、モデル自体のデフォルトに従います (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型の場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割でこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）です。分割による作成でない場合は null です "continuedFrom": object // 分割で作成された会話の引き継ぎ元です。{id, last_message_at, deleted} を返します。元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を返します。該当する会話がない場合は null です "continuationSummary": object // 引き継ぎの要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を返します（items は新しい順です）。分割による作成でない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 会話を他のメンバーに転送します PATCH `/api/v1/conversations/{id}/transfer/` #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | -------------- | -------------- | --- | -- | | assignee | string (uuid) | いいえ | | | transferReason | string | いいえ | | | tagIds | array\[string] | いいえ | | **リクエスト構造の例** ```typescript { "assignee"?: string (uuid) // 任意 "transferReason"?: string // 任意 "tagIds"?: [ // 任意 string (uuid) ] } ``` **リクエストのサンプル値** ```json { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/transfer/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "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 = { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/transfer/", 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/transfer/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "assignee": "550e8400-e29b-41d4-a716-446655440000", "transferReason": "サンプル文字列", "tagIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } 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/transfer/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'assignee' => '550e8400-e29b-41d4-a716-446655440000', 'transferReason' => 'サンプル文字列', 'tagIds' => [ '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 { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外し、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自身のスカラーフィールドであり、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 複数の型を取り得ます (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、省略した場合は制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全内容からリスト内の項目を除外して選択します。false はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にはラベルフィルターが適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件のリストです。operator/conditions のネストした組み合わせに対応します (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。常に reasoning_effort です (任意) "fields"?: object // reasoning_effort フィールドです。options はこのモデルで指定可能な思考レベルを低い順に列挙します。default は常に null です (任意) "canDisable"?: boolean // このモデルの思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントのどちらにも思考レベルを設定していない場合の実際の動作です。off は思考なし（最速）、model_default はモデルが判断するか、プラットフォームのデフォルトレベルによって思考が有効になります (任意) "unsetLevel"?: string // レベル未設定時にプラットフォームが実際に送信するレベルです。null は思考パラメーターを送信せず、モデル自体のデフォルトを使用することを示します (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 複数の型を取り得ます string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。継続先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています） "autoSplitReason": string // 会話の自動分割によってこの会話が作成された理由です。resolved（解決後）または idle（アイドル状態）です。分割による作成でない場合は null です "continuedFrom": object // 分割で作成された会話の継続元です。{id, last_message_at, deleted} の形式で、元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} の形式で、存在しない場合は null です "continuationSummary": object // 継続用の要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} の形式です（items は新しい順です）。分割による作成でない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### AI による返信に戻す PATCH `/api/v1/conversations/{id}/return-to-ai/` {% hint style="info" %} 担当メンバーを解除して AI の自動返信を再開します。完了すると `handoff.returned_to_ai` Webhook イベントが送信されます。 {% endhint %} #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ------- | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | ------------------- | ------- | --- | -- | | requireContextReady | boolean | いいえ | | **リクエスト構造の例** ```typescript { "requireContextReady"?: boolean // 任意 } ``` **リクエスト値の例** ```json { "requireContextReady": true } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/return-to-ai/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "requireContextReady": 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 = { "requireContextReady": true }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/return-to-ai/", 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/return-to-ai/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "requireContextReady": True } 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/return-to-ai/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'requireContextReady' => true ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、 フロントエンドの会話サイドバーに表示する必要がありますが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型になる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id; ``file_workspace_mode`` is the effective P6 mode (MaiGPT, blueprint and the organization's file-library switch already applied). "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "willAiReplyNow": boolean // Whether a text message arriving through the inbox gets an AI reply right now. The messaging channels are gated by ``is_auto_reply_now`` (auto reply on and inside the inbox auto-reply schedule) and by the inbox having a chatbot. The chatbot's API web chat is answered by the completions endpoint, which ignores the schedule, so there the conversation switch alone decides. The channel is only looked up for a web inbox outside its schedule. Surfaces that ignore the schedule on any inbox answer from their own rule instead: the completions endpoint continuing an existing conversation (``completions_progress_status``) and voice turns, which the voice agent answers. "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索対象のナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、省略時は制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外するか、指定した項目のみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方が指定された場合はこのフィールドを優先します） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外するか、指定した項目のみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツを選択し、リスト内の項目を除外します。false の場合はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合、タグによる絞り込みは行いません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベースの検索にタグフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件のリストです。operator/conditions をネストして組み合わせられます (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": { // このモデルの思考設定フォームです。null はこのモデルに思考設定がないことを示します { "type"?: string // フォームの種類です。reasoning_effort 固定です (任意) "fields"?: object // reasoning_effort フィールドです。options にはこのモデルが受け付ける思考レベルを低い順に列挙します。default は null 固定です (任意) "canDisable"?: boolean // このモデルの思考を無効にできるかどうかを示します。true の場合、options に off が含まれます (任意) "unsetBehavior"?: string (enum: off, model_default) // 会話とアシスタントのどちらにも思考レベルが設定されていない場合の実際の動作です。off は思考しません（最速）。model_default はモデル自身が思考を判断するか、プラットフォームのデフォルトレベルで思考を有効にします (任意) "unsetLevel"?: string // レベルが未設定の場合にプラットフォームが実際に送信するレベルです。null の場合、思考パラメーターを送信せず、モデル自体のデフォルトに従います (任意) } } "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型になる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを示します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎ設定とは独立しています） "autoSplitReason": string // 会話の自動分割でこの会話が作成された理由です。resolved（解決後）／idle（アイドル状態）です。分割で作成されていない場合は null です "continuedFrom": object // 分割で作成されたこの会話の引き継ぎ元です。{id, last_message_at, deleted} を含みます。元の会話が削除済みの場合は id=null、deleted=true です "continuedTo": object // この会話から分割された最新の会話です。{id, created_at} を含みます。存在しない場合は null です "continuationSummary": object // 引き継ぎ要約です。{state: disabled|pending|ready|not_applied, items: [{conversation_id, content, generated_at, last_message_at, old_status}]} を含みます（items は新しい順です）。分割で作成されていない場合は null です "conversationKind": string // chat = a chat with an agent; secretary = the member's personal secretary Work chat } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ], "organizationLogin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "willAiReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "autoSplitReason": "レスポンス文字列", "continuedFrom": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuedTo": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "continuationSummary": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "conversationKind": "レスポンス文字列" } ``` **ステータスコード: 409 - Agent context not ready: \`detail\` plus \`agentContext\` (pending / failed writes)** *** ### 会話の出力ファイル一覧を取得 GET `/api/v1/conversations/{conversationId}/outputs/` {% hint style="info" %} レスポンスのフィールド（`count`、`source`、`results[]`）、表示範囲、並び順については、技術マニュアルの[会話の出力一覧 API](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/conversation-outputs-api)を参照してください。 {% endhint %} #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ---------------- | -- | ------ | -- | | `conversationId` | ✅ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/conversations/{conversationId}/outputs/" \ -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/{conversationId}/outputs/", 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/{conversationId}/outputs/" 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/{conversationId}/outputs/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ | ステータスコード | 説明 | | -------- | ------------------------------------------------------------------ | | 200 | No response body | | 4XX | Error response; X-Error-Code carries its code (see "Error codes"). | *** ### 会話を共有 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' => new \stdClass(), '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" ] } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 会話をクイック共有 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' => new \stdClass(), '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" ] } ``` **ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").** *** ### 共有された会話の一覧を取得 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 } "isOwner": boolean "messageCount": integer // Messages the share shows; the view counts a whole page at once (``context['message_counts']``). "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": "レスポンス文字列" }, "isOwner": false, "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 "shareScope": { } "permission": { } "sharedBy": { "id": string (uuid) "name": string } "isOwner": boolean "conversationId": string (uuid) // The original conversation, exposed only to the sharer while the share still follows it ("continue"). "groupIds": [ // Current recipients, for the sharer's settings dialog only. string (uuid) ] "memberIds": [ // Recipients that are still active members, so saving the dialog back as-is stays valid. string (uuid) ] "needsContinueReminder": boolean // True when the sharer can continue the original conversation and has not been warned yet. "createdAt": string (timestamp) "conversationSnapshot": object } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "shareScope": {}, "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "isOwner": false, "conversationId": "550e8400-e29b-41d4-a716-446655440000", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "needsContinueReminder": false, "createdAt": "レスポンス文字列", "conversationSnapshot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } } ``` *** ### 共有会話を更新 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; | | shareScope | string (enum: organization, group, member) | いいえ | `organization`: Organization ; `group`: Group ; `member`: Member; | | groupIds | array\[string] | いいえ | | | memberIds | array\[string] | いいえ | | **リクエストスキーマの例** ```typescript { "title"?: string // 省略可能 "description"?: string // 省略可能 "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only * `copy` - Copyable (省略可能) "shareScope"?: string (enum: organization, group, member) // * `organization` - Organization * `group` - Group * `member` - Member (省略可能) "groupIds"?: [ // 省略可能 string (uuid) ] "memberIds"?: [ // 省略可能 string (uuid) ] } ``` **リクエストのサンプル値** ```json { "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly", "shareScope": "organization", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` #### コード例 {% 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", "shareScope": "organization", "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 = { "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly", "shareScope": "organization", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }; 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", "shareScope": "organization", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } 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', 'shareScope' => 'organization', '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 { "title"?: string // 任意 "description"?: string // 任意 "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only * `copy` - Copyable (任意) "shareScope"?: string (enum: organization, group, member) // * `organization` - Organization * `group` - Group * `member` - Member (任意) "groupIds"?: [ // 任意 string (uuid) ] "memberIds"?: [ // 任意 string (uuid) ] } ``` **レスポンスの値の例** ```json { "title": "レスポンス文字列", "description": "レスポンス文字列", "permission": "readonly", "shareScope": "organization", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` *** ### 共有された会話を削除 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' => new \stdClass() ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に受信しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "title": string // Custom title for the shared conversation "description": string // Custom description for the shared conversation "shareScope": { } "permission": { } "sharedBy": { "id": string (uuid) "name": string } "isOwner": boolean "conversationId": string (uuid) // The original conversation, exposed only to the sharer while the share still follows it ("continue"). "groupIds": [ // Current recipients, for the sharer's settings dialog only. string (uuid) ] "memberIds": [ // Recipients that are still active members, so saving the dialog back as-is stays valid. string (uuid) ] "needsContinueReminder": boolean // True when the sharer can continue the original conversation and has not been warned yet. "createdAt": string (timestamp) "conversationSnapshot": object } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "shareScope": {}, "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "isOwner": false, "conversationId": "550e8400-e29b-41d4-a716-446655440000", "groupIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "needsContinueReminder": false, "createdAt": "レスポンス文字列", "conversationSnapshot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" } } ``` *** ### 自分の共有一覧を取得 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 } "isOwner": boolean "messageCount": integer // Messages the share shows; the view counts a whole page at once (``context['message_counts']``). "createdAt": string (timestamp) } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "shareScope": {}, "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "isOwner": false, "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' => new \stdClass(), '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' => new \stdClass(), '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... | | `excludeBuiltIn` | ❌ | boolean | true の場合、公式の組み込み Agent（Agent マーケットプレイスでレンタルして作成されたロック済みインスタンス）のデータを除外し、組織が独自に作成したアシスタントのみを返します。「独自アシスタントとしてコピー」で作成したコピーは独自作成に含まれます。省略した場合や false の場合、この条件による絞り込みは行いません。 | | `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 | | | `tool` | ❌ | 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&excludeBuiltIn=true&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&tool=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/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&excludeBuiltIn=true&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&tool=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/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&excludeBuiltIn=true&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&tool=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/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&excludeBuiltIn=true&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&tool=example", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "count": integer "next"?: string (uri) // 省略可能 "previous"?: string (uri) // 省略可能 "results": [ { "id": string (uuid) "senderName": string // ユーザーメッセージの送信者名を返します "callerMemberId": string "callerMemberName": string "feedback": { "id": string (uuid) "type": { } "suggestion"?: string // 省略可能 "updatedAt": string (timestamp) } "inputMessage": string "condenseMessage": string // User message rewritten from the chat history and context. "outputMessage": string "faithfulnessScore": number (double) // Whether the chatbot reply is grounded in the knowledge base rather than made up. "displayFaithfulnessScore": integer "answerRelevancyScore": number (double) // Whether the chatbot reply is relevant to the user's question. "displayAnswerRelevancyScore": integer "contextPrecisionScore": number (double) // Whether the chatbot reply is relevant to the reference context. "displayContextPrecisionScore": integer "answerCorrectnessScore": number (double) // Whether the chatbot reply is correct (requires a ground-truth answer). "displayAnswerCorrectnessScore": integer "answerSimilarityScore": number (double) // Whether the chatbot reply is similar to the ground-truth answer. "displayAnswerSimilarityScore": integer "contextRecallScore": number (double) // Whether the chatbot reply recalls the relevant information from the reference context. "displayContextRecallScore": integer "replyTime": string "createdAt": string (timestamp) "error": string // Error message raised during execution. "errorType": // 異なる型になる場合があります string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, hook_blocked, evaluation, other) // Error source: system, LLM, embedding, reranker, and so on. * `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 のウォーターフォールを含む、各処理段階の時間統計を返します "usage": { "words": // 文字数の統計 { "input": integer // ユーザーメッセージの文字数（画像の枚数から換算した文字数を含みます） "output": integer // AI アシスタントの回答文字数（画像の枚数から換算した文字数を含みます） "total": integer // input と output の合計 } "tokens": // トークン使用量 { "llm": // LLM トークン使用量 { "input": integer // LLM の入力トークン数 "output": integer // LLM の出力トークン数 "cacheCreationInputTokens": integer // プロンプトキャッシュに書き込んだ入力トークン数 "cacheReadInputTokens": integer // プロンプトキャッシュから読み取った入力トークン数 "total": integer // input、output、および 2 種類のキャッシュトークン数の合計 } "embedding": integer // テキストの embedding トークン数 "embeddingImage": integer // 画像の embedding トークン数 "reranker": integer // reranker に送信したチャンク数 } "llmCallBreakdown": [ // 各 LLM 呼び出しのトークン明細を呼び出し時刻順で返します。一覧エンドポイントでは常に空の配列となるため、詳細エンドポイントを使用してください { "sequence": integer // この回答内での LLM 呼び出しの順序（1 から始まります） "inputTokens": integer // この呼び出しの入力トークン数 "outputTokens": integer // この呼び出しの出力トークン数 "cacheCreationInputTokens": integer // この呼び出しでプロンプトキャッシュに書き込んだトークン数 "cacheReadInputTokens": integer // この呼び出しでプロンプトキャッシュから読み取ったトークン数 "processingTimeSecs": number (double) // この呼び出しの所要時間（秒）です。未記録の場合は null です "ttftSecs"?: number (double) // この呼び出しの最初のトークンまでの遅延（秒）です。未記録の場合は null となり、一部の古いレコードにはこのキーが含まれません（省略可能） } ] } "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 actually used for this reply, from Chatbot.custom_max_llm_output_tokens or LLM.max_tokens. "chatbot": { "id": string (uuid) "name": string } "context": string "conversationId": string (uuid) "inboxId": string (uuid) "botMessageId": string (uuid) "userMessageId": string (uuid) "creditCosts": [ // この回答で差し引かれたクレジットを課金項目別に集計します。組織がクレジット課金方式を使用していない場合は null です。クレジット課金方式でも、この回答にクレジットの差し引き取引がない場合は null です { "itemCode": string // 課金項目コード "itemName": string // 課金項目名 "category": string // 課金項目カテゴリ "credits": number (double) // この回答のこの課金項目で差し引かれたクレジットの合計 "quantity": number (double) // この課金項目の使用量合計（単位は課金項目によって異なります。例：トークン数） "unitPrice": number (double) // クレジット差し引き時点の単価のスナップショットです。単価が未記録の場合は null です "count": integer // この行にまとめられたクレジット差し引き取引の件数 } ] "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. "voiceOrigin": object // The voice session and turn that delegated this question here, if it was a delegation. } ] } ``` **レスポンス値の例** ```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": { "words": { "input": 456, "output": 456, "total": 456 }, "tokens": { "llm": { "input": 456, "output": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "total": 456 }, "embedding": 456, "embeddingImage": 456, "reranker": 456 }, "llmCallBreakdown": [ { "sequence": 456, "inputTokens": 456, "outputTokens": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "processingTimeSecs": 456, "ttftSecs": 456 } ] }, "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": [ { "itemCode": "レスポンス文字列", "itemName": "レスポンス文字列", "category": "レスポンス文字列", "credits": 456, "quantity": 456, "unitPrice": 456, "count": 456 } ], "cacheSavedCredits": 456, "trace": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "llmRawRequest": null, "source": "レスポンス文字列", "schedule": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" }, "voiceOrigin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス例の名前", "description": "レスポンス例の説明" } } ] } ``` *** ### 特定の会話レコードを取得 GET `/api/v1/records/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Chatbot Record. | #### コード例 {% 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 // User message rewritten from the chat history and context. "outputMessage": string "faithfulnessScore": number (double) // Whether the chatbot reply is grounded in the knowledge base rather than made up. "displayFaithfulnessScore": integer "answerRelevancyScore": number (double) // Whether the chatbot reply is relevant to the user's question. "displayAnswerRelevancyScore": integer "contextPrecisionScore": number (double) // Whether the chatbot reply is relevant to the reference context. "displayContextPrecisionScore": integer "answerCorrectnessScore": number (double) // Whether the chatbot reply is correct (requires a ground-truth answer). "displayAnswerCorrectnessScore": integer "answerSimilarityScore": number (double) // Whether the chatbot reply is similar to the ground-truth answer. "displayAnswerSimilarityScore": integer "contextRecallScore": number (double) // Whether the chatbot reply recalls the relevant information from the reference context. "displayContextRecallScore": integer "replyTime": string "createdAt": string (timestamp) "error": string // Error message raised during execution. "errorType": // 異なる型になる場合があります string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, hook_blocked, evaluation, other) // Error source: system, LLM, embedding, reranker, and so on. * `system` - システム * `llm` - LLM * `embedding` - 埋め込み * `reranker` - リランカー * `vector_db` - ベクトル DB * `workflow` - ワークフロー * `tool` - ツール * `timeout` - タイムアウト * `client_interrupt` - クライアントによる中断 * `hook_blocked` - フックによるブロック * `evaluation` - 評価 * `other` - その他 "processingTime": object // 各処理段階の時間統計を返します。streaming_metrics のウォーターフォールを含みます。 "usage": { "words": // 文字数の統計 { "input": integer // ユーザーメッセージの文字数です（画像の枚数から換算した文字数を含みます）。 "output": integer // AI アシスタントの返信の文字数です（画像の枚数から換算した文字数を含みます）。 "total": integer // input と output の合計です。 } "tokens": // トークン使用量 { "llm": // LLM のトークン使用量 { "input": integer // LLM の入力トークン数です。 "output": integer // LLM の出力トークン数です。 "cacheCreationInputTokens": integer // プロンプトキャッシュに書き込んだ入力トークン数です。 "cacheReadInputTokens": integer // プロンプトキャッシュから読み取った入力トークン数です。 "total": integer // input、output、および2種類のキャッシュトークン数の合計です。 } "embedding": integer // テキストの embedding トークン数です。 "embeddingImage": integer // 画像の embedding トークン数です。 "reranker": integer // reranker に送信したチャンク数です。 } "llmCallBreakdown": [ // LLM 呼び出しごとのトークン内訳です。呼び出し時刻順に並びます。一覧エンドポイントでは常に空の配列になるため、詳細エンドポイントを参照してください。 { "sequence": integer // この返信内での LLM 呼び出し順です。1から始まります。 "inputTokens": integer // この呼び出しの入力トークン数です。 "outputTokens": integer // この呼び出しの出力トークン数です。 "cacheCreationInputTokens": integer // この呼び出しでプロンプトキャッシュに書き込んだトークン数です。 "cacheReadInputTokens": integer // この呼び出しでプロンプトキャッシュから読み取ったトークン数です。 "processingTimeSecs": number (double) // この呼び出しの所要時間（秒）です。記録がない場合は null です。 "ttftSecs"?: number (double) // この呼び出しの最初のトークンまでの遅延（秒）です。記録がない場合は null です。一部の古いレコードにはこのキーがありません。 (任意) } ] } "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 // 元のメッセージテキストを返します。 "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 // 元のメッセージテキストを返します。 "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": [ // この返信のクレジット引き落としを課金項目別に集計したものです。組織がクレジット課金方式を使用していない場合は null です。使用していても、この返信に引き落とし取引がない場合は null です。 { "itemCode": string // 課金項目コード "itemName": string // 課金項目名 "category": string // 課金項目のカテゴリ "credits": number (double) // この返信で、この課金項目について引き落とされたクレジットの合計です。 "quantity": number (double) // この課金項目の使用量の合計です（単位は課金項目により異なり、トークン数などがあります）。 "unitPrice": number (double) // 引き落とし時点の単価のスナップショットです。単価が記録されていない場合は null です。 "count": integer // この行に集計された引き落とし取引の件数です。 } ] "cacheSavedCredits": number (double) // この返信でプロンプトキャッシュにより節約された正味のクレジットです。クレジットモード以外では ``None`` です。 使用量統計の節約額の計算方式（``compute_cache_saved_credits``）を 返信自体の課金バッチにも適用するため、返信ごとの値と時間単位の 集計値は同じ式で定義されます。正味の値は負になる場合があります （キャッシュ作成の割増料金が読み取りによる節約額を上回る場合）。フロントエンドは 仕様として、0以下の値を表示しません。 "trace": object // 詳細表示用にラウンドのトレースタイムラインを返します。旧形式のレコードでは ``None`` です。 "llmRawRequest": object // 最終ラウンドで LLM に送信した元のメッセージ配列です。システムプロンプトとメモリを含みます。 "source": string // 統合された /records/ レスポンスの出所を識別する値です。 "schedule": object // スケジュール実行の行と同じ構造です。スケジュール実行の行では、ここに所属先の ChatbotSchedule を紐付けます。 "voiceOrigin": object // この質問が委譲された場合に、委譲元の音声セッションとターンを示します。 } ``` **レスポンスの値の例** ```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": { "words": { "input": 456, "output": 456, "total": 456 }, "tokens": { "llm": { "input": 456, "output": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "total": 456 }, "embedding": 456, "embeddingImage": 456, "reranker": 456 }, "llmCallBreakdown": [ { "sequence": 456, "inputTokens": 456, "outputTokens": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "processingTimeSecs": 456, "ttftSecs": 456 } ] }, "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": [ { "itemCode": "レスポンス文字列", "itemName": "レスポンス文字列", "category": "レスポンス文字列", "credits": 456, "quantity": 456, "unitPrice": 456, "count": 456 } ], "cacheSavedCredits": 456, "trace": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "llmRawRequest": null, "source": "レスポンス文字列", "schedule": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "voiceOrigin": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } } ``` **ステータスコード: 404 - 指定された会話レコードが見つかりません。** *** ### 会話レコードのエクスポートリクエストの作成 POST `/api/v1/records/export-excel-requests/` #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ------------------ | ------------------ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chatbot | string | いいえ | エクスポートする Chatbot の UUID を指定します。複数の UUID をカンマ区切りで指定できます。空欄の場合は、組織内でアクセス権限があるすべての Chatbot をエクスポートします。 | | chatbotId | string (uuid) | いいえ | エクスポートする Chatbot の UUID を指定します（chatbot の別名で、単一の UUID のみ指定できます）。 | | keyword | string | いいえ | 指定したキーワードを含む会話レコードに絞り込みます（ユーザーメッセージとボットの返信を検索します）。 | | largeLanguageModel | string | いいえ | エクスポートする大規模言語モデルの UUID を指定します。複数の UUID をカンマ区切りで指定できます。 | | startDate | string (date) | いいえ | 開始日（YYYY-MM-DD）です。当日を含みます。 | | endDate | string (date) | いいえ | 終了日（YYYY-MM-DD）です。当日を含みます。 | | 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 条件）。 | | tool | string (uuid) | いいえ | このツールを呼び出した質問と回答に絞り込みます（ツールの UUID を指定します。プラットフォームの組み込みツールを含み、実行に失敗した場合も対象です）。 | | excludeBuiltIn | boolean | いいえ | true の場合、公式組み込み Agent（Agent マーケットプレイスからのレンタルで作成されたロック済みインスタンス）のデータを除外し、組織が独自に作成したアシスタントのみを含めます。「独自アシスタントとしてコピー」で作成したコピーは独自作成に該当します。省略した場合、または false の場合は、この条件による絞り込みを行いません。 | **リクエスト構造の例** ```typescript { "chatbot"?: string // エクスポートする Chatbot の UUID を指定します。複数の UUID をカンマ区切りで指定できます。空欄の場合は、組織内でアクセス権限があるすべての Chatbot をエクスポートします。 (任意) "chatbotId"?: string (uuid) // エクスポートする Chatbot の UUID を指定します（chatbot の別名で、単一の UUID のみ指定できます）。 (任意) "keyword"?: string // 指定したキーワードを含む会話レコードに絞り込みます（ユーザーメッセージとボットの返信を検索します）。 (任意) "largeLanguageModel"?: string // エクスポートする大規模言語モデルの UUID を指定します。複数の UUID をカンマ区切りで指定できます。 (任意) "startDate"?: string (date) // 開始日（YYYY-MM-DD）です。当日を含みます。 (任意) "endDate"?: string (date) // 終了日（YYYY-MM-DD）です。当日を含みます。 (任意) "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 条件）。 (任意) "tool"?: string (uuid) // このツールを呼び出した質問と回答に絞り込みます（ツールの UUID を指定します。プラットフォームの組み込みツールを含み、実行に失敗した場合も対象です）。 (任意) "excludeBuiltIn"?: boolean // true の場合、公式組み込み Agent（Agent マーケットプレイスからのレンタルで作成されたロック済みインスタンス）のデータを除外し、組織が独自に作成したアシスタントのみを含めます。「独自アシスタントとしてコピー」で作成したコピーは独自作成に該当します。省略した場合、または false の場合は、この条件による絞り込みを行いません。 (任意) } ``` **リクエストの値の例** ```json { "chatbot": "サンプル文字列", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "keyword": "サンプル文字列", "largeLanguageModel": "サンプル文字列", "startDate": "サンプル文字列", "endDate": "サンプル文字列", "startDatetime": "サンプル文字列", "endDatetime": "サンプル文字列", "hasError": true, "errorType": "サンプル文字列", "hasFeedback": true, "feedbackType": "サンプル文字列", "callerMember": "サンプル文字列", "tool": "550e8400-e29b-41d4-a716-446655440000", "excludeBuiltIn": true } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/records/export-excel-requests/" \ -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": "サンプル文字列", "tool": "550e8400-e29b-41d4-a716-446655440000", "excludeBuiltIn": 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 = { "chatbot": "サンプル文字列", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "keyword": "サンプル文字列", "largeLanguageModel": "サンプル文字列", "startDate": "サンプル文字列", "endDate": "サンプル文字列", "startDatetime": "サンプル文字列", "endDatetime": "サンプル文字列", "hasError": true, "errorType": "サンプル文字列", "hasFeedback": true, "feedbackType": "サンプル文字列", "callerMember": "サンプル文字列", "tool": "550e8400-e29b-41d4-a716-446655440000", "excludeBuiltIn": true }; axios.post("https://api.maiagent.ai/api/v1/records/export-excel-requests/", 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/" 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": "サンプル文字列", "tool": "550e8400-e29b-41d4-a716-446655440000", "excludeBuiltIn": 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/records/export-excel-requests/", [ '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' => 'サンプル文字列', 'tool' => '550e8400-e29b-41d4-a716-446655440000', 'excludeBuiltIn' => true ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 201** **レスポンス構造の例** ```typescript { "id": string (uuid) "userEmail": string (email) "recordType": // このエクスポートがどの監視一覧からリクエストされたかを示します。テキストのエクスポートではテキストレコード用のフィルターとして、音声のエクスポートでは音声セッション用のフィルターとして filter_params を読み取ります。 * `text` - テキストレコード * `voice` - 音声セッション { } "chatbotId": string (uuid) // エクスポートする Chatbot を指定します（非推奨です。chatbot_ids を使用してください）。 "chatbotIds": object // エクスポートする Chatbot の UUID の一覧です。空欄の場合は、組織内でアクセス権限があるすべての Chatbot をエクスポートします。 "startDate": string (date) // エクスポートするレコードの開始日です（当日を含みます）。 "endDate": string (date) // エクスポートするレコードの終了日です（当日を含みます）。 "status": { } "statusDisplay": string "fileUrl": string // ファイルの URL を返します（有効期限はありません）。 "fileSize": integer // ファイルサイズ（バイト） "recordCount": integer // エクスポートしたレコードの総数です。 "errorMessage": string "processingDurationSeconds": number (double) // 処理時間（秒）を計算します。 "createdAt": string (timestamp) "startedAt": string (timestamp) "completedAt": string (timestamp) } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "userEmail": "response@example.com", "recordType": {}, "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "chatbotIds": null, "startDate": "レスポンス文字列", "endDate": "レスポンス文字列", "status": {}, "statusDisplay": "レスポンス文字列", "fileUrl": "レスポンス文字列", "fileSize": 456, "recordCount": 456, "errorMessage": "レスポンス文字列", "processingDurationSeconds": 456, "createdAt": "レスポンス文字列", "startedAt": "レスポンス文字列", "completedAt": "レスポンス文字列" } ``` *** ### 会話レコードのエクスポート状況の取得 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 // User message rewritten from the chat history and context. "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": { "words": // 文字数の集計 { "input": integer // ユーザーメッセージの文字数です（画像の枚数に応じて換算した文字数を含みます） "output": integer // AI アシスタントの応答の文字数です（画像の枚数に応じて換算した文字数を含みます） "total": integer // input と output の合計です } "tokens": // トークン使用量 { "llm": // LLM トークン使用量 { "input": integer // LLM の入力トークン数です "output": integer // LLM の出力トークン数です "cacheCreationInputTokens": integer // プロンプトキャッシュに書き込む入力トークン数です "cacheReadInputTokens": integer // プロンプトキャッシュから読み取る入力トークン数です "total": integer // input、output、および 2 種類のキャッシュトークン数の合計です } "embedding": integer // テキストの embedding トークン数です "embeddingImage": integer // 画像の embedding トークン数です "reranker": integer // reranker に送信するチャンク数です } "llmCallBreakdown": [ // LLM 呼び出しごとのトークン内訳を呼び出し時刻順で示します。一覧エンドポイントでは常に空の配列です。詳細エンドポイントを参照してください { "sequence": integer // この応答内の LLM 呼び出しの順番です。1 から始まります "inputTokens": integer // この呼び出しの入力トークン数です "outputTokens": integer // この呼び出しの出力トークン数です "cacheCreationInputTokens": integer // この呼び出しでプロンプトキャッシュに書き込んだトークン数です "cacheReadInputTokens": integer // この呼び出しでプロンプトキャッシュから読み取ったトークン数です "processingTimeSecs": number (double) // この呼び出しの所要時間（秒）です。記録がない場合は null です "ttftSecs"?: number (double) // この呼び出しの最初のトークンまでの待ち時間（秒）です。記録がない場合は null です。一部の古いレコードにはこのキーがありません（任意） } ] } "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) // Error source: system, LLM, embedding, reranker, and so on. * `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": [ // この応答で差し引かれたクレジットを課金項目ごとに集計します。組織がクレジット課金方式を使用していない場合は null です。クレジット課金方式でも、この応答に差し引き取引がない場合は null です { "itemCode": string // 課金項目コード "itemName": string // 課金項目名 "category": string // 課金項目のカテゴリ "credits": number (double) // この応答で、この課金項目について差し引かれたクレジットの合計です "quantity": number (double) // この課金項目の使用量の合計です（単位は課金項目によって異なり、トークン数などです） "unitPrice": number (double) // 差し引き時点の単価のスナップショットです。単価が記録されていない場合は null です "count": integer // この行に集約された差し引き取引の件数です } ] "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": { "words": { "input": 456, "output": 456, "total": 456 }, "tokens": { "llm": { "input": 456, "output": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "total": 456 }, "embedding": 456, "embeddingImage": 456, "reranker": 456 }, "llmCallBreakdown": [ { "sequence": 456, "inputTokens": 456, "outputTokens": 456, "cacheCreationInputTokens": 456, "cacheReadInputTokens": 456, "processingTimeSecs": 456, "ttftSecs": 456 } ] }, "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "createdAt": "レスポンス文字列", "conversationId": "550e8400-e29b-41d4-a716-446655440000", "errorType": "system", "creditCosts": [ { "itemCode": "レスポンス文字列", "itemName": "レスポンス文字列", "category": "レスポンス文字列", "credits": 456, "quantity": 456, "unitPrice": 456, "count": 456 } ], "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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/api/ja/api-reference/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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.