有人対応サービス（Manual Service）

開発者がWebhook を手動サービスの接続方式として選択した場合、まず自分のサーバー環境に Webhook サービスを構築する必要があります。
開発者は、有人対応リクエスト、ユーザーメッセージ、およびオペレーターからの返信メッセージを受信するために、仕様に従って以下の3つのインターフェースを提供する必要があります
また、GPTBots 側も、カスタマーサービスの返信メッセージと会話の終了指示を受け取るための2つのインターフェースを提供しています。

注意事項：

1. 開発者は Webhook サービスが正常に利用可能な状態を確保する必要があります。そうでない場合、有人対応サービスの正常な利用に影響を及ぼす可能性があります。

• 有人対応サービスを開始した後に「ビジー状態」と表示される場合、開発者の Webhook サービスが異常であることを示します。
• 有人対応サービスを開始した後に「接続中」と表示される場合、開発者の Webhook サービスが正常であることを示します。

2. 有人対応サービスのリクエストが正常に開始された後：

• 開発者はユーザーメッセージへの返信インターフェース(https://api.gptbots.ai/v1/human/message/receive)を適時に呼び出してユーザーに1件のメッセージを返信する必要があります。これにより、対話接続が正常に確立されます。
• 開発者がユーザーメッセージに返信しない場合、設定された待機タイムアウト時間（デフォルト60秒）を超過すると、有人対応の会話は自動的に終了します。

有人対応サービスリクエストの通知

エンドユーザーが有人対応サービスをリクエストすると、GPTBotsはそのリクエストを開発者のWebhookサービスに転送します。開発者のインターフェースサービスが200を返すと、有人対応サービスの作成が成功したことを意味します。

リクエストメソッド

POST

エンドポイント

https://your_domain/conversation/establish

リクエスト例

                      
                      curl -X POST 'https://YOUR_DOMAIN/human/service/conversation/establish' \
-H 'Content-Type: application/json' \
-d '{
  "body": [
    {
      "text": "human service",
      "message_type": "QUESTION"
    },
    {
      "text": "",
      "message_type": "ANSWER"
    }
  ],
  "timestamp": 1742265090895,
  "email": "bob@gmail.com",
  "conversation_id": "67d8db020fa31d1ef64f53dg",
  "bot_id": "665d88b03ce2b13cf2d573454",
  "user_info": {
    "phone": null,
    "email": "bob@gmail.com",
    "user_id": "KDslas",
    "anonymous_id": "652face5184b30540a6ea7fe"
  }
}'

                    

注意：このリクエストボディの conversation_id は、有人対応サービスの会話シナリオを識別するための一意のIDとして使用され、会話IDの作成 でエージェント会話シナリオ用に生成される一意のIDとは異なります。

リクエストパラメータ

email フィールドに関する注意事項:

• iframe／共有リンク／バブルウィジェット 経由で有人対応を開始する場合、ユーザーはメールアドレスの入力が必要です。ただし、開発者がユーザーのメールアドレスをカスタマイズ設定することで、入力を省略させることも可能です。
• WhatsApp／Telegram／LiveChat などの外部プラットフォーム経由で有人対応をリクエストする場合、デフォルトで使用されるメールアドレスは support@gptbots.ai です。なお、LiveChatでは開発者がユーザーのメールアドレスをカスタマイズ可能です。
• API 経由で有人対応をリクエストする場合、email フィールドは空でも構いません。空の場合、デフォルトで support@gptbots.ai が使用されます。

レスポンス

チャットインターフェース

作成したconversation_idを使用して、ユーザーのメッセージを有人対応サービスに送信します。

リクエストメソッド

POST

エンドポイント

https://your_domain/chat

リクエスト例

                      
                      {
  "conversation_id": "conv_xxx",
  "message_id": "msg_abc124",
  "create_time": 1750000005000,
  "agent_id": "bot_xxx",
  "body": "これは私の注文のスクリーンショットです",
  "timestamp": 1750000005200,
  "files": [
    {
      "content_type": "Image",
      "url": "https://files.gptbots.ai/xxx/order.png",
      "name": "order.png",
      "format": "png"
    }
  ]
}

                    

リクエストのパラメータ

レスポンス

会話終了インターフェース

ユーザーとの会話がタイムアウトした場合や、エージェントユーザーが自発的に会話を終了した場合に、このインターフェースが呼び出されて会話を終了します。

リクエストメソッド

POST

エンドポイント

https://your_domain/conversation/close

リクエストヘッダー

リクエストのパラメータ

レスポンス

ユーザーメッセージへの返信

開発者がwebhookを有人対応サービスの連携方式として選択した場合、GPTBotsはユーザーメッセージへの返信用インターフェースを提供します。このインターフェースを通じて、有人オペレーターからのメッセージをユーザーに送信することができます。

リクエストメソッド

POST

エンドポイント

https://api-${endpoint}.gptbots.ai/v1/human/message/receive

リクエストヘッダー

リクエスト例

                      
                      {
  "conversation_id": "conv_xxx",
  "timestamp": 1750000000000,
  "body": "こちらがご依頼の請求書です",
  "files": [
    { "content_type": "Document", "url": "https://your-cdn.com/files/invoice.pdf", "name": "invoice.pdf", "format": "pdf" },
    { "content_type": "Image", "url": "https://your-cdn.com/files/screenshot.png", "name": "screenshot.png", "format": "png" }
  ]
}

                    

リクエストのパラメータ

レスポンス

有人対応サービスによる会話の終了

開発者が webhook を有人対応サービスの連携方法として選択した場合、 GPTBots が提供する有人対応サービスは必要に応じて能動的に会話を終了することができます。
会話が終了すると、ユーザーが再度有人カスタマーサービスの会話を開始しない限り、有人対応サービスからメッセージを受け取ることはありません。

リクエストメソッド

POST

エンドポイント

https://api-${endpoint}.gptbots.ai/v1/human/close

リクエストヘッダー

リクエストパラメータ

レスポンス

GPTBots サービス状態の検出

GPTBots は、自身の有人対応サービスを監視するためのヘルスモニタリングインターフェースを提供しています。開発者はこのインターフェースを呼び出して、GPTBots の有人対応サービスが正常に利用可能かどうかを確認できます。HTTP ステータスコード 200 が返され、かつレスポンスボディがサービス正常を示す英語の識別子（例：service is normal）であれば、GPTBots の有人対応サービスが正常に利用可能であることを意味します。このインターフェースは認証不要で、プレーンテキストを返します。

リクエストメソッド

GET

エンドポイント

https://api.gptbots.ai/v1/human/health

リクエスト例

                      
                      curl -X GET 'https://api.gptbots.ai/v1/human/health'

                    

レスポンス

GPTBots サービスが正常に利用可能な場合、HTTP ステータスコード 200 が返され、レスポンスボディにサービス正常を示す英語の識別子が返されます。

                      
                      service is normal

                    

可用性の判定に関する推奨事項

呼び出し側は、HTTP ステータスコードのみを判定基準とすれば十分です：

適切なリクエストタイムアウト（例：3～5秒）を設定し、一定の頻度でポーリング検出する（QPM:3）ことを推奨します。このインターフェースは認証不要で、呼び出し時に API Key を付与する必要はありません。