Wisora API を利用すると、外部システムから Wisora ボットに問い合わせて、ボットの回答を取得できます。

API キーを発行する

1. 管理者として 管理コンソールにログイン して、メニューの [管理(テナント)] → [テナント設定] を順にクリックします。

2. [APIキー] タブをクリックします。

3. [API キーを発行する] をクリックします。

   API キーが発行され、一覧に表示されます。

4. 発行された API キーをコピーして、外部システム側で安全に保管します。

   API 呼び出しでは、この値を X-API-KEY ヘッダーに指定します。

API リファレンスを確認する

1. 管理コンソールで、メニューの [管理(テナント)] → [APIドキュメント] を順にクリックします。

   API リファレンスが表示されます。

2. エンドポイント、リクエストボディ、レスポンスボディを確認します。

チャット API を呼び出す

次の手順で、会話 ID を生成してからボットへメッセージを送信します。botId を省略するとデフォルトボットを利用します。特定のボットを指定する場合は、リクエストボディに botId を指定します。デフォルトボットを明示する場合は、default を指定します。

手順のコマンド実行例の https://<管理コンソールのホスト名> には、管理コンソールの URL から /ui/... 以降を除いた URL を指定します。たとえば、管理コンソールのログイン URL が https://example.wisora.soracom.io/ui/wisora-login の場合は、https://example.wisora.soracom.io を指定します。

1. POST /api/chat/start を呼び出して、会話 ID を生成します。

   curl -sS -X POST "https://<管理コンソールのホスト名>/api/chat/start" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: <発行した API キー>" \
     --data '{
       "conversationIdSuffix": "sample-session"
     }'

   conversationIdSuffix は任意です。指定すると、識別しやすいサフィックス付きの会話 ID を生成できます。

   API で取得したレスポンスの例は以下のとおりです。

   {
     "conversationId": "<生成された会話 ID>",
     "suffix": "sample-session"
   }

2. レスポンスの conversationId を指定して、POST /api/chat/message を呼び出します。

   curl -sS -X POST "https://<管理コンソールのホスト名>/api/chat/message" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: <発行した API キー>" \
     --data '{
       "chatMessage": "営業時間を教えてください。",
       "replyFormat": "markdown",
       "conversationId": "<生成された会話 ID>"
     }'

   主なリクエスト項目は以下のとおりです。

   項目	説明
   chatMessage	ボットに送信するメッセージです。
   replyFormat	レスポンスの形式です。この例では markdown を指定しています。
   conversationId	POST /api/chat/start で生成された会話 ID です。同じ値を指定すると会話を継続できます。
   botId	任意です。対象ボットの ID を指定します。省略時はデフォルトボットが対象です。

   API で取得したレスポンスの例は以下のとおりです。レスポンスには、ボットの回答、会話 ID、参照したドキュメントなどが含まれます。

   {
     "chatReply": "お問い合わせありがとうございます。営業時間は平日 9:00 から 18:00 です。",
     "referenceDocs": [
       {
         "title": "お問い合わせ",
         "url": "https://example.co.jp/info.html",
         "content": "営業時間: 平日 9:00 ～ 18:00"
       }
     ],
     "complementaryDocs": [],
     "format": "markdown",
     "updatedConversationHistory": [],
     "conversationId": "<生成された会話 ID>",
     "timestamp": "2026-05-01T12:34:56.789Z"
   }

3. 同じ会話を継続する場合は、手順 2 のレスポンスに含まれる conversationId を次回の POST /api/chat/message に指定します。

   curl -sS -X POST "https://<管理コンソールのホスト名>/api/chat/message" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: <発行した API キー>" \
     --data '{
       "chatMessage": "土曜日も営業していますか。",
       "replyFormat": "markdown",
       "conversationId": "<生成された会話 ID>"
     }'

   API で取得したレスポンスの例は以下のとおりです。

   {
     "chatReply": "土曜日は営業していません。営業時間は平日 9:00 から 18:00 です。",
     "referenceDocs": [
       {
         "title": "お問い合わせ",
         "url": "https://example.co.jp/info.html",
         "content": "営業時間: 平日 9:00 ～ 18:00"
       }
     ],
     "complementaryDocs": [],
     "format": "markdown",
     "updatedConversationHistory": [],
     "conversationId": "<生成された会話 ID>",
     "timestamp": "2026-05-01T12:35:12.345Z"
   }

チャットログ API を呼び出す

GET /api/v1/chat/logs を呼び出すと、チャットログに記録されたメッセージを会話単位で取得できます。取得対象の期間は、メッセージの送信日時で指定します。

curl -sS "https://<管理コンソールのホスト名>/api/v1/chat/logs?from=1764547200000&to=1764633599999&limit=100" \
  -H "X-API-KEY: <発行した API キー>"

主なクエリパラメーターは以下のとおりです。

(*) from と to はメッセージ単位で適用されるため、同じ会話内でも指定範囲外のメッセージはレスポンスに含まれません。

API で取得したレスポンスの例は以下のとおりです。

{
  "items": [
    {
      "conversationId": "cv-1234567890-abc123",
      "category": "supportChat",
      "chatSessionUserId": "publicSession:sample-user",
      "conversations": [
        {
          "sender": "user",
          "message": "営業時間を教えてください。",
          "timestamp": "2026-05-01T12:34:56.789Z"
        },
        {
          "sender": "bot",
          "message": "営業時間は平日 9:00 から 18:00 です。",
          "timestamp": "2026-05-01T12:35:02.345Z"
        }
      ]
    }
  ],
  "nextContinuationToken": "<次のページを取得するためのトークン>"
}