トップ > API

1. 概要

IFRO は公式のクライアント以外にもロボットやアプリなど任意のクライアント上で作成したシナリオを利用できるよう API を提供しています。
シナリオを再生するユーザーの作成、ユーザーごとのシナリオの進行、ユーザーとのやり取りに利用する音声認識などの機能を提供します。

2. 共通仕様

2.1. プランごとの制限

IFRO APIの APIリクエストに関する制限は以下のとおりです。
これらの制限はアカウントごとに適用されます。
制限はご利用のプランによって異なります。プランについて詳しくは、 IFROウェブサイト を参照してください。

月間アクティブユーザー数

プラン

上限

Freeプラン

50件

Basicプラン

500件

Standardプラン

無制限

Premiumプラン

無制限

2.2. ステータスコード

ステータスコード

説明

200 OK

リクエスト成功時に返されます。

401 Unauthorized

有効なプロジェクト認証キーまたはトークンが指定されていない場合に返されます。

403 Forbidden

リソースにアクセスする権限がない場合に返されます。ご契約中のプランや利用状況を確認してください。

500 Internal Server Error

内部サーバーのエラーが発生した場合に返されます

2.3. 認証

認証はプロジェクト単位で行います。
すべてのAPIは以下の認証情報をリクエストヘッダーに含めてリクエストする必要があります。
認証情報の取得方法については [TODO: ドキュメント内の該当箇所にリンク] を参照ください。

ヘッダー

説明

X-Project-Key

認証キー

X-Project-Secret

認証シークレット

3. ユーザーを作成する

シナリオを再生するユーザーを作成するAPIです。
実行すると新規にユーザーが作成されユニークな uid が発行されます。
発行された uid を利用してユーザーごとにシナリオを再生することができます。

3.1. HTTPリクエスト

POST https://api.ifro.ai/v1/clients/projects/users

3.2. リクエストパラメーター

ユーザー作成APIに指定できるパラメーターはありません。

3.3. レスポンス

作成されたユーザー情報がレスポンスされます。

{
  data: {
    id: "1",
    type: "user",
    attributes: {
      uid: "S5PArks-X1T7hDOY5FdPDg",
    }
  }
}

パラメーター名

説明

uid

ユーザーのユニークなIDです。シナリオ進行APIを利用する際にユーザーを特定するために利用します。

4. シナリオを進行する

IFRO で作成したシナリオを進行するAPIです。
ユーザー作成APIで発行したユーザーの uid を指定して実行する必要があり、
指定したユーザーに紐付いたシナリオが進行していきます。
シナリオはモジュール単位で進行していきます。APIからのレスポンスに含まれたパラメーターに従って処理を行ってください。

4.1. HTTPリクエスト

POST https://api.ifro.ai/v1/clients/projects/forwards

4.2. リクエストパラメーター

以下のパラメーターを指定することができます。

パラメーター名

説明

uid

シナリオを再生するユーザーのIDです。新規に発行するにはシナリオ進行APIを利用します。

client_message

ユーザーから聞き取った内容を指定するパラメーターです。聞き取りを行った場合のみパラメーターを指定してください。

4.3. レスポンス

シナリオ進行に関する情報がレスポンスされます。

{
  data: {
    id: "KkY8SkHQ5r53lxQtcWd1NQ",
    type: "scenario_player_message",
    attributes: {
      "module_message": null,
      "client_message": null,
      "client_rendering_content": "こんにちは",
      "client_rendering_content_url": "https://〜",
      "client_action_type": "1",
      "custom_parameter": null,
      "options": null,
      "current_module_label": "Greeting",
      "current_module_id": "jyypXAmc81AYDIWPuX1iWA",
      "current_module_type": "SpeechScenarioModule",
      "next_module_label": "Quit",
      "next_module_id": "rUpgupjJjEJqIOnrBS9RxA",
      "next_module_type": "QuitScenarioModule",
      "creted_at": "1557281922",
      "user_id": "S5PArks-X1T7hDOY5FdPDg",
      "project_id": "40",
      "project_label": "Greeting Project",
      "project_thumbnail_url": "https://〜",
    },
  }
}

パラメーター名

説明

module_message

聞き取り結果など、シナリオを進行する上でモジュール間でやり取りするための内容です。

client_message

ユーザーから聞き取った内容として受け取ったデータです。

client_action_type

モジュールごとに想定されたクライアント側で行うべき動作についての情報です。
このパラメーターに従ってクライアント側で処理を行ってください。
詳細については client_action_type について を参照ください。

client_rendering_content

ボットの発話内容などクライアントに出力する想定の内容です。

client_rendering_content_url

ボットの発話内容などを音声化した mp3 ファイルのURLです
スキル公開時に音声付きで公開を有効にした場合値が入ります。

custom_parameter

パラメーターモジュールに設定したパラメーター内容です。

options

選択肢聞き取りモジュールに設定した選択肢の内容です。

current_module_label

現在再生しているモジュールに設定されたラベル情報です。

current_module_id

現在再生しているモジュールに設定されたID情報です。

current_module_type

現在再生しているモジュールのモジュール種別です。

next_module_label

次に再生するモジュールに設定されたラベル情報です。

next_module_id

次に再生するモジュールに設定されたID情報です。

next_module_type

次に再生するモジュールのモジュール種別です。

created_at

モジュールが再生されたUnixtime形式の日時情報です。

user_id

シナリオを再生しているユーザーのIDです。

project_id

シナリオを作成したスキルのIDです。

project_label

シナリオを作成したスキルのラベル情報です。

project_thumbnail_url

シナリオを作成したスキルのサムネイル画像ファイルのURLです。

4.4. client_action_type について

レスポンスに含まれる client_action_type パラメータの詳細です。

説明

0

クライアント側で特に処理する必要の無い場合に渡されます
そのままAPIを再度実行してシナリオを進めてください。

1

クライアント側で発話を行ってほしい場合に渡されます
client_rendering_content または client_rendering_content_url の内容を任意の方法で処理してください。

2

クライアント側で聞き取りを行ってほしい場合に渡されます
ユーザーからの発話内容を取得して、次にシナリオ進行APIを実行する際に client_message パラメーターに指定してください。

999

シナリオが終了した場合に渡されます。
必要に応じて終了時の処理を行ってください。

5. シナリオを先頭に戻して再生する

ユーザーが進行しているシナリオを先頭まで戻して再生する API です。
これまでに作成された記憶などは保持したままシナリオを先頭に戻します。

5.1. HTTPリクエスト

POST https://api.ifro.ai/v1/clients/projects/rewinds

6. 音声を認識する

音声をテキストに変換するAPIです。
音声が含まれた WAV ファイルを送信すると内容をテキストにして返します。

6.1. HTTPリクエスト

POST https://api.ifro.ai/v1/clients/projects/speech_recognitions

6.2. パラメーター

以下のパラメーターを指定することができます。

パラメーター名

説明

resource

音声が含まれたWAVファイル(16bit, 無圧縮PCM, monoral のみ)

6.3. レスポンス

変換されたテキストの内容がレスポンスされます。

{
  data: {
    id: "",
    type: "speech_recognition",
    attributes: {
      text: "こんにちは",
    },
  }
}

トップ > API