機能について|Tropo Web API

   

WebAPIの機能をよりよく説明するために、少々複雑なJSONのサンプルを使用します。このサンプルは、index.json, the_answer.json そしてthe_wrong_answer.jsonという3つのJSONファイル使用します。 最初のリソース index.jsonは、Tropoに発信者の5ケタのアカウント番号を要求することを指示します。 発信者が有効な回答を入力すれば、the_answer.jsonが使用され、ユーザが無効な回答を入力した場合は、the_wrong_answer.jsonが使われます。 純粋なJSONアプリケーションは論理式の解釈できません。そのため、ユーザが特定の回答をしても、どこへ行くべきか決められないのです。 この論理式(if/then/else)が必要な場合はライブラリが必要になります。

 

ステップ1‐セッション

お客様がTropo上に設定したアプリに対してユーザーが電話を掛ける場合は、お客様のHTTPサーバの指定のリソース(後述)に対して、 TROPO WebAPIがHTTPリクエストボディにJSONドキュメントを付随してPOSTします。(上記の①をご覧ください) 指定のリソースはTropo開発ページの「ファイルの場所:」の入力欄で指定することができます。

 

JSONドキュメントには「session」オブジェクトと以下のようなものを有しています。

図 1.0

{"session":{
	 "id":"0-13c4-4b79de7f-dcedd0c-4f8f-1d104f50",
	 "accountId":"43670",
	 "timestamp":"2010-02-15T23:53:35.963Z",
	 "userType":"HUMAN",
	 "initialText":null,
	 "to":{
		"id":"9991429500",
		"name":"unknown",
		"channel":"VOICE",
		"network":"PSTN"
	 },
	 "from":{
		"id":"username",
		"name":"unknown",
		"channel":"VOICE",
		"network":"PSTN"
	 },
	 "headers":[
		{
		   "key":"x-sbc-from",
		   "value":"username<sip:0000123456@192.168.14.100>;tag=a037367f"
		},
		{
		   "key":"x-sbc-allow",
		   "value":"BYE"
		},
…追加のSIPヘッダ…            
}

このイニシャルメッセージは豊富な情報があります。通話ごとのユニークIDやセッションIDを所持しており、トラッキングに使用できます。 複数のアカウントを処理するマルチテナントアプリケーションを持っていれば、accountIdが便利でしょう。tofromのブロックは、かけてきた人や、 その電話番号などについての全てのネットワーク情報を開示します。そしてheadersというブロックは、 コールを適切に送信する補助となるカスタムヘッダを送ります。これにより、よりフレキシブルな対応が可能となります。 SIPヘッダを使う必要は全くありませんが、必要な場合に備えて提供しています。 実際には、サンプルで示した2つよりもずっと多くのヘッダがありますが、 見やすくするために減らしています。

ステップ 2 - Tropoへの応答

TROPOからセッション情報を取得したら、サーバーはHTTP 200と受けてアプリケーションは次のステップに移ります。 TROPOからのリクエストに対して、サーバーはTROPOに対象のJSONの内容をレスポンスボディに含めて送り返します。 以下のような形でJSONをレスポンスとしてTROPOに返送すると、自動的に音声の再生が始まり、通話発信者にキーパッド(DTMF)入力を要求します。

図 1.1

{"tropo":[
	 {
		"on":[
		   {
			  "event":"continue",
			  "next":"the_answer.json"
		   },
		   {
			  "event":"incomplete",
			  "next":"the_wrong_answer.json"
		   }
		]
	 },
	 {
		"ask":{
		   "bargein":true,
		   "required":true,
		   "timeout":30,
		   "say":[
			  {"value":"5桁のアカウント番号をどうぞ"}
		   ],
		   "choices":
			   {"value":"[5 DIGITS]"},
		   "name":"account_number"
		}}
  ]}
  

Tropoオブジェクト

レスポンスは全て、Tropoオブジェクトから始まります。 これは、お客様のアプリケーションからTropo WebAPIに送るJSONペイロードのルート要素です。配列あるいはオブジェクトで取得できます。

イベント

onのオブジェクトは、お客様のアプリケーションが処理するイベントを決定します。 1つのJSONの処理が終了した結果、次にどのJSON(またはプログラム)を読みに行くのかを、アプリケーションの成功/失敗/切断などの結果に基づき決定します。 上記の例では、continueincompleteが定義されています。
ユーザがうまく5桁のアカウント番号を打ち込んだら、 continueイベントが発生し、次の動作を求めてウェブサーバ上のthe_answer.jsonを参照します。
ユーザが正しい桁数を入力する事に失敗したり、タイムアウトまでに何も入力しなかった場合、 incompleteイベントが発生し、次の動作を求め、the_wrong_answer.jsonを参照します。
全てのアプリケーションに対してイベントを定義する必要があるわけではありませんが、 動作の結果を取得したり、複雑な動作を設定する場合には必須の機能となります。詳細は、APIリファレンスページのonを参照してください。 JSONを作成するためには、(ライブラリまたは、ご自身でJSONを生成できれば)PHP, C#, Python, Ruby あるいは他のいかなる言語も使用できます。 従って、ファイル拡張子はJSONである必要はありません。TROPOとお客様のサーバーを行き来して、JSONの参照/生成ができる限りは問題ありません。

ステップ 3 - Tropoリザルト

Tropoがリクエストを実行して、ユーザーに入力を求めると、結果に応じてonイベントトリガー(図1.1の3~11行目)の指定のリソースに、resultのJSONドキュメント情報を返します。

図 1.2

{"result":{
	 "sessionId":"3FA7C70A1DD211B286B7A583D7B46DDD0xac106207",
	 "state":"ANSWERED",
	 "sessionDuration":1,
	 "sequence":1,
	 "complete":true,
	 "error":null,
	 "actions":{
		"name":"account_number",
		"attempts":1,
		"disposition":"SUCCESS",
		"confidence":100,
		"interpretation":"12345",
		"utterance":"1 2 3 4 5"
	 }
  }
}

ステップ 4 - 返答とハングアップ

アプリケーションは、ステップ2(図1.1の3~11行目)にあるイベントで定義された、次のリソースに移動します。 このリソースでは、sayオブジェクトと明示的なhangupが設定されています。このリソースはなくてもHTTP200を返すことができます。 その場合、Tropoは自動的にこの呼をハングアップします。

図 1.3

{"tropo":[
	 {
	 "say":
		 [
		   {"value":"ご利用ありがとうございました。"}
		 ]
	 },
	 {"hangup":null}
  ]}

より具体的な内容について知りたい場合は、クイックスタートに移動します。