Twilioの人気動詞Gather、電話器のプッシュ音を認識し、いろんな処理を簡単に実現させます。

Twilioのプッシュ音認識機能、をご紹介します。
プッシュ音とは、スマホや固定電話など電話器の数字ボタンを押した際に発生する「音」のことを言います。

Twilioはこの「音」を数字に変換し、呼ばれた処理に値（データ）をPSOTやGETで渡します。
このプッシュ音認識機能はTwilioの機能の中で良く使われる動詞の一つです。
例えば、受信電話番号の振り分け、IVR（自動音声応答）などの開発で良く使われています。

Twilioの「Gather」を使えば単なる電話処理だけではなく、PHPやRubyなどプログラミング言語による開発も可能です。

プッシュ音認識 Gather

Gather動詞は短いコードで、ユーザーから入力されたプッシュ音を認識します。 まず、下のコードをTwilioのRequest URLに設定し、電話をかけてみてください。

そうすると、4行目のメッセージが再生された後、無言状態になります。
そこで、電話器の数字ボタンをプッシュしてみてください。
プッシュされたボタン（キー）の値を取得できるのがです。

なお、Twilioの動詞にはそれぞれいろんな属性を持っていますので、Gatherの属性も試してみてください。
今回のコードでには「timeoutとfinishOnKey」が設定されています。
属性に関する情報やサンプルコード、概要などは下の公式ドキュメントから確認できます。
TwiML 音声通話：Gather

※ Request URLの設定はブログの「◎ 電話番号管理画面」を参考してください。

twilio-gather.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather timeout="10" finishOnKey="*">
    <Say language="ja-jp">こんにちは、ボタンを入力してください。</Say>
  </Gather>
</Response>

ネスト動詞

下記の二つのサンプルコードみればお分かりかと思いますが、二つのサンプルコードは動きが違います。

・上のサンプルコードはメッセージの再生の途中でもキーの入力可能です。
・下のサンプルコードはメッセージの再生の途中にはキーの入力不可能です。

つまり、動詞はSayとPlay動詞のネストが可能です。

twiml-gather-say.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather timeout="10">
    <Say language="ja-jp">Gatherの処理を遷移させます。</Say>
  </Gather>
</Response>

twiml-gather-say-se.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather timeout="10" />
  <Say language="ja-jp">Gatherの処理を遷移させます。</Say>
</Response>

通話の分岐

ここでは通話の処理を分岐させてみたいと思います。 このソースコードは電話をかけたユーザーから好きな果物を電話の数字ボタンで選択してもらいます。 ① ユーザーが050に電話をかけます。 ② 6行目のアナウンスに従って好きな番号をプッシュします。 ③ ユーザーがプッシュした数字がTwilio経由でこのファイルに戻って来ます。 戻って来る値はPOSTまたはGETに設定されます。（選択可）

■ Request URL
下記のソースコードURLをTwilioの電話番号（050）のRequest URLに設定すると、そのRequest URLに値を渡します。
によるデータはリアルタイムで渡されますので、動的なアプリケーションの開発が可能です。

なお、7行目の動詞を他の分岐処理の中に入れますと、処理を入れた箇所で新しい入力を受けることになります。

twilio-gather-ivr.php

<?php
  header("content-type: text/xml");
?>
  <Response>
<?PHP if (empty($_POST["Digits"])) { ?>
  <Say language="ja-jp">リンゴは1を、オレンジは2を、バナナは3を押してください。</Say>
  <Gather numDigits="1" timeout="30" />
<?PHP } elseif ($_POST["Digits"] == "1") { ?>
  <Say language="ja-jp">リンゴを選択しました。</Say>
<?PHP } elseif ($_POST["Digits"] == "2") { ?>
  <Say language="ja-jp">オレンジを選択しました。</Say>
<?PHP } elseif ($_POST["Digits"] == "3") {?>
  <Say language="ja-jp">オレンジを選択しました。</Say>
<?PHP } else { ?>
  <Say language="ja-jp">入力は1から3までです。</Say>
<?PHP } ?>
</Response>

Twilioのライブラリを使いますと。

Twilioは様々なプログラミング言語のライブラリを提供しています。 今回はPHPのライブラリを使いましたが、他のライブラリも是非ご覧ください。

twiML-ivr-test.php

<?php
  require("../Services/Twilio.php");
 
  $response = new Services_Twilio_Twiml();
 
  if (empty($_POST["Digits"])) {
    $gather = $response->gather(array('numDigits' => 1, 'timeout' => 30));
    $gather->say("許可するには1を拒否は2を押してください。", array('language' => 'ja-jp'));
  } elseif ($_POST["Digits"] == "1") {
    $response->say("許可を選びました。", array('language' => 'ja-jp'));
  } elseif ($_POST["Digits"] == "2") {
    $gather->say("拒否を選びました。", array('language' => 'ja-jp'));
    $gather = $response->gather(array('numDigits' => 1, 'timeout' => 30));
  }
  print $response;
?>

入力後の処理を遷移させる

こちらの処理はによる処理終了後その処理を遷移させることが可能です。 使い方は簡単、Gather動詞に actionに遷移先のURLを記述します。 サンプルコードではパラメータ変数を「POST」になっていますが、GETにすることも可能です。 このように書けば、$_GET["userId"]から値の取得が可能になります。

twiml-gather.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather action="twiml-gather-action.php" method="POST">
    <Say language="ja-jp">Gatherの処理を遷移させます。</Say>
  </Gather>
</Response>

twiml-gather-action.php

<?php
  header("content-type: text/xml");
 
  $tel_from = $_POST['From'];
  $tel_to = $_POST['To'];
  $call_status = $_POST['CallStatus'];
  $gather = $_POST['Digits'];
?>
<Response>
  <Say language="ja-jp">入力された値は<?php echo $gather; ?>です。</Say>
</Response>