Scripting API リファレンス|TropoスクリプティングAPI

transfer()method

   

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

 

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

  • playvalueで定められたオーディオファイルが、現在の通話で再生されます。 これは、呼び出し音である「hold music」などにも設定できます。
  • このオーディオファイルは、playrepeatで設定された時間まで再生されます。
  • 音声の再生中に、指定された宛先に新しい通話がかけられます。 
  • 複数の電話番号やSIPアドレスが配列として定められている場合には、最初に電話をとった宛先が、通話権を得ます。
  • callerIDを使用している場合、受信者にこの番号が通知されます。
  • answerOnMediatrueで、電話会社が転送中に着信音を再生した場合、playvalueで設定された音ではなく、この着信音が再生されます。
  • 通話がタイムアウトの時間内に応答されなかった場合、timeoutイベントが実行され、transferは失敗します。
  • タイムアウト前に通話に応答がなされた場合、2つの会話が接続されます。 このメソッドは話者のどちらかが電話を切るか、信号が送られるまで戻りません。
  • タイムアウト以外の事由により通話に失敗した場合に、callFailureイベントが実行されます。
 

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

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

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

 

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

 

転送が完了し、コントロールがご利用中のTropoスクリプトに戻ると、当社が音声を受け取り、お使いのTropoアプリケーションに再接続します。

 

転送された通話が、呼び出し接続される時間を決めるには、 イベントオブジェクトのdurationプロパティとconnectedDurationプロパティをご覧ください。

 

詳細については、通話の転送の例をご覧ください。

 

パラメータ

destination
データの種類:String型またはArray型 デフォルト:なし 必須
destinationとは、電話やメッセージの宛先のことです。 現在では、以下のいずれかの形式をとることができます。 
  • 14155551212 - 「」と国名コードを付けてダイヤルするための電話番号です。
  • tel: 14155551212 - 接頭辞にtel: が付いた電話番号です。
  • 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が接続されない場合にも料金が発生することがあります。
callerID
データの種類:String型 デフォルト:なし 任意
アプリケーションに複数の番号が設定されている場合、ナンバーディスプレイに表示される発信者番号(コーラーID)を指定することができます。 発信者番号の指定は、同一のアプリケーションに紐付く番号のみ有効です。指定が無い場合、またはアプリケーションに関係の無い番号を指定した場合は、 設定に関わらず電話番号一覧の最上位の番号が表示されます。
headers
データの種類:Object型 デフォルト:なし 任意
これは、通話をするときに使われるSIPヘッダを含むハッシュです。このパラメータはSIP通話をするときにのみ適用されます。
interdigitTimeout
データの種類:Integer型 デフォルト:なし 任意
conferencerecordそしてtransferの場合には、 interdigitTimeout がTropoが新たなキー入力を認識するまでに、 ユーザが必要とする待機時間を秒単位で定めます。 基本的には、 ユーザが間違ったキーを押してセッションを終了してしまった場合(#を押そうとして *を押した場合など)に、 キーを押し直すまでにTropoにどれくらいの待機してほしいかということを意味します。
onBusy
データの種類:Function型 デフォルト:なし 任意
呼び出されたアドレスがビジー(電話の場合はビジー信号、SIPの場合は480、486、600)を返した場合に実行します。
onCallFailure
データの種類:Function型 デフォルト:なし 任意
発信通話または転送に失敗した場合(多くの場合は発信先の電話番号が間違っているか、切断されているのが原因)に、このイベントが実行されます。
onConnect
データの種類:Function型 デフォルト:なし 任意
転送の宛先の通話レグが応答し、2つの通話レグが互いに接続される前に、このイベントが実行されます。 これにより、転送を受け入れる前のIVRによるウィスパー機能やブラインド転送を設定することができます。 このイベントが実行を終えると、2つの通話レグを接続します。 2つの通話レグを接続せずに2番目の通話レグの転送をhangup()することもできます。通話を選別する際に有効です。 onConnect機能の実行中は、playvalueによって設定された音声ファイルが再生され続けます。
onError
データの種類:Function型 デフォルト:なし 任意
オーディオ再生中にシステムエラー(非ユーザーエラー)が発生した場合に実行されるイベントハンドラを登録します。
onSignal
データの種類:Function型 デフォルト:なし 任意
シグナルによって関数が中断された場合に実行するコールバック関数を指定します。
onSuccess
データの種類:Function型 デフォルト:なし 任意
通話の転送に成功した場合に実行されるイベントハンドラを登録します。
onTimeout
データの種類:Function型 デフォルト:なし 任意
指定された時間内に通信に応答がなされない場合に、実行されるイベントです。
playrepeat
データの種類:Integer型 デフォルト:なし 任意
これはplayvalueによって設定された音声ファイルの再生時間を定めます。
playvalue
データの種類:String型 デフォルト:なし 任意
このパラメータによって設定された音声ファイルが現在の通話で再生されます。 これは、保留音などにも設定できます。
terminator
データの種類:String型 デフォルト:なし 任意
これは、転送をキャンセルするタッチトーンキー(DTMF)です。 このterminatorは、通話が接続された場合のみ有効です。通話の呼び出し中は無効です。
timeout
データの種類:Float型 デフォルト:30.0 任意
応答、ビジー信号、その他のイベントが実行されるまでTropoが待機する時間で、秒単位で表されます。 音声通話の発信の場合には、50~90秒の間に設定することをお勧めします。
  say("転送中です、お待ちください。シャープボタンを押すと転送を中止します。");
transfer(["09012345***","sip:12345678912@221.122.54.86"], {
    playvalue: "/music/horyuon.mp3",
    terminator: "#",
    onTimeout: function(event) {
        say("応答がありませんでした。");
    }
});

-------------------------------------------

// さらに詳しく

transfer("sip:alice@example.com", {
    playvalue: "/music/horyuon.mp3",
    onConnect: function(event){
        ask("1のボタンを押してください。それ以外では切断します。", {
             choices:"1",
             mode: "dtmf",
             onChoice: function(event) {
               say("接続しました。");
             },
             onBadChoice: function(event) {
               say("切断します。さよなら。");
               hangup();
             }
          }
        );
    }
});  
say "転送中です、お待ちください。シャープボタンを押すと転送を中止します。"
transfer ["09012345***","sip:12345678912@221.122.54.86"], {
    :playvalue => "/music/horyuon.mp3",
    :terminator => "#",
    :onTimeout => lambda { |event|
        say "応答がありませんでした。"}
}

-------------------------------------------

#さらに詳しく

transfer "sip:alice@example.com", {
    :playvalue => "/music/horyuon.mp3",
    :onConnect => lambda { |event|
        ask "1のボタンを押してください。それ以外では切断します。", {
            :choices => "1",
            :mode => "dtmf",
            :onChoice => lambda { |event|
                say "接続しました。"
            },
            :onBadChoice => lambda { |event|
                say "切断します。さよなら。"
                hangup
            }
        }
    }
}
<?php
say("転送中です、お待ちください。シャープボタンを押すと転送を中止します。");
transfer(array("09012345***","sip:12345678912@221.122.54.86"), array(
    "playvalue" => "/music/horyuon.mp3",
    "terminator" => "#",
    "onTimeout" => "timeoutFCN"
    )
);
function timeoutFCN($event) {
    say("応答がありませんでした。");
    }
?>

-------------------------------------------

さらに詳しく

<?php
// Using onConnect
transfer("sip:alice@example.com", array(
    "playvalue" => "/music/horyuon.mp3",
    "onConnect" => "screen"
));
 
function screen($event) {
    $result = ask("1のボタンを押してください。それ以外では切断します。", array(
        "choices" => "1",
        "mode" => "dtmf"
    ));
    if ($result->name == "choice") {
        say("接続しました。");
    } else {
        say("切断します。さよなら。");
        hangup();
    }
}
?>
say("転送中です、お待ちください。シャープボタンを押すと転送を中止します。")
transfer(["09012345***","sip:12345678912@221.122.54.86"], {
    "playvalue":"/music/horyuon.mp3", 
    "terminator": "#",
    "onTimeout": lambda event : say("応答がありませんでした。")})

-------------------------------------------

#さらに詳しく

transfer("09012345***", {
  "playvalue":"/music/horyuon.mp3", 
  "terminator": "#",
  "onTimeout": lambda event : say("応答がありませんでした。"),
  "onConnect": lambda event : connect()
})
 
def connect():
  result = ask("1のボタンを押してください。それ以外では切断します。" ,{
    "choices":"1",
    "mode":"dtmf"
  })
 
  if result.name == "choice":
    say("接続しました。")
  else:
    say("切断します。さよなら。")
    hangup()
say("転送中です、お待ちください。シャープボタンを押すと転送を中止します。")
transfer(["09012345***","sip:12345678912@221.122.54.86"], [
    playvalue: "/music/horyuon.mp3",
    terminator: "#",
    onTimeout: { event->
        say "応答がありませんでした。" }
])

-------------------------------------------

//さらに詳しく

transfer("09012345***", [
    playvalue: "/music/horyuon.mp3",
    callerID: "4071234321",
    terminator: "#",
    onConnect: { event->
        result = ask("1のボタンを押してください。それ以外では切断します。", [
            choices: "1",
            mode: "dtmf"
        ])
         
        if(result.name == "choice"){
             say("接続しました。")
        }else{
            say("切断します。さよなら。")
            hangup();
        }
    },
    onTimeout: { event->
        say "応答がありませんでした。" }
])