メッセージ送信
この 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"
}
}
}'
注意:
image、audio、documentタイプのメッセージでは、base64エンコーディングまたはURLリンクのいずれかの方法を選択して使用できます。- 自社構築のカスタマーサポートシステム(Custom Helpdesk)モードでは、人による対応中に受信したエージェントメッセージおよびユーザーメッセージは、
ai_response=falseまたはrole=human_agentとして送信され、アーカイブ(保存)されるのみで AI をトリガーしません。例:{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "ai_response": false, "human_agent_info": { "name": "Alice", "email": "alice@example.com", "image_url": "https://gptbots.ai/avatar.png" }, "messages": [ { "role": "human_agent", "content": "こんにちは、オペレーターが対応いたします。どのようなご用件でしょうか?" } ] }{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "blocking", "ai_response": false, "human_agent_info": { "name": "Alice", "email": "alice@example.com", "image_url": "https://gptbots.ai/avatar.png" }, "messages": [ { "role": "human_agent", "content": "こんにちは、オペレーターが対応いたします。どのようなご用件でしょうか?" } ] }このコードブロックをポップアップで表示 - 開発者は最新のユーザーメッセージのみを送信すれば十分です。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": "こんにちは" //最新のユーザーメッセージ }]このコードブロックをポップアップで表示 - 開発者が LoopAgent のストリーミングモードを使用する際、エージェントの実行中の処理過程メッセージが必要な場合は、リクエストパラメータの
is_process_resultフィールドで宣言できます。{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "streaming", "is_process_result": true, "messages": [ { "role": "human_agent", "content": "こんにちは、オペレーターが対応いたします。どのようなご用件でしょうか?" } ] }{ "conversation_id": "686e2646cb8ee942d9a62d79", "response_mode": "streaming", "is_process_result": true, "messages": [ { "role": "human_agent", "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、human_agent の3つのロールを使用して会話コンテキストを構築します。ai_response の影響を受けません。 |
| is_process_result | boolean | 任意 | LoopAgent が処理過程の情報を出力するかどうか。空欄可、デフォルトは false です。false:最終回答のみをストリーミングで返し、処理過程メッセージはありません。true:ラウンド間のナレーションメッセージと推論過程を1文字ずつ返し、最終回答も1文字ずつの増分で返します。 |
| ai_response | boolean | 任意 | AI が本メッセージにレスポンスするかどうか。デフォルトは true で、本フィールドを指定しない場合は既存の呼び出しと完全に同じ動作になります。false:本メッセージはアーカイブされるのみで AI はレスポンスしません。トークンやクレジットも消費せず、レスポンスは軽量な受領確認となります。true:AI は通常どおりレスポンスします。自社構築のカスタマーサポートシステム(Custom Helpdesk)モードでは、明示的に true を指定すると会話を人による対応の状態から AI に引き戻します。false と同等、そうでない場合は true と同等です。 |
| human_agent_info | object | 任意 | オペレーターの識別情報。messages に role=human_agent が含まれる場合にのみ意味を持ちます(トップレベルフィールドで、1回のリクエストにつき1名のオペレーターに対応します)。 |
| name | string | 任意 | オペレーターの名前。 |
| string | 任意 | オペレーターのメールアドレス。 | |
| image_url | string | 任意 | オペレーターのアバター画像URL。 |
| 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
}
},
"human_trigger": true
}
有人対応への転送がトリガーされた場合のレスポンス例
自社構築のカスタマーサポートシステム(Custom Helpdesk)モードでは、本ラウンドのレスポンスが有人対応への転送をトリガーした場合、human_trigger は true になります。引き継ぎ備考(handoff note)が併せて存在する場合は、追加で handoff オブジェクトが返されます(備考がない場合、このフィールドは出現しません)。
{
"create_time": 1679587005,
"conversation_id": "657303a8a764d47094874bbe",
"user_id": "65a4ccfc7ce58e728d5897e0",
"anonymous_id": "device_abcdef123456",
"message_id": "65a4ccfC7ce58e728d5897e0",
"output": [
{
"from_component_branch": null,
"from_component_name": "AI Model-1",
"content": {
"text": "オペレーターにおつなぎしています。少々お待ちください。",
"audio": null
}
}
],
"usage": {
"tokens": {
"total_tokens": 29,
"prompt_tokens": 19,
"prompt_tokens_details": {
"audio_tokens": 0,
"text_tokens": 19
},
"completion_tokens": 10,
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"text_tokens": 10
}
},
"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
}
},
"human_trigger": true,
"handoff": {
"note": "転送理由:ユーザーが返金プロセスへの不満を2回続けて表明し、有人対応を要求しました。\n会話サマリー:ユーザーは3月2日に注文し、返金を申請したものの返金通知を受け取っておらず、注文番号 20260302-8891 を確認済みです。"
}
}
成功時のレスポンス (Blocking)
⚠️ blocking レスポンスモードでは、LiveChat や Intercom などのサードパーティの有人対応システムを利用する場合、人による対応サービスは利用できません(オペレーターのメッセージは非同期で配信されるため、webhook モードで受信する必要があります)。
**自社構築のカスタマーサポートシステム(Custom Helpdesk)**を使用する場合はこの制限を受けません。有人対応への転送シグナルはレスポンスボディのhuman_trigger/handoffで返され、オペレーターのメッセージは開発者が本 API を通じてrole=human_agentとして書き込みます。
| フィールド | タイプ | 説明 |
|---|---|---|
| user_id | String | 開発者が紐付けたユーザーID。ユーザーが紐付けられていない場合は null です。 |
| anonymous_id | String | 匿名ユーザー(デバイス)ID。 |
| conversation_id | String | 会話を継続するための識別子です。 |
| message_id | String | 会話内の特定のメッセージを識別するための一意のIDです。 |
| create_time | Long | メッセージが生成された時刻のタイムスタンプです。 |
| output | JSON Array | エージェントのレスポンス内容です。 |
| usage | Object | 利用状況(消費リソースなど)の詳細です。 |
| human_trigger | boolean | 本レスポンスが有人対応への転送をトリガーしたかどうか。トリガーされていない場合は false。 |
| handoff | object | 有人対応への引き継ぎ情報。human_trigger が true で、かつ引き継ぎ備考が存在する場合にのみ出現します。 |
| note | string | 引き継ぎ備考(転送理由 + 会話サマリー)。最長 2000 文字。 |
| ai_response | boolean | アーカイブのみのリクエスト(ai_response=false または role=human_agent を含む)の受領確認で返され、当該メッセージが「アーカイブのみ」として認識されたことを確認するために使用します。 |
| sender_role | string | アーカイブのみのリクエストの受領確認で返され、値は human_agent または user。アーカイブされたメッセージのロールを確認するために使用します。 |
成功時のレスポンス (Streaming)
⚠️ streaming レスポンスモードでは、LiveChat や Intercom などのサードパーティの有人対応システムを利用する場合、人による対応サービスは利用できません(オペレーターのメッセージは非同期で配信されるため、webhook モードで受信する必要があります)。
**自社構築のカスタマーサポートシステム(Custom Helpdesk)**を使用する場合はこの制限を受けません。有人対応への転送はcode:36 HumanTriggerフレームで配信され、引き継ぎ備考はその直後にcode:107 HumanHandoffNoteフレームで配信されます。
| フィールド | タイプ | 説明 |
|---|---|---|
| code | int | メッセージ種別コード:3 - テキスト、10 - FlowAgent出力、0 - 終了、4 - 使用状況データ、39 - 音声メッセージ、5 - ツール呼び出しリクエスト、6 - ツール呼び出しレスポンス-6、41 - 思考、36 - 有人対応への転送トリガー、107 - 有人対応の引き継ぎ備考。 |
| message | string | メッセージ種別:Text(テキスト)、FlowOutput(フロー出力)、End(終了)、HumanTrigger、HumanHandoffNote。 |
| 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":"67b857b6be1f2906861a5e75"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"","transcript":"こんにちは"}}
{"code":39,"message":"Audio","data":{"audioAnswer":"EQAUAA0...IA3bi","transcript":""}}
{"code":0,"message":"End","data":null}
- 自社構築のカスタマーサポートシステム(Custom Helpdesk)モードで有人対応への転送がトリガーされると、
Endフレームの前に、有人対応の転送トリガーフレームと引き継ぎ備考フレームが順に配信されます:
{"code":3,"message":"Text","data":"オペレーターにおつなぎしています。少々お待ちください。"}
{"code":36,"message":"HumanTrigger","data":"HumanTrigger"}
{"code":107,"message":"HumanHandoffNote","data":{"note":"転送理由:ユーザーが返金プロセスへの不満を2回続けて表明し、有人対応を要求しました。\n会話サマリー:ユーザーは3月2日に注文し、返金を申請したものの返金通知を受け取っておらず、注文番号 20260302-8891 を確認済みです。"}}
{"code":0,"message":"End","data":null}
説明:
code: 36, message: "HumanTrigger"は本ラウンドのレスポンスが有人対応への転送をトリガーしたことを示し、dataは固定の識別子文字列です。code: 107, message: "HumanHandoffNote"は引き継ぎ備考を示し、そのdata構造はブロッキングレスポンスのhandoffフィールドと同じです({"note": "..."})。HumanHandoffNoteフレームは引き継ぎ備考が存在する場合にのみ配信されます。備考がない場合はHumanTriggerフレームのみで、空の107フレームは出現しません。- 両フレームは常に
End(code: 0)フレームの前に配信されます。
成功時のレスポンス (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
}
}
}
}
エラーコード
| コード | メッセージ |
|---|---|
| 40000 | パラメータが無効です |
| 40127 | 開発者認証に失敗しました |
| 40356 | 対話(Conversation)が存在しません |
| 40358 | Conversation ID(会話ID) が一致しません |
| 40364 | エージェントは画像形式に対応していません |
| 50000 | システム内部エラー |
| 20040 | 質問の文字数制限を超えました |
| 20022 | 利用可能なクレジットが不足しています |
| 20055 | API の利用が禁止されています(APIスイッチが有効になっているか確認してください) |
