2013年6月1日土曜日

Twilio を使ってブラウザから電話してみる

クラウド電話APIを提供するTwilio(トゥイリオ)が日本でも4月17日からサービスを開始しました(参考:KDDIウェブコミュニケーションズ、クラウド電話API「Twilio」を国内提供)。Twilio を使えば、様々なデバイス(PCやタブレットなど)を電話機として使えます。Twilio 電話番号を購入し、アカウントを取得すれば Twilio を利用することができます。無料で使えるトライアルアカウントを取得することもできるので、簡単に試めすことができます。アカウントの登録や、SDKのダウンロードはこちらのページから行うことができます。

Twilio を利用する様々なシナリオが考えられますが、簡単なシナリオから始めることにします。

シナリオ1:電話機(携帯、固定電話)から Twilio 番号に電話する
購入電話番号にはどんな電話番号からでも電話できますが、トライアルアカウントの場合はベリファイされた電話番号だけが使用できます。取得した Twilio 電話番号ごとに Voice Request URL という入力欄があります。ここに自分が作成したウェブ アプリケーションの URL を設定すると、この電話番号で受信したときにこのアプリを実行することができます。このアプリで Twilioマークアップコマンドをレスポンスとして返すことで様々な処理を行うことができます。

Twilio マークアップレスポンスの例(女性の声で日本語のメッセージを読む):
<Response>
    <Say voice="woman" languege="ja_jp">こんにちは これはテストです</Say>
</Response>

このマークアップを出力する Javaサーブレットを作成して、実際に電話に応答するまでを順を追って説明します。

(WEBアプリの作成)
  1. Eclipse で動的Webプロジェクト(twiml) を作成
    RAP で WEB アプリを作成することもできますが、今回は動的WEBプロジェクトを使用します。File > New >  Dynamic Web Project を選択してプロジェクトを作成します。
    プロジェクト名は twiml とします。
  2. java SDK ライブラリの設定
    Java で Twilio API を使うためのライブラリをダウンロードして、プロジェクトの WebContent/WEB-INF/lib フォルダにコピーします。
    SDK は、https://github.com/twilio/twilio-java からダウンロードしてください。
  3. サーブレットの作成
    上述のマークアップコマンドを出力する以下のサーブレットを作成します。
    twilio.twiml.Test1MLServlet:
    public class Test1MlServlet extends HttpServlet {
    
        public void service(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
    
            response.setContentType("text/html; charset=UTF-8");
            request.setCharacterEncoding("UTF-8");
    
            // 応答メッセージを話す TwiML の作成
            TwiMLResponse twiml = new TwiMLResponse();
            Say say = new Say("こんにちは これはテストです");
            say.setLanguage("ja-jp");
            say.setVoice("woman");
            try {
                twiml.append(say);
            } catch (TwiMLException e) {
                e.printStackTrace();
            }
            response.setContentType("application/xml");
            response.getWriter().print(twiml.toXML());
        }
    }
  4. web.xmlの作成
    以下の web.xml を作成して、上記サーブレットをマッピングします。
    WebContent/WEB-INF/web.xml:
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
        version="3.0">
        <display-name>twilio ml</display-name>
        <servlet>
            <servlet-name>Test1MlServlet</servlet-name>
            <servlet-class>twilio.twiml.Test1MlServlet</servlet-class>
        </servlet>
    
        <servlet-mapping>
            <servlet-name>Test1MlServlet</servlet-name>
            <url-pattern>/test1</url-pattern>
        </servlet-mapping>
    </web-app>
  5. war ファイルをエクスポート
    プロジェクトエクスプローラーで twimlプロジェクトを選択して、ポップアップから Export > WAR file を選択して適当なフォルダへ twiml.war をエクスポートします。

(アプリを公開サーバーにデプロイ)
アプリを公開する方法については Twilio ドキュメントにも色々な方法が説明されていますが、私は、CroudBees の Run@cloud を利用しました。 Run@cloud で新しいアプリを作成し、上で作成した twiml.war をデプロイします。

注意:CroudBees については以前のポスト「CloudBees で RAPアプリケーションを開発する(3) デプロイと実行」を参考にしてください。


(アプリURLを電話番号の Voice Request URLに設定)
Run@cloud で作成したアプリのロケーションが http://xxx.zzz.cloudbees.net/ の場合、Test1MlServlet の URL は http://xxx.zzz.cloudbees.net/test1 となります。これを先に説明した twilio 電話番号の Voice Request URL に設定してください。



これで、携帯電話から Twilio 電話番号に電話をかけるとメッセージを聞く事ができます。出力するマークアップを変えればもっと実用的な処理を実行できます。

次はもう少し複雑な例を取り上げます。

シナリオ2: ブラウザから電話する
ここで作成するアプリのおおまかな処理の流れは次のようになります
  1. ブラウザで実行されるアプリの処理内容:
    1. Twilio 登録アカウントの SID と 認証トークンを使って TwilioCapability オブジェクトを作成します。
    2. TwilioCapability#allowClientOutgoing() を使って接続時に実行するアプリ(TWIMLアプリ)の SID を指定します。この SID は TWIMLアプリを作成すると取得できます。(TWIMLアプリの作成については後で説明します)
    3. TwilioCapability#generateToken() でケーパビリティトークンを取得します。
    4. JavaScript オブジェクトでブラウザから Twilio に接続します。
  2. TWIMLアプリ(サーブレット)の処理内容:
    指定された電話番号へダイアルする Twilio マークアップコマンドを出力します。
上記1. のブラウザで実行するアプリはローカルサーバー上で実行することもできますが、2.のTWIMLアプリは公開サーバー上になければなりません。まず 1. のアプリを作成します。

注意:これらのアプリは「Twilio Client Java クイックスタート」のサンプルを参考にして作成しました。詳しい説明はそちらをご覧ください。

(ブラウザで実行するアプリの作成)
  1. シナリオ1で作成したプロジェクトに新しいサーブレットを追加します。
    このサーブレットは登録アカウントの SID と認証トークンを使って TwilioCapability オブジェクトを作成し、それを使って、Twilio 接続時に実行するアプリケーションの設定を行います。そして、 操作画面のJSPビューへリダイレクトします。
    twilio.client.TwiliolServlet:
    public class TwilioServlet extends HttpServlet {
    
        public static final String ACCOUNT_SID = "YOUR_ACCOUNT_SID";
        public static final String AUTH_TOKEN = "YOUR_AUTH_TOKEN";
    
        public void service(HttpServletRequest request, HttpServletResponse response)
                throws IOException, ServletException {
            
            response.setContentType("text/html; charset=UTF-8");
            request.setCharacterEncoding("UTF-8");
    
            String applicationSid = "YOUR_APP_SID";
            TwilioCapability capability = new TwilioCapability(ACCOUNT_SID, AUTH_TOKEN);
            capability.allowClientOutgoing(applicationSid);
            String token = null;
            try {
                token = capability.generateToken();
            } catch (DomainException e) {
                e.printStackTrace();
            }
            // Forward the token information to a JSP view
            response.setContentType("text/html");
            request.setAttribute("token", token);
            RequestDispatcher view = request.getRequestDispatcher("client.jsp");
            view.forward(request, response);
        }
    }
  2. 上の TwilioServlet から呼ばれる Jsp ビューを作成します。
    この JSP では「call」ボタン、「hungup」ボタン、電話番号入力用のテキストを表示します。
    ユーザーが電話番号を入力して、「call」ボタンを押すと call() 関数が呼ばれ、Twilio に接続します。Twilio はアプリの SID を調べ、対応する URLのTWIMLアプリを実行します。
    WebContent/client.jsp:
    <!DOCTYPE html>
    <html>
      <head>
        <title>Hello Client Monkey 4</title>
        <script type="text/javascript"
          src="//static.twilio.com/libs/twiliojs/1.1/twilio.min.js"></script>
        <script type="text/javascript"
          src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js">
        </script>
        <link href="http://static0.twilio.com/packages/quickstart/client.css"
          type="text/css" rel="stylesheet" />
        <script type="text/javascript">
     
        Twilio.Device.setup("${token}", {debug: true});
     
          Twilio.Device.ready(function (device) {
            $("#log").text("Ready");
          });
     
          Twilio.Device.error(function (error) {
            $("#log").text("Error: " + error.message);
          });
     
          Twilio.Device.connect(function (conn) {
            $("#log").text("Successfully established call");
          });
     
          Twilio.Device.disconnect(function (conn) {
            $("#log").text("Call ended");
          });
     
          function call() {
            params = {"PhoneNumber": $("#number").val()};
            Twilio.Device.connect(params);
          }
     
          function hangup() {
            Twilio.Device.disconnectAll();
          }
        </script>
      </head>
      <body>
        <button class="call" onclick="call();">
          Call
        </button>
     
        <button class="hangup" onclick="hangup();">
          Hangup
        </button>
     
        <input type="text" id="number" name="number"
          placeholder="Enter a phone number to call"/>
     
        <div id="log">Loading pigeons...</div>
      </body>
    </html>
  3. web.xml に次のサーブレットとマッピングの定義を追加します。
    WebContent/WEB-INF/web.xml の修正:
        <servlet>
            <servlet-name>TwilioServlet</servlet-name>
            <servlet-class>twilio.client.TwilioServlet</servlet-class>
        </servlet>
        ...
        <servlet-mapping>
            <servlet-name>TwilioServlet</servlet-name>
            <url-pattern>/client</url-pattern>
        </servlet-mapping>
    
(TWIMLアプリの作成)
  1. 同じプロジェクトに次のサーブレットを追加します。
    このサーブレットはリクエストパラメータとして渡された電話番号にダイアルするマークアップコマンドを出力します。
    twilio.client.TwilioDialServlet:
    public class TwilioDialServlet extends HttpServlet {
    
        public void service(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
    
            String phoneNumber = request.getParameter("PhoneNumber");
            String callerId = "+815088889999";
    
            TwiMLResponse twiml = new TwiMLResponse();
            Dial dial = new Dial();
            try {
                if (phoneNumber != null) {
                    dial.append(new Number(phoneNumber));
                    dial.setCallerId(callerId);
                }
                twiml.append(dial);
            } catch (TwiMLException e) {
                e.printStackTrace();
            }
            response.setContentType("application/xml");
            response.getWriter().print(twiml.toXML());
        }
    }
    注意: callerId は自分の Twilio 電話番号を使用する必要があります。
  2. web.xml に次のサーブレットとマッピングの定義を追加します。
        <servlet>
            <servlet-name>TwilioDialServlet</servlet-name>
            <servlet-class>twilio.client.TwilioDialServlet</servlet-class>
        </servlet>
        ...
        <servlet-mapping>
            <servlet-name>TwilioDialServlet</servlet-name>
            <url-pattern>/dial</url-pattern>
        </servlet-mapping>
    
(WARファイルのエクスポート)
 シナリオ1の場合と同様にして、twiml.war をエクスポートします。

(WARファイルのデプロイ)
同様に、シナリオ1で作成した Run@cloud のアプリへ twiml.war をアップロードして新バージョンに置き換えます。

(TWIMLアプリの登録)
Twilio の登録アカウントにログインして、ツールタブのTWIML APP タブから新しいアプリを作成します。作成したアプリの Request URL フィールドに上記 TwilioDialServlet の URL(例えば、http://xxx.zzz.cloudbees.net/dial)を設定します。

ブラウザでURLとして、http://xxx.zzz.cloudbees.net/client (Run@cloud のアプリを実行する場合)または http://localhost:8080/twiml/client(Eclipse IDE から実行する場合)を入力してアプリを実行すると次の画面が表示されます。


自分の携帯の番号を設定して「call」ボタンを押すと携帯に電話をかけることができます。
注意: 電話番号が 080-1111-2222 の場合 +818011112222 を入力します。


0 件のコメント: