メッセージ送信
メッセージ送信
この API を使用すると、指定した conversation_id にメッセージを送信し、エージェントが生成したレスポンスを受け取ることができます。
この API は、テキスト、画像、音声、ドキュメントなど、さまざまな種類のメッセージコンテンツに対応しています。
リクエストメソッド
POST
エンドポイント
https://api-${endpoint}.gptbots.ai/v2/conversation/message
認証
詳細については、API概要の認証方法の説明をご参照ください。
リクエスト
リクエストの例
curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"conversation_id": "686e2646cb8ee942d9a62d79",
"response_mode": "blocking",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "I have uploaded 2 image files, please OCR and return 2 json records."
},
{
"type": "image",
"image": [
{
"base64_content": "<complete_base64_string>",
"format": "jpeg",
"name": "TAXI1"
},
{
"url": "https://gptbots.ai/example.png",
"format": "png",
"name": "TAXI2"
}
]
},
{
"type": "audio",
"audio": [
{
"url": "https://gptbots.ai/example.mp3",
"format": "mp3",
"name": "example1 audio"
}
]
},
{
"type": "document",
"document": [
{
"base64_content": "<complete_base64_string>",
"format": "pdf",
"name": "example pdf"
}
]
}
]
}
],
"conversation_config": {
"long_term_memory": false,
"short_term_memory": false,
"knowledge": {
"data_ids": [
"58c70da0403cc812641b9356",
"59c70da0403cc812641df35a"
],
"group_ids": [
"67c70da0403cc812641b93je",
"69c70da0403cc812641df35f"
]
},
"custom_variables": {
"var_current_url": "https://gptbots.ai/example",
"var_session_id": "abcdef"
}
}
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v2/conversation/message' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"conversation_id": "686e2646cb8ee942d9a62d79",
"response_mode": "blocking",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "I have uploaded 2 image files, please OCR and return 2 json records."
},
{
"type": "image",
"image": [
{
"base64_content": "<complete_base64_string>",
"format": "jpeg",
"name": "TAXI1"
},
{
"url": "https://gptbots.ai/example.png",
"format": "png",
"name": "TAXI2"
}
]
},
{
"type": "audio",
"audio": [
{
"url": "https://gptbots.ai/example.mp3",
"format": "mp3",
"name": "example1 audio"
}
]
},
{
"type": "document",
"document": [
{
"base64_content": "<complete_base64_string>",
"format": "pdf",
"name": "example pdf"
}
]
}
]
}
],
"conversation_config": {
"long_term_memory": false,
"short_term_memory": false,
"knowledge": {
"data_ids": [
"58c70da0403cc812641b9356",
"59c70da0403cc812641df35a"
],
"group_ids": [
"67c70da0403cc812641b93je",
"69c70da0403cc812641df35f"
]
},
"custom_variables": {
"var_current_url": "https://gptbots.ai/example",
"var_session_id": "abcdef"
}
}
}'
このコードブロックをポップアップで表示
注意:
image、audio、documentタイプのメッセージでは、base64エンコーディングまたはURLリンクのいずれかの方法を選択して使用できます。- 開発者は最新のユーザーメッセージのみを送信すれば十分です。GPTBotsは自動的に短期記憶と長期記憶の管理を行います。短期記憶をカスタマイズする必要がある場合は、以下の短期記憶カスタマイズのサンプルをご参照ください。"messages": [ { "role": "user", "content": "こんにちは" //カスタム短期記憶 }, { "role": "assistant", "content": "Hello! How can I assist you today?" //カスタム短期記憶 }, { "role": "user", "content": "こんにちは" //最新のユーザーメッセージ }]
"messages": [ { "role": "user", "content": "こんにちは" //カスタム短期記憶 }, { "role": "assistant", "content": "Hello! How can I assist you today?" //カスタム短期記憶 }, { "role": "user", "content": "こんにちは" //最新のユーザーメッセージ }]このコードブロックをポップアップで表示
リクエストヘッダー
| フィールド | タイプ | 説明 |
|---|---|---|
| Authorization | Bearer ${API Key} | 認証には Authorization: Bearer ${API Key} を使用してください。トークンはAPIキーページから取得できます。 |
| Content-Type | application/json | データの形式は application/json を設定してください。 |
リクエストボディ
| フィールド名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| conversation_id | String | 必須 | 会話の一意の識別子。会話を継続するには conversation_id の指定が必須です。 |
| response_mode | String | 必須 | エージェントのレスポンスモード： |
| messages | JSON Array | 必須 | メッセージ内容。userおよびassistantのロールを使用して会話コンテキストを構築します。 |
| conversation_config | Object | 任意 | 開発者が本対話においてエージェントの機能範囲を一時的に調整するための設定。特殊なシナリオに対応する際に使用します。 |
| short_term_memory | Boolean | 任意 | 短期メモリの有効/無効を指定します。この設定は当該会話のみ有効です。 |
| long_term_memory | Boolean | 任意 | 長期メモリの有効/無効を指定します。この設定は当該会話のみ有効です。 |
| knowledge | Object | 任意 | ナレッジ検索の範囲をカスタマイズする設定。group_ids と data_ids を含み、両方に値がある場合はそれらの和集合で検索します。両方が空配列の場合はナレッジ検索を行いません。knowledge を指定しない場合はエージェントのデフォルト設定が使用されます。group_ids: ナレッジベースのID（複数のドキュメントを含む可能性があります）data_ids: ナレッジベース内のドキュメントID |
| custom_variables | Object | 任意 | カスタム変数。開発者がエージェント内のカスタム変数の値を一時的に変更でき、当該会話のみ有効です。 |
| thinking | boolean | No | ストリーミングで思考情報を返すかどうかを制御します。 |
| tool_call | boolean | No | ストリーミングでツール呼び出し情報を返すかどうかを制御します。 |
注意:
エージェントの入出力設定ページでは、メッセージの種類ごとに異なる認識方式をサポートしています。対応しているファイル形式やサイズは異なるため、APIで送信するデータもそれに応じて調整する必要があります。サポートされているメッセージ形式の上限は以下の通りです。
- テキストメッセージ: string
- オーディオメッセージ: .mp3, .wav, .acc
- 画像メッセージ: .jpg, .jpeg, .png, .gif, .webp
- ドキュメントメッセージ: .pdf, .txt, .docx, .csv, .xlsx, .html, .json, .md, .tex, .ts, .xml, etc.
レスポンス
レスポンス例
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "Hi, is there anything I can help you?",
"audio": [
{
"audio": "http://gptbots.ai/example.mp3",
"transcript": "Transcribed audio content"
}
]
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0.0,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
}
}
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "Hi, is there anything I can help you?",
"audio": [
{
"audio": "http://gptbots.ai/example.mp3",
"transcript": "Transcribed audio content"
}
]
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0.0,
"text_input_credits": 0.0,
"text_output_credits": 0.0,
"audio_input_credits": 0.0,
"audio_output_credits": 0.0
}
}
}
このコードブロックをポップアップで表示
成功時のレスポンス (Blocking)
| フィールド | タイプ | 説明 |
|---|---|---|
| user_id | String | 開発者が紐付けたユーザーID。ユーザーが紐付けられていない場合は null です。 |
| anonymous_id | String | 匿名ユーザー（デバイス）ID。 |
| conversation_id | String | 会話を継続するための識別子です。 |
| message_id | String | 会話内の特定のメッセージを識別するための一意のIDです。 |
| create_time | Long | メッセージが生成された時刻のタイムスタンプです。 |
| output | JSON Array | エージェントのレスポンス内容です。 |
| usage | Object | 利用状況（消費リソースなど）の詳細です。 |
成功時のレスポンス (Streaming)
| フィールド | タイプ | 説明 |
|---|---|---|
| code | int | メッセージ種別コード：3 - テキスト、10 - FlowAgent出力、0 - 終了、4 - 使用状況データ、39 - 音声メッセージ、5 - ツール呼び出しリクエスト、6 - ツール呼び出しレスポンス-6、41 - 思考。 |
| message | string | メッセージ種別：Text（テキスト）、FlowOutput（フロー出力）、End（終了）。 |
| data | object | レスポンスの内容。 |
- テキストメッセージのストリーミング例：
{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"How "}
{"code":3,"message":"Text","data":"can "}
{"code":3,"message":"Text","data":"I "}
{"code":3,"message":"Text","data":"help "}
{"code":3,"message":"Text","data":"you?"}
{"code":0,"message":"End","data":null}
{"code":11,"message":"MessageInfo","data":{"message_id":"6785dba0f06d872bff9ee347"}}
{"code":3,"message":"Text","data":"How "}
{"code":3,"message":"Text","data":"can "}
{"code":3,"message":"Text","data":"I "}
{"code":3,"message":"Text","data":"help "}
{"code":3,"message":"Text","data":"you?"}
{"code":0,"message":"End","data":null}
このコードブロックをポップアップで表示
- オーディオメッセージのストリーミング例:
{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"こんにちは"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
{"code":11,"message":"MessageInfo","data":{"message_id":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"こんにちは"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
このコードブロックをポップアップで表示
成功時のレスポンス (Webhook)
開発者が「連携-API」で webhook アドレスの設定を完了すると、GPTBots システムは「Agent の返信」と「人による対応の返信」のメッセージを webhook アドレスに送信します。
Webhook メッセージの詳細については、webhookでメッセージを受信をご参照ください。
⚠️ API モードでは、有人対応サービスを有効にしている場合、人による対応の返信メッセージを受信するには、必ず webhook 応答モードを使用する必要があります。
エラーレスポンス
| フィールド | タイプ | 説明 |
|---|---|---|
| code | Int | エラーコード |
| message | String | エラー詳細内容 |
失敗例
{
"code": 40000,
"message": "パラメータが無効です",
"errors": [
{
"error_code": 40000,
"error_message": "Message user role type must have file or content."
}
],
"data": {
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "認識可能な内容に基づいて回答しました……",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0,
"text_input_credits": 0,
"text_output_credits": 0,
"audio_input_credits": 0,
"audio_output_credits": 0
}
}
}
}
{
"code": 40000,
"message": "パラメータが無効です",
"errors": [
{
"error_code": 40000,
"error_message": "Message user role type must have file or content."
}
],
"data": {
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": "1",
"from_component_name": "Component Name",
"content": {
"text": "認識可能な内容に基づいて回答しました……",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 0
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 0
}
},
"credits": {
"total_credits": 0,
"text_input_credits": 0,
"text_output_credits": 0,
"audio_input_credits": 0,
"audio_output_credits": 0
}
}
}
}
このコードブロックをポップアップで表示
エラーコード
| コード | メッセージ |
|---|---|
| 40000 | パラメータが無効です |
| 40127 | 開発者認証に失敗しました |
| 40356 | 対話（Conversation）が存在しません |
| 40358 | Conversation ID（会話ID） が一致しません |
| 40364 | エージェントは画像形式に対応していません |
| 50000 | システム内部エラー |
| 20040 | 質問の文字数制限を超えました |
| 20022 | 利用可能なクレジットが不足しています |
| 20055 | API の利用が禁止されています（APIスイッチが有効になっているか確認してください） |