Web API リファレンス|Tropo Web API

{"transfer":} オブジェクト

   

これを使うと、既に応答された通話を他の宛先または電話番号に転送します。 この通話は、「to」パラメータによって設定された電話番号、 SIPアドレスのどちらにでも転送可能です。

 

このメソッドが呼び出されると、下記のような流れになります。

  • 「on ring」イベントに設定された音声ファイルが、現在の通話で再生されます。 これは、呼び出し音である「hold music」などにも設定できます。
  • この音声ファイルが、ringRepeatで定義された時間になるまで再生されます。
  • 音声の再生中に、指定された宛先に新しい通話をコールします。 
  • 複数の電話番号やSIPアドレスを配列として設定している場合には、最初に電話をとった人と通話します。
  • answerOnMediatrueで、電話会社が転送中に着信音を再生した場合、playvalueで設定された音ではなく、この着信音が再生されます。
  • 通話がタイムアウトの時間内に応答されなかった場合、incompleteイベントが実行され、転送は失敗します。
  • タイムアウト前に通話に応答がなされた場合、2つの電話が接続されます。 このメソッドは話者のどちらかが電話を切るか、シグナルが送られるまで終了しません。
  • タイムアウト以外の何らかの理由により通話が失敗した場合、incompleteイベントが実行されます。
 

追加のダイヤルオプションには下記のようなものがあります。

 
  • postd - 通話が接続された後にダイヤルするためのDTMFディジットです。
  • pause - 電話が接続されてから、数字を出力するまでの待機時間の長さです。これを使うことで、大きな時間の値が定義できます。
  • p - 1秒間の休止のことです。
  • 「14155551212;postd=1234pp56;pause=5s」を例にとってみます。
  • 電話がつながってから5秒後に1234をダイアルし、さらに2秒(PP)時間をおいてから、56をダイアルします。 この例も全く同じことをしますが、少しだけ複雑です。 14155551212;postd=ppppp1234pp56" 'ms' にも対応しているので、5sの代わりに5000msと定めることもできます。
 

Tropoは同期方式なので、transferはブロッキングメソッドです。 つまり、転送が完了するまで、他のメソッドは実行できないということです。

 

転送中の音質を改善するため、音声は発信者と受信者間で直接繋がります。従って、 Tropoはメディアパスに介入していません。 ただし、通話録音( startRecording、 callメソッドの録音オプションのいずれかを介した場合)が実行中である場合には、音声はTropoを介して通信されます。

 

transferが完了してTropoのスクリプトにコントロールが戻れば、同様に音声も戻り、そのTropoアプリに再接続します。

 

通話が応答されたのか、ビジー状態なのか、失敗したのかを判断するには、resultオブジェクトの「disposition」フィールドをご覧ください。 転送された通話がどれくらいの時間、呼び出し、接続されるかを知るには、resultオブジェクトのアクションのdurationプロパティと connectedDurationプロパティをご覧ください。

 

フィールド

to
データの種類:String型またはArray型 デフォルト:なし 必須
着信通話に対する新しい宛先を指定します。2つの形式を取ります。 
  • tel: 電話番号 - フォーマットされた電話番号(たとえば090-0010-0XXX)は、ダイアルする前にTropoによりフォーマットを除去されます
  • sip:username@domain.com - ダイヤルするためのSIP URLです。
  •  
音声電話をかける場合、番号の一部として、ダイヤルオプションを定められます。  
  • postd - 通話が接続された後にダイヤルするためのDTMFディジットです。
  • 一時停止 - 通話が接続された後に、ディジットを発行するまでに待機する時間です。
  • 「14155551212;postd=1234pp56;pause=1000ms」を例にとって説明します。 これは、電話番号に接続した1秒後に1234をダイヤルし、さらに2秒(PP)経った後に、56をダイヤルするということです。
  本文でも述べましたが、複数の電話番号またはSIPアドレスあるいはその両方を音声通話用の配列として一覧表示することもできます。 最初に電話に出た受信者と接続されます。
allowSignals
データの種類:String型またはArray型 デフォルト:*(任意の信号) 任意
このパラメータを使用すると、この関数にシグナルを割り当てることができます。一致するシグナル名を持つTropo REST APIからのイベントは、この関数を中断します。 すでにこの関数が実行され完了していた場合、中断の要求は無視されます。 この関数がまだ実行されていない場合、中断の要求は実行されるまでジョブキューに並びます。 デフォルトでは、allowSignalsはどんなシグナルも有効なものとして認識します。 allowSignalsを定めなかった場合、その関数は「中断なし」として定義されます。 配列を使うこともできます。配列にある名前のいずれかに一致するシグナルを受信した際に、この関数を中断します。
answerOnMedia
データの種類:Boolean型 デフォルト:false 任意
trueに設定すると、callに「応答がなされた」ものとみなし、相手方からメディアを受信するとすぐに、音声の再生がはじまります(リンギング、ビジー信号など)。 Pythonを使用している場合、trueとfalseではなく、必ずTrueとFalseを使用するようにしてください。 callに「応答された」ものと見なされるので、onTimeoutイベントは実行されず、onAnswerイベントが最初の呼び出し音で実行されることに注意してください。 また、answerOnMediaは課金の開始に繋がります。従って、callが接続されない場合にも料金が発生することがあります。
choices
データの種類:Object型 デフォルト:なし 任意
choicesによってterminatorを定めることができます。 このterminatorは転送をキャンセルさせることができるタッチトーンキー(DTMF)です。 一般的なterminatorはシャープキー(♯)です。
from
データの種類:String型 デフォルト:なし 任意
アプリケーションに複数の番号が設定されている場合、ナンバーディスプレイに表示される発信者番号(コーラーID)を指定することができます。 発信者番号の指定は、同一のアプリケーションに紐付く番号のみ有効です。指定が無い場合、またはアプリケーションに関係の無い番号を指定した場合は、 設定に関わらず電話番号一覧の最上位の番号が表示されます。
headers
データの種類:Object型 デフォルト:なし 任意
これは、現在のセッションのセッション開始プロトコル(SIP)ヘッダを含む、高度なネットワーク情報です。
interdigitTimeout
データの種類:Integer型 デフォルト:なし 任意
conferencerecordそしてtransferの場合には、 interdigitTimeout がTropoが新たなキー入力を認識するまでに、 ユーザが必要とする待機時間を秒単位で定めます。 基本的には、 ユーザが間違ったキーを押してセッションを終了してしまった場合(#を押そうとして *を押した場合など)に、 キーを押し直すまでにTropoにどれくらいの待機させるかを設定します。
name
データの種類:String型 デフォルト:なし 必須
これが、作業の結果を識別するのに使われるキーです。こうして、複数の結果を区別できます。 例えば、あなたがユーザに好みの色を質問するとします。ネーム値を 'color(色)'と設定しても、戻ってくる値が 'blue(青)'かもしれません。 1つの結果しか戻ってこない場合には、それほど役立たないかもしれませんが、結果が複数ある場合には、 これが、どの結果がどの作業に属するかを決定する助けとなります。
on
データの種類:Object型 デフォルト:なし 任意
コールバックイベントを追加すれば、お使いのアプリケーションは特定のイベントが発生したとき、それを知ることができます。 transferの場合、イベントには下記のようなものがあります。 ring - これを使えば、発信通話の呼び出し中に音声ファイルの再生または何かを「say」することができます。 connect - 2つの中継局がお互いに接続される前に、転送の宛先の中継局が応答するとこのイベントが実行されます。 転送における「whispers」の一般的な使い方は、通話が接続される前に受信者に対して再生する音声ファイルです(たとえば、通話を受け入れるかどうか尋ねる場合)。 この機能が実行を終えると、2つの中継局が接続されます。 2つの中継局が接続せずに2番目の中継局の転送をhangup()することもできます。通話を選別する際に特に有効です。 「ring」イベントで指定されたこの音声ファイルが、コードのconnectイベントの実行中に再生され続けます。
required
データの種類:Boolean型 デフォルト:true 任意
これにより、Tropoが次の動詞に移動すべきかどうかを決めます。もし、要求が「true」と設定されて、 現在の作業が完全に成功していれば、Tropoは次の動詞に移動します。
ringRepeat
データの種類:Integer型 デフォルト:1 任意
これはringイベントで設定された音声ファイルが繰り返し再生される回数を定めます。
timeout
データの種類:Float型 デフォルト:30.0 任意
これは秒単位で、どれくらいTropoが相手側が電話に応答するのを待機するかを定めます。 タイムアウトに達しても、呼び出しに応答がなければ、incompleteイベントハンドラで指定されたURLが呼び出されます。
 

サンプル

 

新しいSIPアドレスに対する転送例

{
   "tropo":[
      {
         "say":[
            {
               "value":"転送します。"
            }
         ]
      },
      {
         "transfer":{
            "to":"sip:9991427589@example.com"
         }
      }
   ]
}

転送中に再生される音声ファイル付きの転送例

{
   "tropo":[
      {
         "transfer":{
            "to":"09012345XXX",
            "ringRepeat":2,
            "on":{
               "event":"ring",
               "say":{
                  "value":"http://www.phono.com/audio/holdmusic.mp3"
               }
            }
         }
      }
   ]
}

転送中のwhisperの例

{
  "tropo": [
    {
      "say": {
        "value": "転送します。"
      }
    },
    {
      "transfer": {
        "to": "037894XXXX",
        "ringRepeat": 2,
        "on": [
          {
            "event": "ring",
            "say": {
              "value": "http://www.phono.com/audio/holdmusic.mp3"
            }
          },
          {
            "event": "connect",
            "ask": {
              "attempts": 3,
              "say": [
                {
                  "value": "もう一度5桁のアカウント番号をもう一度入力してください。",
                  "event": "nomatch"
                },
                {
                  "value": "すみません、良くわかりませんでした。",
                  "event": "timeout"
                },
                {
                  "value": "5桁のアカウント番号をもう一度入力してください。"
                }
              ],
              "required": true,
              "bargein": true,
              "timeout": 10,
              "name": "foo",
              "choices": {
                "value": "[5 DIGITS]",
                "mode": "dtmf"
              }
            }
          }
        ]
      }
    }
  ]
}