api.aiのEventの概要

Events

Eventはユーザクエリの代わりにイベント名によってintentを呼び出すことができる機能である。
まず、Intent内でEvent名を定義する。そして、eventパラメータを含む/queryリクエストを送信することによって、Intentを呼び出すことができる。

Event Name

Event名は50文字以内の文字列である。a-z、A-Z、0-9、アンダースコア、ハイフンが使用可能。イベント名は大文字小文字を区別しない。

幾つかの文字列は予約語になっている。

Defining Event Names in Intents

デベロッパーコンソールや/intentエンドポイントを伴ったAPI呼び出し経由内Intentが持つEvent名を定義する事ができる。
IntentのEvent項目から設定できる。
API経由でイベントを発生冴えるには、"event"フィールドを使うと良い。

"events": [
    {
        "name": "<event_name>"
    }
]

Invoking an Event via Query Request

Event名によって特定のIntentを発火されるには、"event"パラメータの値を含む/queryリクエストを送信する。
queryリクエストは"query"または"event"パラメータを含む必要がある。

GET /query Request

Eventを呼び出すためにGETメソッドを使用する場合、下記のフォーマットでEvent名を送信することができる。e=<event_name>

curl -H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN" "https://api.api.ai/v1/query?v=20150910&e=event_name&timezone=Europe/Paris&lang=en&sessionId=1234567890"

POST /query Request

Eventを呼び出すためにPOSTメソッドを使用する場合、"event"パラメータの値は下記のフォーマットとなる。

"event":{  
  "name":"<event_name>",
  "data":{
      “<parameter_name>”:”<parameter_value>”  
  }
}

Sending Parameters in a Query Request

"event"パラメータを付けてクエリリクエストを送るとき、api.aiはEvent名と同じ名前のContextを生成し、Contextのlifespanを0とする。このLifespanの値は、Contextが現在のリクエストを処理する間のみ有効であることを意味する。

"data"オブジェクトからActionセクションに手動で定義されたパラメータにあたいをわたすときや、発火したIntentのResponseセクション内またはIntentのパラメータ値の参照にこのContextを使うことができる。

Default Welcome Intent

新規でAgentを作成したとき、自動的にDefault Welcome Intentが追加される。このようなIntentは事前定義されたWelcomeイベントとテキストレスポンスを持っている。

このWELCOMEイベントはサポートされたone-clickインテグレーションのための一般的なイベントである。後続イベントを設定するための手っ取り早い方法である。GOOGLE_ASSISTANT_WELCOME, FACEBOOK_WELCOME, TELEGRAM_WELCOME, KIK_WELCOME.

エンドユーザが、サポートされたメッセージプラットフォームからIntentを発火させたとき、関連するイベントがAPI.AIに送られる。特定のメッセージングプラットフォームに対応して定義された明確なイベントがない場合、Default Welcome Intentが発火する。（よくわかんね）

例えば、ユーザがFacebook Messenger内のGet Startedボタンをクリックした場合、{"event": "FACEBOOK_WELCOME", "data": {}}がAgentに送信される。まず、API.AIはFACEBOOK_WELCOMEイベントを含んでいるIntentをチェックする。もしそのようなIntentがない場合、Default Welcome Intentが発火する。

Invoking Event from Webhook

自分自身のWebサービスから"followupEvent"を含んだevent名が送られるfulfillmentを経由してEventを呼び出すことができる。
この"followupEvent"パラメータは下記のフォーマットのオブジェクトである。

{
   "followupEvent": {
      "name": "<event_name>",
      "data": {
         "<parameter_name>":"<parameter_value>>"
      }
   }
}

後続するfollowupIntentを発火するためにwebサービスにリクエストを送ったIntentが発火したとき、JSONレスポンス内には"metadata"フィールドをが含まれ、"executionSequence"を含む。データ群の最初のシーケンスはシーケンスを発火させるためのIntentについての情報を含んでいる。例えば、API.AIからウェブサービスに送られたリクエストなど。最初のシーケンスに含まれる"webhookTriggeringEvent"の値は、follow-up intentをwebサービス側から発火させるEventの名前である。