> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/api-reference/dui-hua-he-xun-xi.md). # 会話とメッセージ ### メッセージ送信 (ストリーミング) POST `/api/v1/chatbots/{chatbotId}/completions/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------- | -- | ------ | -- | | `chatbotId` | ✅ | string | | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ---------------------- | ------------------------------------------------------------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | conversation | string (uuid) | いいえ | 会話の一意の識別子です。空の場合は新しい会話を作成します（任意） | | message | object (8 個のプロパティを含みます: content, contentPayload, queryMetadata...) | はい | 送信するメッセージの内容です | | message.content | string | はい | メッセージのテキスト内容です。添付ファイルを指定した場合は空文字列にできます | | message.contentPayload | object | いいえ | JSON 形式のメッセージの追加コンテンツペイロードです（任意） | | message.queryMetadata | object | いいえ | JSON 形式のクエリメタデータです（任意） | | message.metadata | object | いいえ | タイムゾーンなどの環境情報を含む、JSON 形式のメッセージメタデータです（任意） | | message.attachments | array\[AttachmentInput] | いいえ | メッセージの添付ファイルリストです（任意） | | message.toolIds | array\[string] | いいえ | このメッセージで有効にするツール ID のリストです（任意） | | message.clientTools | array\[any] | いいえ | このメッセージに対してクライアント（Chrome extension など）が提供するツール定義のリストです（任意）。各項目には name(str)、description(str)、input\_schema(dict) が必要です。LLM がツールを呼び出した際、バックエンドでは実行せず、clientToolCall の内容を返してこのターンを終了します。 | | message.sender | string (uuid) | いいえ | 送信者の Contact ID です（任意） | | isStreaming | boolean | いいえ | ストリーミングモードで応答するかどうかを指定します。デフォルトは false です（任意） | | waitForAttachments | boolean | いいえ | 添付ファイルの処理完了を待ってから agent workflow に進むかどうかを指定します。デフォルトは true です（任意） | **リクエスト構造の例** ```typescript { "conversation"?: string (uuid) // 会話の一意の識別子です。空の場合は新しい会話を作成します（任意） (任意) "message": // 送信するメッセージの内容です { "content": string // メッセージのテキスト内容です。添付ファイルを指定した場合は空文字列にできます "contentPayload"?: object // JSON 形式のメッセージの追加コンテンツペイロードです（任意） (任意) "queryMetadata"?: object // JSON 形式のクエリメタデータです（任意） (任意) "metadata"?: object // タイムゾーンなどの環境情報を含む、JSON 形式のメッセージメタデータです（任意） (任意) "attachments"?: [ // メッセージの添付ファイルリストです（任意） (任意) { "id": string (uuid) // 添付ファイルの一意の識別子です "type": // 添付ファイルの種類です。選択肢：image（画像）、video（動画、開発中のため未対応）、audio（音声）、sticker（スタンプ、開発中のため未対応）、other（その他） * `image` - Image * `video` - Video * `audio` - Audio * `sticker` - Sticker * `other` - Other { } "filename": string // 添付ファイル名です "file": string (uri) // 添付ファイルの URL です } ] "toolIds"?: [ // このメッセージで有効にするツール ID のリストです（任意） (任意) string (uuid) ] "clientTools"?: [ // このメッセージに対してクライアント（Chrome extension など）が提供するツール定義のリストです（任意）。各項目には name(str)、description(str)、input_schema(dict) が必要です。LLM がツールを呼び出した際、バックエンドでは実行せず、clientToolCall の内容を返してこのターンを終了します。 (任意) object ] "sender"?: string (uuid) // 送信者の Contact ID です（任意） (任意) } "isStreaming"?: boolean // ストリーミングモードで応答するかどうかを指定します。デフォルトは false です（任意） (任意) "waitForAttachments"?: boolean // 添付ファイルの処理完了を待ってから agent workflow に進むかどうかを指定します。デフォルトは true です（任意） (任意) } ``` **リクエストの値の例** ```json { "message": { "content": "こんにちは、自己紹介をしてください" }, "is_streaming": true } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": { "content": "こんにちは、自己紹介をしてください" }, "is_streaming": true }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "message": { "content": "こんにちは、自己紹介をしてください" }, "is_streaming": true }; axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", data, config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "message": { "content": "こんにちは、自己紹介をしてください" }, "is_streaming": True } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'message' => [ 'content' => 'こんにちは、自己紹介をしてください' ], 'is_streaming' => true ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ | ステータスコード | 説明 | | -------- | ---------------------------------------------------------- | | 200 | 会話の応答内容です。ストリーミングの場合はイベントストリームです | | 400 | リクエストパラメータが不正です。考えられる原因には、Contact ID がその組織に属していないことなどがあります | *** ### メッセージ送信 (作成) POST `/api/v1/messages/` #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------- | --------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | conversation | string (uuid) | はい | | | type | string | いいえ | | | content | string | いいえ | | | contentPayload | object | いいえ | | | attachments | array\[AttachmentCreateInput] | いいえ | | | canvas | object | いいえ | | | canvas.name | string | はい | | | canvas.canvasType | object | はい | | | canvas.title | string | はい | | | canvas.content | string | はい | | | slideTemplate | object (3 個のプロパティを含みます: slug, displayName, thumbnailUrls) | いいえ | | | slideTemplate.slug | string | はい | | | slideTemplate.displayName | string | はい | | | slideTemplate.thumbnailUrls | array\[string] | いいえ | | | queryMetadata | object | いいえ | クエリ可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください | | queryMetadata.knowledgeBases | array\[object] | いいえ | クエリ可能なナレッジベースのリストです。空の配列または null の場合はすべてクエリ不可（権限なし）となり、省略した場合は制限しません | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルによるフィルタリングを行いません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルのフィルタリングは適用されません（制限なしと同じです） | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件のリストです。operator/conditions のネストされた組み合わせに対応しています | | metadata | object | いいえ | Message metadata, such as timezone and other environment information | | broadcast | boolean | いいえ | | | skipCopilotTrigger | boolean | いいえ | | | suggestedForId | string (uuid) | いいえ | | | skillIds | array\[string] | いいえ | Per-message selected skill IDs from the WebChat client (camelCase: skillIds). | | toolIds | array\[string] | いいえ | Per-message selected tool IDs from the WebChat client (camelCase: toolIds). | | templateId | string (uuid) | いいえ | Document/sheet template ID for file-level compilation (camelCase: templateId). | **リクエスト構造の例** ```typescript { "conversation": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "contentPayload"?: object // 任意 "attachments"?: [ // 任意 { "type"?: // 任意 { } "filename": string "file": string (uri) "conversation"?: string (uuid) // 任意 } ] "canvas"?: { // 任意 { "name": string "canvasType": { } "title": string "content": string } } "slideTemplate"?: // 任意 { "slug": string "displayName": string "thumbnailUrls"?: [ // 任意 string ] } "queryMetadata"?: { // クエリ可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // クエリ可能なナレッジベースのリストです。空の配列または null の場合はすべてクエリ不可（権限なし）となり、省略した場合は制限しません (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目のみを指定します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外する項目または選択する項目のみを指定します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースのすべての内容を選択し、リスト内の項目を除外します。false の場合はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルによるフィルタリングを行いません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルのフィルタリングは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件のリストです。operator/conditions のネストされた組み合わせに対応しています (任意) object ] } } } } "metadata"?: object // Message metadata, such as timezone and other environment information (任意) "broadcast"?: boolean // 任意 "skipCopilotTrigger"?: boolean // 任意 "suggestedForId"?: string (uuid) // 任意 "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意) string (uuid) ] "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意) string (uuid) ] "templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意) } ``` **リクエストの値の例** ```json { "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2", "sender": { "id": 2.992461161002561e+38, "name": "jessiekuo", "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png" }, "type": "incoming", "content": "これはテストメッセージです", "contentPayload": { "content": "これはテストメッセージです", "items": [ { "type": "text", "text": "これはテストメッセージです", "startTimestamp": null, "citations": [] } ], "metadata": null }, "feedback": "like", "createdAt": "1748314926000", "attachments": [], "citations": [], "citationNodes": [], "canvas": { "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd", "name": "system-architecture-diagram", "canvasType": "markdown", "title": "システム構成図", "content": "~~~mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンド画面]\n B --> C[API レイヤー]\n C --> D[データベース]\n~~~", "createdAt": "1748314926000" } } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/messages/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2", "sender": { "id": 2.992461161002561e+38, "name": "jessiekuo", "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png" }, "type": "incoming", "content": "これはテストメッセージです", "contentPayload": { "content": "これはテストメッセージです", "items": [ { "type": "text", "text": "これはテストメッセージです", "startTimestamp": null, "citations": [] } ], "metadata": null }, "feedback": "like", "createdAt": "1748314926000", "attachments": [], "citations": [], "citationNodes": [], "canvas": { "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd", "name": "system-architecture-diagram", "canvasType": "markdown", "title": "システム構成図", "content": "~~~mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンド画面]\n B --> C[API レイヤー]\n C --> D[データベース]\n~~~", "createdAt": "1748314926000" } }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2", "sender": { "id": 2.992461161002561e+38, "name": "jessiekuo", "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png" }, "type": "incoming", "content": "これはテストメッセージです", "contentPayload": { "content": "これはテストメッセージです", "items": [ { "type": "text", "text": "これはテストメッセージです", "startTimestamp": null, "citations": [] } ], "metadata": null }, "feedback": "like", "createdAt": "1748314926000", "attachments": [], "citations": [], "citationNodes": [], "canvas": { "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd", "name": "system-architecture-diagram", "canvasType": "markdown", "title": "システム構成図", "content": "~~~mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンド画面]\n B --> C[API レイヤー]\n C --> D[データベース]\n~~~", "createdAt": "1748314926000" } }; axios.post("https://api.maiagent.ai/api/v1/messages/", data, config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/messages/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2", "sender": { "id": 2.992461161002561e+38, "name": "jessiekuo", "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png" }, "type": "incoming", "content": "これはテストメッセージです", "contentPayload": { "content": "これはテストメッセージです", "items": [ { "type": "text", "text": "これはテストメッセージです", "startTimestamp": None, "citations": [] } ], "metadata": None }, "feedback": "like", "createdAt": "1748314926000", "attachments": [], "citations": [], "citationNodes": [], "canvas": { "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd", "name": "system-architecture-diagram", "canvasType": "markdown", "title": "システム構成図", "content": "~~~mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンド画面]\n B --> C[API レイヤー]\n C --> D[データベース]\n~~~", "createdAt": "1748314926000" } } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/messages/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'conversation' => 'c96a0fb9-d106-4b16-8706-3906533bafa2', 'sender' => [ 'id' => 2.992461161002561e+38, 'name' => 'jessiekuo', 'avatar' => 'https://media-dev.maiagent.ai/static/images/default-user-avatar.png' ], 'type' => 'incoming', 'content' => 'これはテストメッセージです', 'contentPayload' => [ 'content' => 'これはテストメッセージです', 'items' => [ [ 'type' => 'text', 'text' => 'これはテストメッセージです', 'startTimestamp' => null, 'citations' => [] ] ], 'metadata' => null ], 'feedback' => 'like', 'createdAt' => '1748314926000', 'attachments' => [], 'citations' => [], 'citationNodes' => [], 'canvas' => [ 'id' => '034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd', 'name' => 'system-architecture-diagram', 'canvasType' => 'markdown', 'title' => 'システム構成図', 'content' => '~~~mermaid 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) "type"?: // 任意 { } "filename": string "file": string (uri) "expiresAt": string // ISO datetime when this attachment will be auto-deleted. For conversation-bound attachments: conversation.last_message_created_at + retention_days. For attachments without a conversation: created_at + retention_days. Returns None when cleanup is disabled (effective_from not set). "conversation"?: string (uuid) // 任意 } ] "citations": [ { "id": string (uuid) "filename": string // ファイル名 "file": string (uri) // アップロードするファイルです "fileType": string "knowledgeBase"?: // 任意 { "id": string (uuid) "name": string } "size": integer "status": { } "parser": { "id": string (uuid) "name": string "provider": { } "isTimestampSttProvider": boolean } "labels"?: [ // 任意 { "id": string (uuid) "name": string } ] "rawUserDefineMetadata"?: object // 任意 "speakerLabels": [ { "id": string (uuid) "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00) "customName"?: string // User-defined speaker name (e.g., John) (任意) "displayName": string } ] "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes) "chunksCount": integer // Number of chunks/nodes generated from this file "waitingTime": number (double) "processingTime": number (double) "processingTimeDetails": object "previewUrl": string // プレゼンテーション（pptx/ppt）の場合は、プレビュー可能な派生 pdf ファイルの URL を返します（フロントエンドでは PDF ビューアーで表示します）。それ以外の場合は None を返します。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式を統一します（各 storage provider の presign/host ルールを含みます）。get_absolute_url() は誤った形式の URL を生成するため、使用しないでください。 "createdAt": string (timestamp) } ] "citationNodes": [ { "chatbotTextNode": { { "id": string (uuid) "charactersCount": integer "hitsCount": integer "text": string "updatedAt": string (timestamp) "filename": string "chatbotFile": object // フロントエンドの画像プレビューに対応するため、ファイルの URL と種類を含む ChatbotFile の完全な情報を返します "knowledgeBaseFile": object // get_chatbot_file と同じ情報を返し、後方互換性を提供します "pageNumber": integer // Backward-compatible alias of ``page_start``. "pageStart": integer "pageEnd": integer "citationTitle": string // 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": "like", "createdAt": "1748314926000", "attachments": [], "citations": [], "citationNodes": [], "canvas": { "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd", "name": "system-architecture-diagram", "canvasType": "markdown", "title": "システム構成図", "content": "~~~mermaid\ngraph TD\n A[ユーザー] --> B[フロントエンド画面]\n B --> C[API レイヤー]\n C --> D[データベース]\n~~~", "createdAt": "1748314926000" } } ``` *** ### プロアクティブメッセージの送信 POST `/api/v1/messages/outgoing/` #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------- | --------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | conversation | string (uuid) | はい | | | type | string | いいえ | | | content | string | いいえ | | | contentPayload | object | いいえ | | | attachments | array\[AttachmentCreateInput] | いいえ | | | canvas | object | いいえ | | | canvas.name | string | はい | | | canvas.canvasType | object | はい | | | canvas.title | string | はい | | | canvas.content | string | はい | | | slideTemplate | object (3 つのプロパティを含みます: slug, displayName, thumbnailUrls) | いいえ | | | slideTemplate.slug | string | はい | | | slideTemplate.displayName | string | はい | | | slideTemplate.thumbnailUrls | array\[string] | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルによる絞り込みを行いません（権限なしを意味するものではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです） | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応します | | metadata | object | いいえ | Message metadata, such as timezone and other environment information | | broadcast | boolean | いいえ | | | skipCopilotTrigger | boolean | いいえ | | | suggestedForId | string (uuid) | いいえ | | | skillIds | array\[string] | いいえ | Per-message selected skill IDs from the WebChat client (camelCase: skillIds). | | toolIds | array\[string] | いいえ | Per-message selected tool IDs from the WebChat client (camelCase: toolIds). | | templateId | string (uuid) | いいえ | Document/sheet template ID for file-level compilation (camelCase: templateId). | **リクエストスキーマの例** ```typescript { "conversation": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "contentPayload"?: object // 任意 "attachments"?: [ // 任意 { "type"?: // 任意 { } "filename": string "file": string (uri) "conversation"?: string (uuid) // 任意 } ] "canvas"?: { // 任意 { "name": string "canvasType": { } "title": string "content": string } } "slideTemplate"?: // 任意 { "slug": string "displayName": string "thumbnailUrls"?: [ // 任意 string ] } "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合は、このフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツから一覧内の項目を除外して選択し、false は一覧内の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルによる絞り込みを行いません（権限なしを意味するものではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応します (任意) object ] } } } } "metadata"?: object // Message metadata, such as timezone and other environment information (任意) "broadcast"?: boolean // 任意 "skipCopilotTrigger"?: boolean // 任意 "suggestedForId"?: string (uuid) // 任意 "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意) string (uuid) ] "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意) string (uuid) ] "templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意) } ``` **リクエストの値の例** ```json { "conversation": "550e8400-e29b-41d4-a716-446655440000", "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。", "contentPayload": null, "attachments": [ { "type": {}, "filename": "document.pdf", "file": "https://example.com/file.jpg", "conversation": "550e8400-e29b-41d4-a716-446655440000" } ], "canvas": { "name": "サンプル名", "canvasType": {}, "title": "サンプル名", "content": "こんにちは！製品について詳しく知りたいです。" }, "slideTemplate": { "slug": "サンプル文字列", "displayName": "サンプル文字列", "thumbnailUrls": [ "サンプル文字列" ] }, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "metadata": null, "broadcast": true, "skipCopilotTrigger": true, "suggestedForId": "550e8400-e29b-41d4-a716-446655440000", "skillIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "toolIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "templateId": "550e8400-e29b-41d4-a716-446655440000" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/messages/outgoing/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "conversation": "550e8400-e29b-41d4-a716-446655440000", "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。", "contentPayload": null, "attachments": [ { "type": {}, "filename": "document.pdf", "file": "https://example.com/file.jpg", "conversation": "550e8400-e29b-41d4-a716-446655440000" } ], "canvas": { "name": "サンプル名", "canvasType": {}, "title": "サンプル名", "content": "こんにちは！製品について詳しく知りたいです。" }, "slideTemplate": { "slug": "サンプル文字列", "displayName": "サンプル文字列", "thumbnailUrls": [ "サンプル文字列" ] }, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "metadata": null, "broadcast": true, "skipCopilotTrigger": true, "suggestedForId": "550e8400-e29b-41d4-a716-446655440000", "skillIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "toolIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "templateId": "550e8400-e29b-41d4-a716-446655440000" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "conversation": "550e8400-e29b-41d4-a716-446655440000", "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。", "contentPayload": null, "attachments": [ { "type": {}, "filename": "document.pdf", "file": "https://example.com/file.jpg", "conversation": "550e8400-e29b-41d4-a716-446655440000" } ], "canvas": { "name": "サンプル名", "canvasType": {}, "title": "サンプル名", "content": "こんにちは！製品について詳しく知りたいです。" }, "slideTemplate": { "slug": "サンプル文字列", "displayName": "サンプル文字列", "thumbnailUrls": [ "サンプル文字列" ] }, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "metadata": null, "broadcast": true, "skipCopilotTrigger": true, "suggestedForId": "550e8400-e29b-41d4-a716-446655440000", "skillIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "toolIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "templateId": "550e8400-e29b-41d4-a716-446655440000" }; axios.post("https://api.maiagent.ai/api/v1/messages/outgoing/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/messages/outgoing/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト内容 (payload) data = { "conversation": "550e8400-e29b-41d4-a716-446655440000", "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。", "contentPayload": None, "attachments": [ { "type": {}, "filename": "document.pdf", "file": "https://example.com/file.jpg", "conversation": "550e8400-e29b-41d4-a716-446655440000" } ], "canvas": { "name": "サンプル名", "canvasType": {}, "title": "サンプル名", "content": "こんにちは！製品について詳しく知りたいです。" }, "slideTemplate": { "slug": "サンプル文字列", "displayName": "サンプル文字列", "thumbnailUrls": [ "サンプル文字列" ] }, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ 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' => [ [ '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) "type"?: // 任意 { } "filename": string "file": string (uri) "expiresAt": string // ISO datetime when this attachment will be auto-deleted. For conversation-bound attachments: conversation.last_message_created_at + retention_days. For attachments without a conversation: created_at + retention_days. Returns None when cleanup is disabled (effective_from not set). "conversation"?: string (uuid) // 任意 } ] "citations": [ { "id": string (uuid) "filename": string // ファイル名 "file": string (uri) // アップロードするファイル "fileType": string "knowledgeBase"?: // 任意 { "id": string (uuid) "name": string } "size": integer "status": { } "parser": { "id": string (uuid) "name": string "provider": { } "isTimestampSttProvider": boolean } "labels"?: [ // 任意 { "id": string (uuid) "name": string } ] "rawUserDefineMetadata"?: object // 任意 "speakerLabels": [ { "id": string (uuid) "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00) "customName"?: string // User-defined speaker name (e.g., John) (任意) "displayName": string } ] "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes) "chunksCount": integer // Number of chunks/nodes generated from this file "waitingTime": number (double) "processingTime": number (double) "processingTimeDetails": object "previewUrl": string // プレゼンテーション（pptx/ppt）の場合は、プレビュー可能な派生 pdf ファイルの URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外は None を返します。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式を統一します（各 storage provider の presign/host ルールを含みます）。get_absolute_url() は URL の形式が不正になるため、使用しないでください。 "createdAt": string (timestamp) } ] "citationNodes": [ { "chatbotTextNode": { { "id": string (uuid) "charactersCount": integer "hitsCount": integer "text": string "updatedAt": string (timestamp) "filename": string "chatbotFile": object // フロントエンドの画像プレビューをサポートするため、ファイルの URL と種類を含む ChatbotFile の全情報を返します "knowledgeBaseFile": object // get_chatbot_file と同じ情報を提供し、後方互換性を維持します "pageNumber": integer // Backward-compatible alias of ``page_start``. "pageStart": integer "pageEnd": integer "citationTitle": string // 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, "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/` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/conversations/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト本文 (payload) const data = {}; axios.post("https://api.maiagent.ai/api/v1/conversations/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/conversations/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト本文 (payload) data = {} response = requests.post(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/conversations/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => new \stdClass() ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 201** **レスポンススキーマの例** ```typescript { "id": string (uuid) "contact": { "id": string (uuid) "name": string "sourceId"?: string // 任意 } "lastMessageCreatedAt": string (timestamp) "autoReplyEnabled": boolean "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型の場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） "title": string } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "sourceId": "レスポンス文字列" }, "lastMessageCreatedAt": "レスポンス文字列", "autoReplyEnabled": false, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "title": "レスポンス文字列" } ``` *** ### メッセージ一覧を取得します GET `/api/v1/messages/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | -------------- | -- | ------- | ------------------------------------- | | `conversation` | ✅ | string | 会話 ID | | `cursor` | ❌ | string | The pagination cursor value. | | `pageSize` | ❌ | integer | Number of results to return per page. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "count": integer "next"?: string (uri) // 任意 "previous"?: string (uri) // 任意 "results": [ { "id": string (uuid) "conversation": string (uuid) "sender": { "id": string (uuid) "name": string "avatar": string "email"?: string (email) // 任意 "phoneNumber"?: string // 任意 } "type"?: string // 任意 "content"?: string // 任意 "contentPayload"?: object // 任意 "feedback": { "id": string (uuid) "type": { } "suggestion"?: string // 任意 "updatedAt": string (timestamp) } "createdAt": string (timestamp) "attachments"?: [ // 任意 { "id": string (uuid) "type"?: // 任意 { } "filename": string "file": string (uri) "expiresAt": string // ISO datetime when this attachment will be auto-deleted. For conversation-bound attachments: conversation.last_message_created_at + retention_days. For attachments without a conversation: created_at + retention_days. Returns None when cleanup is disabled (effective_from not set). "conversation"?: string (uuid) // 任意 } ] "citations": [ { "id": string (uuid) "filename": string // ファイル名 "file": string (uri) // アップロードするファイル "fileType": string "knowledgeBase"?: // 任意 { "id": string (uuid) "name": string } "size": integer "status": { } "parser": { "id": string (uuid) "name": string "provider": { } "isTimestampSttProvider": boolean } "labels"?: [ // 任意 { "id": string (uuid) "name": string } ] "rawUserDefineMetadata"?: object // 任意 "speakerLabels": [ { "id": string (uuid) "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00) "customName"?: string // User-defined speaker name (e.g., John) (任意) "displayName": string } ] "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes) "chunksCount": integer // Number of chunks/nodes generated from this file "waitingTime": number (double) "processingTime": number (double) "processingTimeDetails": object "previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー可能な派生 PDF ファイルの URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外は None を返します。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式の一貫性を確保します（各 storage provider の presign/host ルールを含みます）。get_absolute_url() は使用しないでください。生成される URL の形式が正しくありません。 "createdAt": string (timestamp) } ] "citationNodes": [ { "chatbotTextNode": { { "id": string (uuid) "charactersCount": integer "hitsCount": integer "text": string "updatedAt": string (timestamp) "filename": string "chatbotFile": object // フロントエンドの画像プレビューに対応するため、ファイルの URL と種類を含む ChatbotFile の完全な情報を返します "knowledgeBaseFile": object // get_chatbot_file と同じ情報を提供し、後方互換性を維持します "pageNumber": integer // Backward-compatible alias of ``page_start``. "pageStart": integer "pageEnd": integer "citationTitle": string // 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 reverse relation の DB クエリ（N+1 問題）の発生を回避します。 "broadcast"?: boolean // 任意 "skipCopilotTrigger"?: boolean // 任意 "activeRevisionNumber": integer "revisions": [ { "id": string (uuid) "revisionNumber": integer "content": string "contentPayload": object "isActive": boolean "createdAt": string (timestamp) } ] "suggestedForId"?: string (uuid) // 任意 "suggestionStatus": string "suggestionTriggerSource": string "suggestionError": string "retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"]. "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (任意) string (uuid) ] "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (任意) string (uuid) ] "templateId"?: string (uuid) // Document/sheet template ID for file-level compilation (camelCase: templateId). (任意) "videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery; ``errorMessage`` is blank to match the socket emit (raw value stays on the DB row). "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, "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) "type"?: // 任意 { } "filename": string "file": string (uri) "expiresAt": string // ISO datetime when this attachment will be auto-deleted. For conversation-bound attachments: conversation.last_message_created_at + retention_days. For attachments without a conversation: created_at + retention_days. Returns None when cleanup is disabled (effective_from not set). "conversation"?: string (uuid) // 任意 } ] "citations": [ { "id": string (uuid) "filename": string // ファイル名 "file": string (uri) // アップロードするファイル "fileType": string "knowledgeBase"?: // 任意 { "id": string (uuid) "name": string } "size": integer "status": { } "parser": { "id": string (uuid) "name": string "provider": { } "isTimestampSttProvider": boolean } "labels"?: [ // 任意 { "id": string (uuid) "name": string } ] "rawUserDefineMetadata"?: object // 任意 "speakerLabels": [ { "id": string (uuid) "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00) "customName"?: string // User-defined speaker name (e.g., John) (任意) "displayName": string } ] "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes) "chunksCount": integer // Number of chunks/nodes generated from this file "waitingTime": number (double) "processingTime": number (double) "processingTimeDetails": object "previewUrl": string // プレゼンテーション（pptx/ppt）の場合、プレビュー可能な派生 PDF ファイルの URL を返します（フロントエンドの PDF ビューアーで表示します）。それ以外は None を返します。 `file` フィールドと同じ CustomizedFileFieldSerializer で URL を生成し、形式の一貫性を確保します（各 storage provider の presign/host ルールを含みます）。get_absolute_url() は使用しないでください。生成される URL の形式が正しくありません。 "createdAt": string (timestamp) } ] "citationNodes": [ { "chatbotTextNode": { { "id": string (uuid) "charactersCount": integer "hitsCount": integer "text": string "updatedAt": string (timestamp) "filename": string "chatbotFile": object // フロントエンドの画像プレビューに対応するため、ファイルの URL と種類を含む ChatbotFile の完全な情報を返します "knowledgeBaseFile": object // get_chatbot_file と同じ情報を提供し、後方互換性を維持します "pageNumber": integer // Backward-compatible alias of ``page_start``. "pageStart": integer "pageEnd": integer "citationTitle": string // 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, "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 | | | `contactTags` | ❌ | array | Multiple values may be separated by commas. | | `cursor` | ❌ | string | The pagination cursor value. | | `endDate` | ❌ | string | | | `externalConversationId` | ❌ | string | | | `externalSource` | ❌ | string | | | `inbox` | ❌ | string | | | `isPinned` | ❌ | string | | | `mine` | ❌ | boolean | | | `mode` | ❌ | string | \`chat\`: Chat ; \`cowork\`: Cowork; | | `pageSize` | ❌ | integer | Number of results to return per page. | | `startDate` | ❌ | string | | | `status` | ❌ | array | \`open\`: Open ; \`resolved\`: Resolved ; \`queued\`: Queued; | | `tags` | ❌ | array | Multiple values may be separated by commas. | | `unassigned` | ❌ | boolean | | | `updatedAfter` | ❌ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z", config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&chatbot=550e8400-e29b-41d4-a716-446655440000&contact=550e8400-e29b-41d4-a716-446655440000&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=550e8400-e29b-41d4-a716-446655440000&isPinned=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2025-01-01T00:00:00.000Z", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "count": integer "next"?: string (uri) // 任意 "previous"?: string (uri) // 任意 "results": [ { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外することで、 N+1 クエリの問題を防ぎます。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーへの表示に必要です。N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて除外または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて除外または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true＝ナレッジベースの全コンテンツを選択し、一覧の項目を除外します。false＝一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしを意味するものではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にはラベルフィルターが適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 型が異なる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます。 "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています）。 } ] } ``` **レスポンスの値の例** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false } ] } ``` *** ### 特定の会話を取得 GET `/api/v1/conversations/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { "id": string (uuid) "name": string "sourceId"?: string // 任意 } "lastMessageCreatedAt": string (timestamp) "autoReplyEnabled": boolean "thinkingConfigSchema": object "effectiveThinkingConfig": object // 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. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 型が異なる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます。 "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true で、引き継ぎの切り替え設定とは独立しています）。 "title": string } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "sourceId": "レスポンス文字列" }, "lastMessageCreatedAt": "レスポンス文字列", "autoReplyEnabled": false, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false, "title": "レスポンス文字列" } ``` *** ### 会話の名前を変更 PATCH `/api/v1/conversations/{id}/rename/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | いいえ | Conversation List view 用の軽量な Contact Serializer です。List view に必要なフィールドのみを含み、N+1 クエリを避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | いいえ | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください。 | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）、省略は制限なしを意味します。 | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にはラベルフィルターが適用されません（制限なしと同じです）。 | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です。 | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions のネストした組み合わせに対応しています。 | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエスト構造の例** ```typescript { "contact"?: { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含み、inboxes、mcp_credentials、api_credentials を除外することで N+1 クエリを避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 (任意) { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 型が異なる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox"?: { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. (任意) { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "lastMessage"?: { // 任意 { "type"?: string // 任意 "content"?: string // 任意 } } "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索対象のナレッジ範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（アクセス権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合は、このフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツから一覧の項目を除外して選択し、false は一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルタ条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にタグフィルタは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法 "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 } ``` **リクエストのサンプル値** ```json { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト内容 (payload) data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": None, "phoneNumber": "サンプル文字列", "metadata": None, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": True }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'contact' => [ 'name' => 'サンプル名', 'avatar' => 'サンプル文字列', 'email' => null, 'phoneNumber' => 'サンプル文字列', 'metadata' => null, 'sourceId' => 'サンプル文字列' ], 'inbox' => [ 'name' => 'サンプル名', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => 'サンプル文字列', 'url' => 'サンプル文字列', 'realm' => 'サンプル文字列' ], 'line' => [ 'liffId' => 'サンプル文字列' ], 'ad' => [ 'saml' => 'サンプル文字列' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ 'サンプル文字列' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => 'サンプル文字列', 'content' => 'こんにちは！製品について詳しく知りたいです。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => 'サンプル文字列', 'queuedAt' => 'サンプル文字列', 'assignedAt' => 'サンプル文字列', 'transferReason' => 'サンプル文字列' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外し、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドであり、 フロントエンドの会話サイドバーでの表示に必要です。N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索対象のナレッジ範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（アクセス権限なし）、未指定は制限なしを意味します (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合は、このフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、一覧の項目を除外するか、一覧の項目のみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツから一覧の項目を除外して選択し、false は一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルタ条件です。conditions が空の配列の場合はタグで絞り込みません（アクセス権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にタグフィルタは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法 "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 型が異なる場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報：enabled=プラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "displayContextUsage": false } ``` *** ### 会話の削除 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 | *** ### 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 | *** ### 会話の満足度の送信 POST `/api/v1/conversations/{id}/satisfaction/` {% hint style="info" %} 各会話につき一度だけ送信できます。 {% endhint %} #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | はい | Conversation List view 用の軽量 Contact Serializer です。List view に必要なフィールドのみを含め、N+1 クエリを避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | はい | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）となり、未指定の場合は制限しません | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルでフィルタリングしません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定すると、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです） | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions の入れ子の組み合わせをサポートします | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエスト構造の例** ```typescript { "contact": { // Conversation List view 用の軽量 Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して N+1 クエリを避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 型が異なる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (省略可能) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (省略可能) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (省略可能) string ] } "enableAnalysis"?: boolean // 省略可能 } } "lastMessage"?: { // 省略可能 { "type"?: string // 省略可能 "content"?: string // 省略可能 } } "enableGroupMention"?: boolean // 省略可能 "queryMetadata"?: { // 検索メタデータです。検索可能なナレッジの範囲を制御します。詳細は各エンドポイントの説明を参照してください (省略可能) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）となり、省略した場合は制限しません (省略可能) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (省略可能) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合は、このフィールドを優先します） (省略可能) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (省略可能) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全内容を選択し、一覧内の項目を除外します。false の場合は一覧内の項目のみを選択します (省略可能) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグで絞り込みません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にはタグのフィルターが適用されません（制限なしと同じです） (省略可能) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法 "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (省略可能) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (省略可能) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (省略可能) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (省略可能) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (省略可能) "firstResponseAt"?: string (timestamp) // 省略可能 "queuedAt"?: string (timestamp) // 省略可能 "assignedAt"?: string (timestamp) // 省略可能 "transferReason"?: string // 省略可能 } ``` **リクエストの値の例** ```json { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X 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 '{ "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }; axios.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 = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": None, "phoneNumber": "サンプル文字列", "metadata": None, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": True }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について詳しく知りたいです。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } 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' => [ 'contact' => [ 'name' => 'サンプル名', 'avatar' => 'サンプル文字列', 'email' => null, 'phoneNumber' => 'サンプル文字列', 'metadata' => null, 'sourceId' => 'サンプル文字列' ], 'inbox' => [ 'name' => 'サンプル名', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => 'サンプル文字列', 'url' => 'サンプル文字列', 'realm' => 'サンプル文字列' ], 'line' => [ 'liffId' => 'サンプル文字列' ], 'ad' => [ 'saml' => 'サンプル文字列' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ 'サンプル文字列' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => 'サンプル文字列', 'content' => 'こんにちは！製品について詳しく知りたいです。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => 'サンプル文字列', 'queuedAt' => 'サンプル文字列', 'assignedAt' => 'サンプル文字列', 'transferReason' => 'サンプル文字列' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外して、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーで表示する必要がありますが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (省略可能) "email"?: // 複数の型を取り得ます (省略可能) string (email) // 省略可能 "phoneNumber"?: string // 省略可能 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (省略可能) "sourceId"?: string // 省略可能 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 省略可能 "signAuth"?: // 省略可能 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 省略可能 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (省略可能) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (省略可能) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (省略可能) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (省略可能) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (省略可能) string ] } "enableAnalysis"?: boolean // 省略可能 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 省略可能 { "id": string (uuid) "type"?: string // 省略可能 "content"?: string // 省略可能 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (省略可能) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 省略可能 "queryMetadata"?: { // 検索メタデータです。検索可能なナレッジの範囲を制御します。詳細は各エンドポイントの説明を参照してください (省略可能) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）となり、省略した場合は制限しません (省略可能) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (省略可能) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合は、このフィールドを優先します） (省略可能) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象になります） (省略可能) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全内容を選択し、一覧内の項目を除外します。false の場合は一覧内の項目のみを選択します (省略可能) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグで絞り込みません（権限がないという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にはタグのフィルターが適用されません（制限なしと同じです） (省略可能) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法 "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (省略可能) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (省略可能) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (省略可能) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (省略可能) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 複数の型を取り得ます string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます。 "displayContextUsage": boolean // コンテキスト使用率バーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています）。 } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスの名前の例", "description": "レスポンスの説明の例" }, "displayContextUsage": false } ``` *** ### 会話イベントの一覧取得 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 ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください。 (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）、未指定は制限なしを意味します。 (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します）。 (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方が指定された場合は、このフィールドを優先します）。 (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外対象または選択対象のみを指定します）。 (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースのすべての内容を選択し、リスト内の項目を除外します。false はリスト内の項目のみを選択します。 (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルによる絞り込みを行いません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベース検索にはラベルのフィルターが適用されません（制限なしと同等です）。 (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です。 "conditions"?: [ // ラベル条件のリストです。operator/conditions の入れ子の組み合わせに対応しています。 (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 複数の型を取り得ます string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます。 "displayContextUsage": boolean // コンテキスト使用率バーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています）。 } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "displayContextUsage": false } ``` *** ### 会話をメンバーに割り当てる PATCH `/api/v1/conversations/{id}/assign/` {% hint style="info" %} 引き継ぐメンバーを設定し、AI の自動返信を無効にします。待機中の会話は進行中になります。 {% endhint %} #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | いいえ | Conversation List view 用の軽量 Contact Serializer です。List view に必要なフィールドのみを含み、N+1 クエリの問題を避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーで表示する必要がありますが、N+1 の追加コストはありません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | いいえ | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能な知識の範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください。 | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースのリストです。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです。 | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルでフィルタリングしません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルフィルターは適用されません（制限なしと同じです）。 | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法 | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件のリストです。operator/conditions のネストした組み合わせに対応しています。 | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエストスキーマの例** ```typescript { "contact"?: { // Conversation List view 用の軽量 Contact Serializer です。 List view に必要なフィールドのみを含み、inboxes、mcp_credentials、api_credentials を除外して N+1 クエリの問題を避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドです。 フロントエンドの会話サイドバーで表示する必要がありますが、N+1 の追加コストはありません。 (任意) { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox"?: { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. (任意) { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "lastMessage"?: { // 任意 { "type"?: string // 任意 "content"?: string // 任意 } } "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能な知識の範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください。 (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです。 (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて、除外するか、リスト内の項目のみを選択します）。 (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます）。 (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて、除外するか、リスト内の項目のみを選択します）。 (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースのすべての内容を選択し、リスト内の項目を除外します。false の場合はリスト内の項目のみを選択します。 (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルでフィルタリングしません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルフィルターは適用されません（制限なしと同じです）。 (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法 "conditions"?: [ // ラベル条件のリストです。operator/conditions のネストした組み合わせに対応しています。 (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 } ``` **リクエスト値の例** ```json { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品情報について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/assign/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品情報について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品情報について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/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 = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": None, "phoneNumber": "サンプル文字列", "metadata": None, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": True }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について教えてください。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/assign/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'contact' => [ 'name' => 'サンプル名', 'avatar' => 'サンプル文字列', 'email' => null, 'phoneNumber' => 'サンプル文字列', 'metadata' => null, 'sourceId' => 'サンプル文字列' ], 'inbox' => [ 'name' => 'サンプル名', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => 'サンプル文字列', 'url' => 'サンプル文字列', 'realm' => 'サンプル文字列' ], 'line' => [ 'liffId' => 'サンプル文字列' ], 'ad' => [ 'saml' => 'サンプル文字列' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ 'サンプル文字列' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => 'サンプル文字列', 'content' => 'こんにちは！製品について教えてください。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => 'サンプル文字列', 'queuedAt' => 'サンプル文字列', 'assignedAt' => 'サンプル文字列', 'transferReason' => 'サンプル文字列' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外し、 N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自身のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要です。N+1 の負荷は発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースのリストです。空の配列または null はすべて検索不可（権限なし）を意味し、未指定の場合は制限しません (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象のみになります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID のリストです（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドを優先します） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID のリストです（hasUserSelectedAll に応じて除外対象または選択対象のみになります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true はナレッジベースの全コンテンツを選択し、リスト内の項目を除外します。false はリスト内の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグでフィルタリングしません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定すると、ナレッジベースの検索にタグフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件のリストです。operator/conditions のネストした組み合わせに対応します (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型の場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。継続先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかです（会話プラットフォームの切り替え設定で、MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "displayContextUsage": false } ``` *** ### 会話を引き受ける PATCH `/api/v1/conversations/{id}/claim/` {% hint style="info" %} 呼び出し元のユーザー自身を引き受けるメンバーに設定します。「会話を割り当てる」と同じ効果があります。 {% endhint %} #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | いいえ | Conversation List view 用の軽量な Contact Serializer です。List view に必要なフィールドのみを含め、N+1 クエリの問題を避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーでの表示に必要です。N+1 のコストは発生しません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | いいえ | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください。 | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしです。 | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルのフィルターは適用されません（制限なしと同じです）。 | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です。 | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています。 | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエスト構造の例** ```typescript { "contact"?: { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外します。 これにより N+1 クエリの問題を避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要です。N+1 のコストは発生しません。 (任意) { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 型が異なる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox"?: { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. (任意) { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "lastMessage"?: { // 任意 { "type"?: string // 任意 "content"?: string // 任意 } } "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください。 (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、省略した場合は制限なしです。 (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります）。 (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合はこのフィールドが優先されます）。 (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります）。 (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全内容を選択して一覧の項目を除外し、false の場合は一覧の項目のみを選択します。 (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルのフィルターは適用されません（制限なしと同じです）。 (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です。 "conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています。 (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 } ``` **リクエストの値の例** ```json { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出し例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/claim/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/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 = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": None, "phoneNumber": "サンプル文字列", "metadata": None, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": True }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/claim/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'contact' => [ 'name' => '名前の例', 'avatar' => '文字列の例', 'email' => null, 'phoneNumber' => '文字列の例', 'metadata' => null, 'sourceId' => '文字列の例' ], 'inbox' => [ 'name' => '名前の例', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => '文字列の例', 'url' => '文字列の例', 'realm' => '文字列の例' ], 'line' => [ 'liffId' => '文字列の例' ], 'ad' => [ 'saml' => '文字列の例' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ '文字列の例' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => '文字列の例', 'content' => 'こんにちは！製品について知りたいです。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => '文字列の例', 'queuedAt' => '文字列の例', 'assignedAt' => '文字列の例', 'transferReason' => '文字列の例' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量 Contact Serializer です List view に必要なフィールドのみを含み、inboxes、mcp_credentials および api_credentials を除外します これにより N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドです。 フロントエンドの会話サイドバーで表示する必要があり、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型の場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）で、省略した場合は制限しません (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、これらのファイルを除外するか、これらのみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名称です。両方を指定した場合は、このフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、これらの FAQ を除外するか、これらのみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true = ナレッジベースのすべてのコンテンツを選択し、一覧内の項目を除外します。false = 一覧内の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグでフィルタリングしません（権限がないという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にタグフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件の一覧です。operator/conditions の入れ子の組み合わせをサポートします (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型の場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled=プラットフォームの切り替え設定です。継続先の会話には source_conversation_id/source_title が含まれ、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定で、MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "displayContextUsage": false } ``` *** ### 他のメンバーに会話を転送します PATCH `/api/v1/conversations/{id}/transfer/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | -------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Conversation. | #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | いいえ | Conversation List view 用の軽量な Contact Serializer です。List view に必要なフィールドのみを含め、N+1 クエリを避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーに表示する必要がありますが、N+1 の負荷は発生しません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | いいえ | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください。 | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです。 | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしを意味するものではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです）。 | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です。 | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions のネストした組み合わせに対応しています。 | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエスト構造の例** ```typescript { "contact"?: { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外します。 これにより N+1 クエリを避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドです。 フロントエンドの会話サイドバーに表示する必要がありますが、N+1 の負荷は発生しません。 (任意) { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型を取る場合があります。 (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox"?: { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. (任意) { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "lastMessage"?: { // 任意 { "type"?: string // 任意 "content"?: string // 任意 } } "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください。 (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです。 (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象となります）。 (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方が指定された場合は、このフィールドが優先されます）。 (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外対象または選択対象となります）。 (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースのすべての内容を選択し、一覧の項目を除外します。false の場合は一覧の項目のみを選択します。 (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしを意味するものではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にラベルフィルターは適用されません（制限なしと同じです）。 (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です。 "conditions"?: [ // ラベル条件の一覧です。operator/conditions のネストした組み合わせに対応しています。 (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 } ``` **リクエストの値の例** ```json { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について教えてください。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/transfer/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について教えてください。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します。 const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト内容 (payload) const data = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": null, "phoneNumber": "サンプル文字列", "metadata": null, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": true }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について教えてください。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/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 = { "contact": { "name": "サンプル名", "avatar": "サンプル文字列", "email": None, "phoneNumber": "サンプル文字列", "metadata": None, "sourceId": "サンプル文字列" }, "inbox": { "name": "サンプル名", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "サンプル文字列", "url": "サンプル文字列", "realm": "サンプル文字列" }, "line": { "liffId": "サンプル文字列" }, "ad": { "saml": "サンプル文字列" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "サンプル文字列" ] }, "enableAnalysis": True }, "lastMessage": { "type": "サンプル文字列", "content": "こんにちは！製品について教えてください。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "サンプル文字列", "queuedAt": "サンプル文字列", "assignedAt": "サンプル文字列", "transferReason": "サンプル文字列" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/transfer/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'contact' => [ 'name' => 'サンプル名', 'avatar' => 'サンプル文字列', 'email' => null, 'phoneNumber' => 'サンプル文字列', 'metadata' => null, 'sourceId' => 'サンプル文字列' ], 'inbox' => [ 'name' => 'サンプル名', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => 'サンプル文字列', 'url' => 'サンプル文字列', 'realm' => 'サンプル文字列' ], 'line' => [ 'liffId' => 'サンプル文字列' ], 'ad' => [ 'saml' => 'サンプル文字列' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ 'サンプル文字列' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => 'サンプル文字列', 'content' => 'こんにちは！製品について詳しく知りたいです。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => 'サンプル文字列', 'queuedAt' => 'サンプル文字列', 'assignedAt' => 'サンプル文字列', 'transferReason' => 'サンプル文字列' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量 Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外します。 これにより N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型を取る場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空配列または null＝すべて検索不可（権限なし）、未指定＝制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて除外、または一覧の項目のみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方が指定された場合はこのフィールドを優先します） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて除外、または一覧の項目のみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true＝ナレッジベースのすべての内容を選択し、一覧の項目を除外します。false＝一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空配列の場合、タグによる絞り込みは行いません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にはタグのフィルターが適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法 "conditions"?: [ // タグ条件の一覧です。operator/conditions のネストされた組み合わせに対応します (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型を取る場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled=プラットフォームの切り替え設定です。引き継ぎ先の会話には source_conversation_id/source_title、引き継ぎ元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "displayContextUsage": false } ``` *** ### 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. | #### リクエスト内容 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | object | いいえ | Conversation List view 用の軽量な Contact Serializer です。List view に必要なフィールドのみを含め、N+1 クエリを避けるために inboxes、mcp\_credentials、api\_credentials を除外します。email / phone\_number / metadata は Contact 自体のスカラーフィールドで、フロントエンドの会話サイドバーでの表示に必要です。N+1 のコストは発生しません。 | | contact.name | string | はい | | | contact.avatar | string | いいえ | Stores our own media as a relative storage key, or an external CDN URL as-is. | | contact.email | object | いいえ | | | contact.phoneNumber | string | いいえ | | | contact.metadata | object | いいえ | Custom customer information shown in the customer panel of the conversation page | | contact.sourceId | string | いいえ | | | inbox | object | いいえ | Inbox summary embedded in a conversation payload. `unread_conversations_count` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS em... | | inbox.name | string | はい | | | inbox.channelType | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... | | inbox.unreadConversationsCount | integer | いいえ | | | inbox.signAuth | object (8 個のプロパティを含みます: id, signSource, signParams...) | いいえ | | | inbox.signAuth.signSource | string (uuid) | はい | | | inbox.signAuth.signParams | object | はい | | | inbox.signAuth.signParams.keycloak | object (3 個のプロパティを含みます: clientId, url, realm) | はい | | | inbox.signAuth.signParams.line | object (1 個のプロパティを含みます: liffId) | はい | | | inbox.signAuth.signParams.ad | object (1 個のプロパティを含みます: saml) | はい | | | inbox.signAuth.signParams.google | object (1 個のプロパティを含みます: enabled) | いいえ | | | inbox.signAuth.sourceIdAccessEnabled | boolean | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. | | inbox.signAuth.sourceIdVerifyMode | object | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin... | | inbox.signAuth.sourceIdSignatureTtlMinutes | object | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15; | | inbox.signAuth.keycloakTokenPassthrough | boolean | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to... | | inbox.signAuth.keycloakTokenPassthroughAllowedHosts | array\[string] | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to | | inbox.enableAnalysis | boolean | いいえ | | | lastMessage | object | いいえ | | | lastMessage.type | string | いいえ | | | lastMessage.content | string | いいえ | | | enableGroupMention | boolean | いいえ | | | queryMetadata | object | いいえ | 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください | | queryMetadata.knowledgeBases | array\[object] | いいえ | 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです | | queryMetadata.labelRelations | object | いいえ | ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルフィルターは適用されません（制限なしと同じです） | | queryMetadata.labelRelations.operator | string (enum: AND, OR) | はい | ラベル条件の組み合わせ方法です | | queryMetadata.labelRelations.conditions | array\[any] | いいえ | ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています | | toolMask | object | いいえ | Enabled/disabled state per tool: {tool\_id: bool} | | connectorMask | object | いいえ | Enabled/disabled state per connector: {connector\_id: bool} | | thinkingConfig | object | いいえ | None = not set (inherit the chatbot setting); otherwise {"reasoning\_effort": } | | status | string (enum: open, resolved, queued) | いいえ | `open`: Open ; `resolved`: Resolved ; `queued`: Queued; | | firstResponseAt | string (timestamp) | いいえ | | | queuedAt | string (timestamp) | いいえ | | | assignedAt | string (timestamp) | いいえ | | | transferReason | string | いいえ | | **リクエスト構造の例** ```typescript { "contact"?: { // Conversation List view 用の軽量な Contact Serializer です。 List view に必要なフィールドのみを含め、inboxes、mcp_credentials、api_credentials を除外します。 これにより N+1 クエリを避けます。email / phone_number / metadata は Contact 自体のスカラーフィールドです。 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 (任意) { "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型になる場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 } } "inbox"?: { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. (任意) { "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "lastMessage"?: { // 任意 { "type"?: string // 任意 "content"?: string // 任意 } } "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明をご覧ください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null の場合はすべて検索不可（権限なし）、未指定の場合は制限なしです (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて、除外するか、その項目のみを選択します） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方を指定した場合はこのフィールドが優先されます） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて、除外するか、その項目のみを選択します） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースの全コンテンツを選択し、一覧の項目を除外します。false の場合は一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // ラベルのフィルター条件です。conditions が空の配列の場合はラベルで絞り込みません（権限なしという意味ではありません）。knowledgeBases と一緒に指定する必要があります。単独で指定した場合、ナレッジベースの検索にラベルフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // ラベル条件の組み合わせ方法です "conditions"?: [ // ラベル条件の一覧です。operator/conditions の入れ子の組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 } ``` **リクエストの値の例** ```json { "contact": { "name": "名前の例", "avatar": "文字列の例", "email": null, "phoneNumber": "文字列の例", "metadata": null, "sourceId": "文字列の例" }, "inbox": { "name": "名前の例", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "文字列の例", "url": "文字列の例", "realm": "文字列の例" }, "line": { "liffId": "文字列の例" }, "ad": { "saml": "文字列の例" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "文字列の例" ] }, "enableAnalysis": true }, "lastMessage": { "type": "文字列の例", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "文字列の例", "queuedAt": "文字列の例", "assignedAt": "文字列の例", "transferReason": "文字列の例" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/return-to-ai/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "名前の例", "avatar": "文字列の例", "email": null, "phoneNumber": "文字列の例", "metadata": null, "sourceId": "文字列の例" }, "inbox": { "name": "名前の例", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "文字列の例", "url": "文字列の例", "realm": "文字列の例" }, "line": { "liffId": "文字列の例" }, "ad": { "saml": "文字列の例" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "文字列の例" ] }, "enableAnalysis": true }, "lastMessage": { "type": "文字列の例", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "文字列の例", "queuedAt": "文字列の例", "assignedAt": "文字列の例", "transferReason": "文字列の例" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト本文 (payload) const data = { "contact": { "name": "名前の例", "avatar": "文字列の例", "email": null, "phoneNumber": "文字列の例", "metadata": null, "sourceId": "文字列の例" }, "inbox": { "name": "名前の例", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "文字列の例", "url": "文字列の例", "realm": "文字列の例" }, "line": { "liffId": "文字列の例" }, "ad": { "saml": "文字列の例" }, "google": { "enabled": true } }, "sourceIdAccessEnabled": true, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": true, "keycloakTokenPassthroughAllowedHosts": [ "文字列の例" ] }, "enableAnalysis": true }, "lastMessage": { "type": "文字列の例", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": true, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": true } ], "labelRelations": { "operator": "AND", "conditions": [ null ] } }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "status": "open", "firstResponseAt": "文字列の例", "queuedAt": "文字列の例", "assignedAt": "文字列の例", "transferReason": "文字列の例" }; axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/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 = { "contact": { "name": "名前の例", "avatar": "文字列の例", "email": None, "phoneNumber": "文字列の例", "metadata": None, "sourceId": "文字列の例" }, "inbox": { "name": "名前の例", "channelType": "line", "unreadConversationsCount": 123, "signAuth": { "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "文字列の例", "url": "文字列の例", "realm": "文字列の例" }, "line": { "liffId": "文字列の例" }, "ad": { "saml": "文字列の例" }, "google": { "enabled": True } }, "sourceIdAccessEnabled": True, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": True, "keycloakTokenPassthroughAllowedHosts": [ "文字列の例" ] }, "enableAnalysis": True }, "lastMessage": { "type": "文字列の例", "content": "こんにちは！製品について知りたいです。" }, "enableGroupMention": True, "queryMetadata": { "knowledgeBases": [ { "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000", "chatbotFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "knowledgeBaseFileIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "faqIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "hasUserSelectedAll": True } ], "labelRelations": { "operator": "AND", "conditions": [ None ] } }, "toolMask": None, "connectorMask": None, "thinkingConfig": None, "status": "open", "firstResponseAt": "文字列の例", "queuedAt": "文字列の例", "assignedAt": "文字列の例", "transferReason": "文字列の例" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/return-to-ai/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'contact' => [ 'name' => '名前の例', 'avatar' => '文字列の例', 'email' => null, 'phoneNumber' => '文字列の例', 'metadata' => null, 'sourceId' => '文字列の例' ], 'inbox' => [ 'name' => '名前の例', 'channelType' => 'line', 'unreadConversationsCount' => 123, 'signAuth' => [ 'signSource' => '550e8400-e29b-41d4-a716-446655440000', 'signParams' => [ 'keycloak' => [ 'clientId' => '文字列の例', 'url' => '文字列の例', 'realm' => '文字列の例' ], 'line' => [ 'liffId' => '文字列の例' ], 'ad' => [ 'saml' => '文字列の例' ], 'google' => [ 'enabled' => true ] ], 'sourceIdAccessEnabled' => true, 'sourceIdVerifyMode' => new \stdClass(), 'sourceIdSignatureTtlMinutes' => new \stdClass(), 'keycloakTokenPassthrough' => true, 'keycloakTokenPassthroughAllowedHosts' => [ '文字列の例' ] ], 'enableAnalysis' => true ], 'lastMessage' => [ 'type' => '文字列の例', 'content' => 'こんにちは！製品について詳しく知りたいです。' ], 'enableGroupMention' => true, 'queryMetadata' => [ 'knowledgeBases' => [ [ 'knowledgeBaseId' => '550e8400-e29b-41d4-a716-446655440000', 'chatbotFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'knowledgeBaseFileIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'faqIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'hasUserSelectedAll' => true ] ], 'labelRelations' => [ 'operator' => 'AND', 'conditions' => [ null ] ] ], 'toolMask' => null, 'connectorMask' => null, 'thinkingConfig' => null, 'status' => 'open', 'firstResponseAt' => '文字列の例', 'queuedAt' => '文字列の例', 'assignedAt' => '文字列の例', 'transferReason' => '文字列の例' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "contact": { // Conversation List view 用の軽量 Contact Serializer です List view に必要なフィールドのみを含み、inboxes、mcp_credentials、api_credentials を除外して N+1 クエリの問題を回避します。email / phone_number / metadata は Contact 自体のスカラーフィールドで、 フロントエンドの会話サイドバーでの表示に必要ですが、N+1 のコストは発生しません。 { "id": string (uuid) "name": string "avatar"?: string // Stores our own media as a relative storage key, or an external CDN URL as-is. (任意) "email"?: // 異なる型を取る場合があります (任意) string (email) // 任意 "phoneNumber"?: string // 任意 "metadata"?: object // Custom customer information shown in the customer panel of the conversation page (任意) "sourceId"?: string // 任意 "tags": [ { "id": string (uuid) "name": string } ] } } "inbox": { // Inbox summary embedded in a conversation payload. ``unread_conversations_count`` stays here because it is part of the documented REST conversation API. It is an org-wide denormalized counter, so WS emit paths must run the payload through :func:`strip_org_wide_unread_count` before broadcasting it to rooms that include members without ``GroupInbox.can_view_conversations``. { "id": string (uuid) "name": string "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE * `telegram` - Telegram * `teams` - Teams * `web` - Web * `messenger` - Messenger * `instagram` - Instagram * `email` - Email * `whatsapp` - WhatsApp * `slack` - Slack * `team_plus` - Team+ * `line_works` - LINE WORKS * `viber` - Viber "unreadConversationsCount"?: integer // 任意 "signAuth"?: // 任意 { "id": string (uuid) "signSource": string (uuid) "signParams": { { "keycloak": { "clientId": string "url": string "realm": string } "line": { "liffId": string } "ad": { "saml": string } "google"?: // 任意 { "enabled": boolean } } } "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意) "sourceIdVerifyMode"?: // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks. * `signature` - Require signature verification * `raw` - Source ID only (任意) { } "sourceIdSignatureTtlMinutes"?: // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. * `1` - 1 * `5` - 5 * `15` - 15 (任意) { } "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意) "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意) string ] } "enableAnalysis"?: boolean // 任意 } } "chatbot": object // Chatbot (Agent) summary from the conversation's inbox, already eager-loaded. ``is_maigpt`` lets the client tell the default MaiGPT agent apart (icon, feature gate) without comparing against the organization's ``maigpt_inbox`` id. "title": string "lastMessage"?: { // 任意 { "id": string (uuid) "type"?: string // 任意 "content"?: string // 任意 "createdAt": string (timestamp) } } "callRecord": { "id": string (uuid) "status"?: string (enum: initiated, ringing, in-progress, completed, failed, busy, no-answer, canceled) // * `initiated` - Initiated * `ringing` - Ringing * `in-progress` - In Progress * `completed` - Completed * `failed` - Failed * `busy` - Busy * `no-answer` - No Answer * `canceled` - Canceled (任意) "direction": string (enum: inbound, outbound) // * `inbound` - Inbound * `outbound` - Outbound "isActive": boolean "canHangup": boolean } "lastMessageCreatedAt": string (timestamp) "unreadMessagesCount": integer "autoReplyEnabled": boolean "isAutoReplyNow": boolean "lastReadAt": string (timestamp) "createdAt": string (timestamp) "isGroupChat": boolean "enableGroupMention"?: boolean // 任意 "queryMetadata"?: { // 検索可能なナレッジの範囲を制御するクエリメタデータです。詳細は各エンドポイントの説明を参照してください (任意) { "knowledgeBases"?: [ // 検索可能なナレッジベースの一覧です。空の配列または null はすべて検索不可（権限なし）を意味し、省略した場合は制限しません (任意) { "knowledgeBaseId": string (uuid) // ナレッジベース ID "chatbotFileIds"?: [ // ファイル ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意) string (uuid) ] "knowledgeBaseFileIds"?: [ // ファイル ID の一覧です（chatbotFileIds の新しい名前です。両方が指定された場合はこのフィールドを優先します） (任意) string (uuid) ] "faqIds"?: [ // FAQ ID の一覧です（hasUserSelectedAll に応じて除外対象または選択対象になります） (任意) string (uuid) ] "hasUserSelectedAll"?: boolean // true の場合はナレッジベースのすべての内容を選択し、一覧の項目を除外します。false の場合は一覧の項目のみを選択します (任意) } ] "labelRelations"?: { // タグのフィルター条件です。conditions が空の配列の場合はタグで絞り込みません（権限なしという意味ではありません）。knowledgeBases と併せて指定する必要があります。単独で指定した場合、ナレッジベース検索にタグのフィルターは適用されません（制限なしと同じです） (任意) { "operator": string (enum: AND, OR) // タグ条件の組み合わせ方法です "conditions"?: [ // タグ条件の一覧です。operator/conditions のネストした組み合わせに対応しています (任意) object ] } } } } "toolMask"?: object // Enabled/disabled state per tool: {tool_id: bool} (任意) "connectorMask"?: object // Enabled/disabled state per connector: {connector_id: bool} (任意) "thinkingConfig"?: object // None = not set (inherit the chatbot setting); otherwise {"reasoning_effort": } (任意) "thinkingConfigSchema": object "effectiveThinkingConfig": object // The level the next reply sends on this conversation's model, after gating and clamping. The stored choice resolves conversation > chatbot > the LLM row's default level; None means the model sends no thinking parameter, so the provider default applies. "llm": string (uuid) // The model the next reply runs on: the conversation's pin, else its assistant's current model. TC-0205: returning the stored ``conversation.llm`` would show a model an unpinned conversation no longer uses once its assistant switches model, while ``thinking_config_schema`` already follows the effective model. Read-only: displaying it never marks the conversation as explicitly selected; only the update-llm endpoint does. "deepResearchStatus": // Status of deep research for this conversation * `not_used` - Not Used * `started` - Started * `running` - Running * `completed` - Completed * `failed` - Failed { } "deepResearchOutputFormat": // 異なる型を取る場合があります string (enum: canvas, chat, file) // Chosen delivery form for the finished report. Set only when the user clicks a format in the pre-research choice card; reset to NULL each time Deep Research is (re-)armed. NULL means no explicit choice (or a plan-skipping request) and falls back to Canvas at render time, but stays distinct from an explicit canvas pick so the frontend can lock the card only after a real selection. To roll back to fixed-Canvas behavior, force this to NULL/canvas — no redeploy needed. * `canvas` - Canvas * `chat` - Chat reply * `file` - Downloadable file "ipAddress": string "ipCountryCode": string "ipRecordedAt": string (timestamp) "assignee": { "id": string (uuid) "name": string "userId": string (uuid) } "status"?: string (enum: open, resolved, queued) // * `open` - Open * `resolved` - Resolved * `queued` - Queued (任意) "tags": [ { "id": string (uuid) "name": string "memberIds"?: [ // 任意 string (uuid) ] } ] "progressStatus": string "firstResponseAt"?: string (timestamp) // 任意 "queuedAt"?: string (timestamp) // 任意 "assignedAt"?: string (timestamp) // 任意 "transferReason"?: string // 任意 "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied) "satisfactionComment": string "satisfactionSubmittedAt": string (timestamp) "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision). Reads the `latest_analysis_summary` annotation added by `setup_eager_loading` to avoid an N+1 query. All read paths (list / retrieve / create) eager-load, so the annotation is present; it falls back to '' only for instances built outside `setup_eager_loading`. "clientPlatform": // Client platform that created this conversation (web, desktop) * `web` - Web * `desktop` - Desktop { } "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations. "slideProjectId": string "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet`` both read this, so resolving it once avoids recomputing the keyword and title-match logic three times per serialized conversation. "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses. Reads the ``matched_message_content`` annotation added by ``ConversationViewSet._annotate_keyword_match``; no extra query. "matchedMessageId": string "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned. "folder": string (uuid) // The user-defined sidebar folder this conversation is grouped into. Null means unclassified (shown under the time groups). Deleting the folder resets this to null without deleting the conversation. "hasActiveBrowserSession": boolean // Whether a browser_use session snapshot exists to resume. Lets the frontend know it should proactively re-request the browser panel (emit ``browser:start``) after a page reload, instead of only ever showing the panel when a live ``browser:frame`` push happens to arrive first. "callerOrganizationId": string // Bound caller organization (stamped at conversation start); null when unbound "handoff": object // 引き継ぎ情報です。enabled はプラットフォームの切り替え設定です。継続先の会話には source_conversation_id/source_title が含まれ、引き継がれる元の会話には continued_to_conversation_id/continued_to_title と latest_summary_message_id が含まれます "displayContextUsage": boolean // コンテキスト使用率のパーセントバーを表示するかどうかを指定します（会話プラットフォームの切り替え設定です。MaiGPT では常に true です。引き継ぎの切り替え設定とは独立しています） } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "contact": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "avatar": "レスポンス文字列", "email": "response@example.com", "phoneNumber": "レスポンス文字列", "metadata": null, "sourceId": "レスポンス文字列", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" } ] }, "inbox": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "channelType": "line", "unreadConversationsCount": 456, "signAuth": { "id": "550e8400-e29b-41d4-a716-446655440000", "signSource": "550e8400-e29b-41d4-a716-446655440000", "signParams": { "keycloak": { "clientId": "レスポンス文字列", "url": "レスポンス文字列", "realm": "レスポンス文字列" }, "line": { "liffId": "レスポンス文字列" }, "ad": { "saml": "レスポンス文字列" }, "google": { "enabled": false } }, "sourceIdAccessEnabled": false, "sourceIdVerifyMode": {}, "sourceIdSignatureTtlMinutes": {}, "keycloakTokenPassthrough": false, "keycloakTokenPassthroughAllowedHosts": [ "レスポンス文字列" ] }, "enableAnalysis": false }, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "title": "レスポンス文字列", "lastMessage": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "レスポンス文字列", "content": "レスポンス文字列", "createdAt": "レスポンス文字列" }, "callRecord": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "initiated", "direction": "inbound", "isActive": false, "canHangup": false }, "lastMessageCreatedAt": "レスポンス文字列", "unreadMessagesCount": 456, "autoReplyEnabled": false, "isAutoReplyNow": false, "lastReadAt": "レスポンス文字列", "createdAt": "レスポンス文字列", "isGroupChat": false, "enableGroupMention": false, "queryMetadata": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "toolMask": null, "connectorMask": null, "thinkingConfig": null, "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "effectiveThinkingConfig": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "llm": "550e8400-e29b-41d4-a716-446655440000", "deepResearchStatus": {}, "deepResearchOutputFormat": "canvas", "ipAddress": "レスポンス文字列", "ipCountryCode": "レスポンス文字列", "ipRecordedAt": "レスポンス文字列", "assignee": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "userId": "550e8400-e29b-41d4-a716-446655440000" }, "status": "open", "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列", "memberIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ], "progressStatus": "レスポンス文字列", "firstResponseAt": "レスポンス文字列", "queuedAt": "レスポンス文字列", "assignedAt": "レスポンス文字列", "transferReason": "レスポンス文字列", "satisfactionScore": 456, "satisfactionComment": "レスポンス文字列", "satisfactionSubmittedAt": "レスポンス文字列", "latestAnalysisSummary": "レスポンス文字列", "clientPlatform": {}, "workingDirectory": "レスポンス文字列", "slideProjectId": "レスポンス文字列", "matchedField": "レスポンス文字列", "matchedSnippet": "レスポンス文字列", "matchedMessageId": "レスポンス文字列", "pinnedAt": "レスポンス文字列", "folder": "550e8400-e29b-41d4-a716-446655440000", "hasActiveBrowserSession": false, "callerOrganizationId": "レスポンス文字列", "handoff": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンス説明の例" }, "displayContextUsage": false } ``` *** ### 会話の出力ファイルを一覧表示 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 | *** ### 会話を共有 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" ] } ``` *** ### 会話をすばやく共有 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" ] } ``` *** ### 共有された会話の一覧を取得 GET `/api/v1/shared-conversations/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ---------- | -- | ------- | ---------------------------------------------- | | `page` | ❌ | integer | A page number within the paginated result set. | | `pageSize` | ❌ | integer | Number of results to return per page. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス本文 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "count": integer "next"?: string (uri) // 任意 "previous"?: string (uri) // 任意 "results": [ { "id": string (uuid) "title": string // Custom title for the shared conversation "description": string // Custom description for the shared conversation "shareScope": { } "permission": { } "sharedBy": { "id": string (uuid) "name": string } "messageCount": integer "createdAt": string (timestamp) } ] } ``` **レスポンスの値の例** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "shareScope": {}, "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "messageCount": 456, "createdAt": "レスポンス文字列" } ] } ``` *** ### 特定の共有された会話を取得 GET `/api/v1/shared-conversations/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | --------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Shared Conversation. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス本文 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "title": string // Custom title for the shared conversation "description": string // Custom description for the shared conversation "permission": { } "sharedBy": { "id": string (uuid) "name": string } "createdAt": string (timestamp) "conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]} } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "createdAt": "レスポンス文字列", "conversationSnapshot": null } ``` *** ### 共有された会話を更新 PATCH `/api/v1/shared-conversations/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | --------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Shared Conversation. | #### リクエスト本文 **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ----------- | ----------------------------- | --- | ----------------------------------------- | | title | string | いいえ | | | description | string | いいえ | | | permission | string (enum: readonly, copy) | いいえ | `readonly`: Read Only ; `copy`: Copyable; | **リクエストスキーマの例** ```typescript { "title"?: string // 任意 "description"?: string // 任意 "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only * `copy` - Copyable (任意) } ``` **リクエストの値の例** ```json { "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエスト本文 (payload) const data = { "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly" }; axios.patch("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエスト本文 (payload) data = { "title": "サンプル名", "description": "サンプル文字列", "permission": "readonly" } response = requests.patch(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'title' => 'サンプル名', 'description' => 'サンプル文字列', 'permission' => 'readonly' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス本文 **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "title"?: string // 任意 "description"?: string // 任意 "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only * `copy` - Copyable (任意) } ``` **レスポンスの値の例** ```json { "title": "レスポンス文字列", "description": "レスポンス文字列", "permission": "readonly" } ``` *** ### 共有された会話を削除 DELETE `/api/v1/shared-conversations/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | --------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Shared Conversation. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X DELETE "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; // リクエストボディ (payload) const data = null; axios.delete("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.delete(url, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php delete("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ | ステータスコード | 説明 | | -------- | ---------------- | | 204 | No response body | *** ### 共有会話を複製 POST `/api/v1/shared-conversations/{id}/fork/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | --------------------------------------------------- | | `id` | ✅ | string | A UUID string identifying this Shared Conversation. | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = {}; axios.post("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", data, config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = {} response = requests.post(url, json=data, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => 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 "permission": { } "sharedBy": { "id": string (uuid) "name": string } "createdAt": string (timestamp) "conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]} } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "createdAt": "レスポンス文字列", "conversationSnapshot": null } ``` *** ### 自分の共有会話一覧を取得 GET `/api/v1/shared-conversations/my-shares/` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/my-shares/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/shared-conversations/my-shares/", config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/shared-conversations/my-shares/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/shared-conversations/my-shares/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンススキーマの例** ```typescript { "id": string (uuid) "title": string // Custom title for the shared conversation "description": string // Custom description for the shared conversation "shareScope": { } "permission": { } "sharedBy": { "id": string (uuid) "name": string } "messageCount": integer "createdAt": string (timestamp) } ``` **レスポンス値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "レスポンス文字列", "description": "レスポンス文字列", "shareScope": {}, "permission": {}, "sharedBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "messageCount": 456, "createdAt": "レスポンス文字列" } ``` *** ### メッセージのフィードバックを作成 POST `/api/v1/messages/{messagePk}/feedback/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ----------- | -- | ------ | -- | | `messagePk` | ✅ | string | | #### リクエストボディ **リクエストパラメータ** | フィールド | 型 | 必須 | 説明 | | ---------- | ------ | --- | -- | | type | object | はい | | | suggestion | string | いいえ | | **リクエストスキーマの例** ```typescript { "type": { } "suggestion"?: string // 任意 } ``` **リクエスト値の例** ```json { "type": {}, "suggestion": "サンプル文字列" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": {}, "suggestion": "サンプル文字列" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "type": {}, "suggestion": "サンプル文字列" }; axios.post("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/", data, config) .then(response => { console.log('レスポンスを取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "type": {}, "suggestion": "サンプル文字列" } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'type' => 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... | | `feedbackType` | ❌ | array | Multiple values may be separated by commas. \`like\`: Like ; \`dislike\`: Dislike; | | `hasError` | ❌ | boolean | | | `hasFeedback` | ❌ | boolean | | | `keyword` | ❌ | string | キーワード検索（ユーザーのメッセージとボットの回答の両方を検索します） | | `largeLanguageModel` | ❌ | string | 特定の大規模言語モデル (UUID) で絞り込みます | | `page` | ❌ | integer | A page number within the paginated result set. | | `pageSize` | ❌ | integer | Number of results to return per page. | | `source` | ❌ | string | 記録のソースをカンマ区切りで指定して絞り込みます。省略すると両方のソースを返します。interactive = ユーザーとの会話、scheduled = スケジュール実行。 | | `startDate` | ❌ | string | 開始日（形式：YYYY-MM-DD、例：2025-01-01） | | `startDatetime` | ❌ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエスト中にエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエスト中にエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/records/?callerMember=example&chatbot=example&endDate=example&endDatetime=2025-01-01T00:00:00.000Z&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&source=interactive&startDate=example&startDatetime=2025-01-01T00:00:00.000Z", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエスト中にエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンス内容 **ステータスコード: 200** **レスポンス構造の例** ```typescript { "count": integer "next"?: string (uri) // 任意 "previous"?: string (uri) // 任意 "results": [ { "id": string (uuid) "senderName": string // ユーザーメッセージの送信者名を返します "callerMemberId": string "callerMemberName": string "feedback": { "id": string (uuid) "type": { } "suggestion"?: string // 任意 "updatedAt": string (timestamp) } "inputMessage": string "condenseMessage": string // 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": object // 文字数、トークン数、および各 LLM 呼び出しのトークン内訳を含む使用量統計を返します "citationNodes": [ { "id": string "text": string "chatbotFileId": string "fileName": string "url": string } ] "inputHookLogs": [ { "id": string (uuid) "hook": string (uuid) "hookName": string "hookTypeLabel": string "hookAction": string "conversation": string (uuid) "message": string (uuid) "messageContent": string // Return the raw message text. "chatbotId": string "chatbotName": string "metadata": object "triggerPoint": string "createdAt": string (timestamp) "updatedAt": string (timestamp) } ] "outputHookLogs": [ { "id": string (uuid) "hook": string (uuid) "hookName": string "hookTypeLabel": string "hookAction": string "conversation": string (uuid) "message": string (uuid) "messageContent": string // Return the raw message text. "chatbotId": string "chatbotName": string "metadata": object "triggerPoint": string "createdAt": string (timestamp) "updatedAt": string (timestamp) } ] "instructionId": string "llm": { "id": string (uuid) "name": string } "effectiveMaxLlmOutputTokens": integer // max_tokens 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": [ // Return credit costs aggregated by item_code for credit-mode organizations. object ] "cacheSavedCredits": number (double) // Net credits saved by prompt caching for this reply; ``None`` outside credit mode. Reuses the usage-statistics saving semantics (``compute_cache_saved_credits``) on the reply's own billing batch, so the per-reply figure and the hourly aggregate are defined by the same formula. The net value may be negative (cache-creation premium exceeding read savings); the frontend hides non-positive values by design. "trace": object // Return the round trace timeline for the detail view; ``None`` for legacy records. "llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory "source": string // Origin discriminator for the unified /records/ response. "schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here. } ] } ``` **レスポンスのサンプル値** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "senderName": "レスポンス文字列", "callerMemberId": "レスポンス文字列", "callerMemberName": "レスポンス文字列", "feedback": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": {}, "suggestion": "レスポンス文字列", "updatedAt": "レスポンス文字列" }, "inputMessage": "レスポンス文字列", "condenseMessage": "レスポンス文字列", "outputMessage": "レスポンス文字列", "faithfulnessScore": 456, "displayFaithfulnessScore": 456, "answerRelevancyScore": 456, "displayAnswerRelevancyScore": 456, "contextPrecisionScore": 456, "displayContextPrecisionScore": 456, "answerCorrectnessScore": 456, "displayAnswerCorrectnessScore": 456, "answerSimilarityScore": 456, "displayAnswerSimilarityScore": 456, "contextRecallScore": 456, "displayContextRecallScore": 456, "replyTime": "レスポンス文字列", "createdAt": "レスポンス文字列", "error": "レスポンス文字列", "errorType": "system", "processingTime": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "usage": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "citationNodes": [ { "id": "レスポンス文字列", "text": "レスポンス文字列", "chatbotFileId": "レスポンス文字列", "fileName": "レスポンス文字列", "url": "レスポンス文字列" } ], "inputHookLogs": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "hook": "550e8400-e29b-41d4-a716-446655440000", "hookName": "レスポンス文字列", "hookTypeLabel": "レスポンス文字列", "hookAction": "レスポンス文字列", "conversation": "550e8400-e29b-41d4-a716-446655440000", "message": "550e8400-e29b-41d4-a716-446655440000", "messageContent": "レスポンス文字列", "chatbotId": "レスポンス文字列", "chatbotName": "レスポンス文字列", "metadata": null, "triggerPoint": "レスポンス文字列", "createdAt": "レスポンス文字列", "updatedAt": "レスポンス文字列" } ], "outputHookLogs": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "hook": "550e8400-e29b-41d4-a716-446655440000", "hookName": "レスポンス文字列", "hookTypeLabel": "レスポンス文字列", "hookAction": "レスポンス文字列", "conversation": "550e8400-e29b-41d4-a716-446655440000", "message": "550e8400-e29b-41d4-a716-446655440000", "messageContent": "レスポンス文字列", "chatbotId": "レスポンス文字列", "chatbotName": "レスポンス文字列", "metadata": null, "triggerPoint": "レスポンス文字列", "createdAt": "レスポンス文字列", "updatedAt": "レスポンス文字列" } ], "instructionId": "レスポンス文字列", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "effectiveMaxLlmOutputTokens": 456, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "context": "レスポンス文字列", "conversationId": "550e8400-e29b-41d4-a716-446655440000", "inboxId": "550e8400-e29b-41d4-a716-446655440000", "botMessageId": "550e8400-e29b-41d4-a716-446655440000", "userMessageId": "550e8400-e29b-41d4-a716-446655440000", "creditCosts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } ], "cacheSavedCredits": 456, "trace": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llmRawRequest": null, "source": "レスポンス文字列", "schedule": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } } ] } ``` *** ### 特定の会話記録を取得 GET `/api/v1/records/{id}/` #### パラメータ | パラメータ名 | 必須 | 型 | 説明 | | ------ | -- | ------ | ---------------------------------------------- | | `id` | ✅ | string | 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` - 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": object // 文字数、トークン数、および各 LLM 呼び出しのトークン内訳を含む使用量統計を返します "citationNodes": [ { "id": string "text": string "chatbotFileId": string "fileName": string "url": string } ] "inputHookLogs": [ { "id": string (uuid) "hook": string (uuid) "hookName": string "hookTypeLabel": string "hookAction": string "conversation": string (uuid) "message": string (uuid) "messageContent": string // Return the raw message text. "chatbotId": string "chatbotName": string "metadata": object "triggerPoint": string "createdAt": string (timestamp) "updatedAt": string (timestamp) } ] "outputHookLogs": [ { "id": string (uuid) "hook": string (uuid) "hookName": string "hookTypeLabel": string "hookAction": string "conversation": string (uuid) "message": string (uuid) "messageContent": string // Return the raw message text. "chatbotId": string "chatbotName": string "metadata": object "triggerPoint": string "createdAt": string (timestamp) "updatedAt": string (timestamp) } ] "instructionId": string "llm": { "id": string (uuid) "name": string } "effectiveMaxLlmOutputTokens": integer // max_tokens 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": [ // Return credit costs aggregated by item_code for credit-mode organizations. object ] "cacheSavedCredits": number (double) // Net credits saved by prompt caching for this reply; ``None`` outside credit mode. Reuses the usage-statistics saving semantics (``compute_cache_saved_credits``) on the reply's own billing batch, so the per-reply figure and the hourly aggregate are defined by the same formula. The net value may be negative (cache-creation premium exceeding read savings); the frontend hides non-positive values by design. "trace": object // Return the round trace timeline for the detail view; ``None`` for legacy records. "llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory "source": string // Origin discriminator for the unified /records/ response. "schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here. } ``` **レスポンスのサンプル値** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "senderName": "レスポンス文字列", "callerMemberId": "レスポンス文字列", "callerMemberName": "レスポンス文字列", "feedback": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": {}, "suggestion": "レスポンス文字列", "updatedAt": "レスポンス文字列" }, "inputMessage": "レスポンス文字列", "condenseMessage": "レスポンス文字列", "outputMessage": "レスポンス文字列", "faithfulnessScore": 456, "displayFaithfulnessScore": 456, "answerRelevancyScore": 456, "displayAnswerRelevancyScore": 456, "contextPrecisionScore": 456, "displayContextPrecisionScore": 456, "answerCorrectnessScore": 456, "displayAnswerCorrectnessScore": 456, "answerSimilarityScore": 456, "displayAnswerSimilarityScore": 456, "contextRecallScore": 456, "displayContextRecallScore": 456, "replyTime": "レスポンス文字列", "createdAt": "レスポンス文字列", "error": "レスポンス文字列", "errorType": "system", "processingTime": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "usage": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "citationNodes": [ { "id": "レスポンス文字列", "text": "レスポンス文字列", "chatbotFileId": "レスポンス文字列", "fileName": "レスポンス文字列", "url": "レスポンス文字列" } ], "inputHookLogs": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "hook": "550e8400-e29b-41d4-a716-446655440000", "hookName": "レスポンス文字列", "hookTypeLabel": "レスポンス文字列", "hookAction": "レスポンス文字列", "conversation": "550e8400-e29b-41d4-a716-446655440000", "message": "550e8400-e29b-41d4-a716-446655440000", "messageContent": "レスポンス文字列", "chatbotId": "レスポンス文字列", "chatbotName": "レスポンス文字列", "metadata": null, "triggerPoint": "レスポンス文字列", "createdAt": "レスポンス文字列", "updatedAt": "レスポンス文字列" } ], "outputHookLogs": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "hook": "550e8400-e29b-41d4-a716-446655440000", "hookName": "レスポンス文字列", "hookTypeLabel": "レスポンス文字列", "hookAction": "レスポンス文字列", "conversation": "550e8400-e29b-41d4-a716-446655440000", "message": "550e8400-e29b-41d4-a716-446655440000", "messageContent": "レスポンス文字列", "chatbotId": "レスポンス文字列", "chatbotName": "レスポンス文字列", "metadata": null, "triggerPoint": "レスポンス文字列", "createdAt": "レスポンス文字列", "updatedAt": "レスポンス文字列" } ], "instructionId": "レスポンス文字列", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "effectiveMaxLlmOutputTokens": 456, "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "context": "レスポンス文字列", "conversationId": "550e8400-e29b-41d4-a716-446655440000", "inboxId": "550e8400-e29b-41d4-a716-446655440000", "botMessageId": "550e8400-e29b-41d4-a716-446655440000", "userMessageId": "550e8400-e29b-41d4-a716-446655440000", "creditCosts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } ], "cacheSavedCredits": 456, "trace": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" }, "llmRawRequest": null, "source": "レスポンス文字列", "schedule": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンスのサンプル名", "description": "レスポンスのサンプル説明" } } ``` **ステータスコード: 404 - 指定された会話記録が見つかりません** *** ### 会話記録のエクスポートリクエストを作成 POST `/api/v1/records/export-excel-requests/` #### パラメータ | パラメーター名 | 必須 | 型 | 説明 | | ----------- | -- | ------ | --------------------------------------------------- | | `endDate` | ❌ | string | 終了日（形式：YYYY-MM-DD、例：2025-01-31） | | `keyword` | ❌ | string | 特定のキーワードを含む会話レコードを絞り込みます（ユーザーメッセージとボットの返信の両方を検索します） | | `startDate` | ❌ | string | 開始日（形式：YYYY-MM-DD、例：2025-01-01） | #### リクエストボディ **リクエストパラメーター** | フィールド | 型 | 必須 | 説明 | | ------------------ | ------------------ | --- | -------------------------------------------------------------------------------------------------- | | chatbot | string | いいえ | エクスポートする Chatbot の UUID を指定します。カンマ区切りで複数の UUID を指定できます。空欄の場合、組織内でアクセス権限のあるすべての Chatbot をエクスポートします。 | | chatbotId | string (uuid) | いいえ | エクスポートする Chatbot の UUID を指定します（chatbot の別名で、単一の UUID のみ指定できます）。 | | largeLanguageModel | string | いいえ | エクスポートする大規模言語モデルの UUID を指定します。カンマ区切りで複数の UUID を指定できます。 | | startDatetime | string (timestamp) | いいえ | 正確な開始日時を指定します（ISO 8601、指定時点を含みます）。一覧のドリルダウンフィルターと同じ意味で使用します。 | | endDatetime | string (timestamp) | いいえ | 正確な終了日時を指定します（ISO 8601、指定時点を含みません）。一覧のドリルダウンフィルターと同じ意味で使用します。 | | hasError | boolean | いいえ | エラーの有無でレコードを絞り込みます（true はエラーのあるレコードのみ、false はエラーのないレコードのみを含みます）。 | | errorType | string | いいえ | エラーの種類で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。指定可能な値は会話レコード一覧と同じです。 | | hasFeedback | boolean | いいえ | ユーザーのフィードバックの有無で絞り込みます（true は高評価/低評価のあるレコードのみ、false はフィードバックのないレコードのみを含みます）。 | | feedbackType | string | いいえ | ユーザーのフィードバックの種類（like / dislike）で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。 | | callerMember | string | いいえ | 発話したメンバーの UUID で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。 | **リクエスト構造の例** ```typescript { "chatbot"?: string // エクスポートする Chatbot の UUID を指定します。カンマ区切りで複数の UUID を指定できます。空欄の場合、組織内でアクセス権限のあるすべての Chatbot をエクスポートします。 (任意) "chatbotId"?: string (uuid) // エクスポートする Chatbot の UUID を指定します（chatbot の別名で、単一の UUID のみ指定できます）。 (任意) "largeLanguageModel"?: string // エクスポートする大規模言語モデルの UUID を指定します。カンマ区切りで複数の UUID を指定できます。 (任意) "startDatetime"?: string (timestamp) // 正確な開始日時を指定します（ISO 8601、指定時点を含みます）。一覧のドリルダウンフィルターと同じ意味で使用します。 (任意) "endDatetime"?: string (timestamp) // 正確な終了日時を指定します（ISO 8601、指定時点を含みません）。一覧のドリルダウンフィルターと同じ意味で使用します。 (任意) "hasError"?: boolean // エラーの有無でレコードを絞り込みます（true はエラーのあるレコードのみ、false はエラーのないレコードのみを含みます）。 (任意) "errorType"?: string // エラーの種類で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。指定可能な値は会話レコード一覧と同じです。 (任意) "hasFeedback"?: boolean // ユーザーのフィードバックの有無で絞り込みます（true は高評価/低評価のあるレコードのみ、false はフィードバックのないレコードのみを含みます）。 (任意) "feedbackType"?: string // ユーザーのフィードバックの種類（like / dislike）で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。 (任意) "callerMember"?: string // 発話したメンバーの UUID で絞り込みます。カンマ区切りで複数の値を指定できます（OR 条件）。 (任意) } ``` **リクエストの値の例** ```json { "chatbot": "文字列の例", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "largeLanguageModel": "文字列の例", "startDatetime": "文字列の例", "endDatetime": "文字列の例", "hasError": true, "errorType": "文字列の例", "hasFeedback": true, "feedbackType": "文字列の例", "callerMember": "文字列の例" } ``` #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X POST "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chatbot": "文字列の例", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "keyword": "文字列の例", "largeLanguageModel": "文字列の例", "startDate": "文字列の例", "endDate": "文字列の例", "startDatetime": "文字列の例", "endDatetime": "文字列の例", "hasError": true, "errorType": "文字列の例", "hasFeedback": true, "feedbackType": "文字列の例", "callerMember": "文字列の例" }' # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // リクエストボディ (payload) const data = { "chatbot": "文字列の例", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "keyword": "文字列の例", "largeLanguageModel": "文字列の例", "startDate": "文字列の例", "endDate": "文字列の例", "startDatetime": "文字列の例", "endDatetime": "文字列の例", "hasError": true, "errorType": "文字列の例", "hasFeedback": true, "feedbackType": "文字列の例", "callerMember": "文字列の例" }; axios.post("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", data, config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # リクエストボディ (payload) data = { "chatbot": "文字列の例", "chatbotId": "550e8400-e29b-41d4-a716-446655440000", "keyword": "文字列の例", "largeLanguageModel": "文字列の例", "startDate": "文字列の例", "endDate": "文字列の例", "startDatetime": "文字列の例", "endDatetime": "文字列の例", "hasError": True, "errorType": "文字列の例", "hasFeedback": True, "feedbackType": "文字列の例", "callerMember": "文字列の例" } response = requests.post(url, json=data, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'chatbot' => '文字列の例', 'chatbotId' => '550e8400-e29b-41d4-a716-446655440000', 'keyword' => '文字列の例', 'largeLanguageModel' => '文字列の例', 'startDate' => '文字列の例', 'endDate' => '文字列の例', 'startDatetime' => '文字列の例', 'endDatetime' => '文字列の例', 'hasError' => true, 'errorType' => '文字列の例', 'hasFeedback' => true, 'feedbackType' => '文字列の例', 'callerMember' => '文字列の例' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ | ステータスコード | 説明 | | -------- | ----------------- | | 200 | Excel ファイルのダウンロード | *** ### 会話レコードのエクスポート状況を取得 GET `/api/v1/records/export-excel-requests/{exportId}/` #### パラメーター | パラメーター名 | 必須 | 型 | 説明 | | ---------- | -- | ------ | -- | | `exportId` | ✅ | string | | #### コード例 {% tabs %} {% tab title="Shell/Bash" %} ```bash # API 呼び出しの例 (Shell) curl -X GET "https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/" \ -H "Authorization: Api-Key YOUR_API_KEY" # 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。 ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // リクエストヘッダーを設定します const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/", config) .then(response => { console.log('レスポンスを正常に取得しました:'); console.log(response.data); }) .catch(error => { console.error('リクエストでエラーが発生しました:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("レスポンスを正常に取得しました:") print(response.json()) except Exception as e: print("リクエストでエラーが発生しました:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "レスポンスを正常に取得しました:\n"; print_r($data); } catch (Exception $e) { echo 'リクエストでエラーが発生しました: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### レスポンスボディ **ステータスコード: 200** **レスポンス構造の例** ```typescript { "id": string (uuid) "senderName": string // ユーザーメッセージの送信者名を返します "callerMemberId": string "callerMemberName": string "inputMessage": string "outputMessage": string "chatbot": { "id": string (uuid) "name": string } "condenseMessage": string // 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 のウォーターフォールは含みません "usage": object // 文字数、トークン数、各 LLM 呼び出しのトークン内訳を含む使用量統計を返します "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": [ object ] "source": string // Origin discriminator for the unified /records/ response. "schedule": object // Shape parity with scheduled rows, which link their owning ChatbotSchedule here. } ``` **レスポンスの値の例** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "senderName": "レスポンス文字列", "callerMemberId": "レスポンス文字列", "callerMemberName": "レスポンス文字列", "inputMessage": "レスポンス文字列", "outputMessage": "レスポンス文字列", "chatbot": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "condenseMessage": "レスポンス文字列", "feedback": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": {}, "suggestion": "レスポンス文字列", "updatedAt": "レスポンス文字列" }, "displayFaithfulnessScore": 456, "displayAnswerRelevancyScore": 456, "displayContextPrecisionScore": 456, "displayAnswerCorrectnessScore": 456, "displayAnswerSimilarityScore": 456, "displayContextRecallScore": 456, "replyTime": "レスポンス文字列", "processingTime": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "usage": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" }, "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス文字列" }, "createdAt": "レスポンス文字列", "conversationId": "550e8400-e29b-41d4-a716-446655440000", "errorType": "system", "creditCosts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } ], "source": "レスポンス文字列", "schedule": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "レスポンス名の例", "description": "レスポンスの説明の例" } } ``` *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation 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.