Java向けProgrammable Voiceクイックスタート

Javaを使用し、Twilio Programmable Voiceを使用した通話の発着信を始める準備はできましたか?

このJava向けProgrammable Voiceクイックスタートでは、REST API用のTwilio Javaヘルパーライブラリーを使用し発着信する方法を説明します。

このクイックスタートでは、以下について説明します。

1. Twilioにサインアップし、音声対応のTwilioの電話番号を初めて取得する
2. 開発環境を設定し、通話の発着信を行う
3. Twilioを使用し最初の電話をかけましょう!
4. 通話の着信・応答時に、Text to Speechを使用し発信側に対しメッセージを読み上げる

ビデオもご用意しています。Java Voiceクイックスタートビデオ(YouTube)をご覧ください。

Twilioにサインアップし、Twilioの電話番号を取得する

Javaから電話をかける前に、Twilioアカウントにサインアップするか、既存のアカウントにサインインし音声対応の電話番号を購入する必要があります。

音声機能付きのTwilio電話番号をまだお持ちではない場合には、ご購入いただく必要があります。 [Buy a Number](番号を購入する)ページに移動し、[Voice]ボックスをチェックし、[Search](検索)をクリックします。

使用可能な電話番号とその機能のリストが表示されます。好みの番号を探し、[Buy](購入)をクリックし、アカウントに追加します。

これでTwilioアカウントとプログラム可能な電話番号が作成できたため、早速コードを書いてみましょう!次に、Java環境を設定し、Javaアプリケーション用のTwilio公式ヘルパーライブラリーをダウンロードします。

Java環境を設定する

最初の電話をかけるには、Java Standard Edition (SE) Development Kit (JDK)をインストールする必要があります。JDKがインストールされているか分からない場合は、次のコマンドを実行し、使用しているバージョンを確認してください。

javac -version

次のような出力が表示されます。

javac 1.8.0_92

Twilio SDKには、Java SE 8以降が必要です。上記のコマンドを実行するとバージョン番号「1.8」以降と表示されます。

Javaのバージョンが古いか、JDKがインストールされていない場合は、先に進む前にJDKをインストールする必要があります。Java SEダウンロードページを開き、手順に従い、ご利用のプラットフォーム(Windows、Mac、Linux)用のJava SE Development Kitをインストールします。

スタンドアロンのTwilio Javaヘルパーライブラリーをダウンロードする

Javaの設定はすべて完了しましたか?素晴らしい!

次に、スタンドアロンのTwilio Javaヘルパーライブラリーをダウンロードします。このライブラリーでは、Javaを使用しTwilio APIを呼び出すためのJavaクラスと、実行させるために必要な他のすべての依存関係を利用できます。jarファイルをダウンロードする際は、twilio-8.x-jar-with-dependencies.jarのような名前のファイルをダウンロードします。

Maven、Gradle、または別のビルドツールを使用しますか?

Mavenを使用し、pom.xmlファイルの<dependencies>タグ内に、以下を配置します。

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio</artifactId>
  <version>8.0.0</version>
</dependency>

Gradleを使用し、build.gradleファイルの依存関係ブロック内に、次の行を貼り付けます。

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"

Java IDEを使用し、アプリケーションを構築している場合は、依存関係のgroup id、artifact id、version numberを指定できます。

使用しているパッケージマネージャーに関係なく、Twilio Javaヘルパーライブラリーの最新バージョンを指定してください。最新バージョン番号はTwilio Javaヘルパーライブラリーページで確認してください。

Javaを使用し通話を発信する

JDK設定を完了し、Twilio Javaヘルパーライブラリーをダウンロードしたため、APIリクエストを一回送るだけで、購入したばかりのTwilioの電話番号から電話をかけることができます。MakePhoneCall.javaという新しいファイルを作成します。このファイルを開き、コードサンプルを入力するか、貼り付けます。

電話をかける前に、このファイルをもう少し編集する必要があります。

プレースホルダの認証情報値を置き換える

ACCOUNT_SIDとAUTH_TOKENのプレースホルダ値を、ご自身のTwilio認証情報に置き換えます。https://www.twilio.com/consoleに移動し、ログインします。このページでは、お客様固有のAccount SIDとAuth Tokenを確認できます。この作業は、今回のようにTwilio Javaヘルパーライプラリーを使用し電話をかける際に必要となります。「目」のアイコンをクリックすると、Auth Tokenが表示されます。

MakePhoneCall.javaを開き、ACCOUNT_SIDとAUTH_TOKENの値をご自身固有の値に置き換えます。

"from"の電話番号を置き換える

数分前に購入した音声対応の電話番号を覚えていますか。入力されているfromの番号を、その番号に置き換えます。必ずE.164形式を使用してください。

[+][国コード][エリアコードを含む電話番号]

"to"の電話番号を置き換える

toの電話番号をご自身の電話番号に置き換えます。どの電話番号でも構いませんが、素晴らしさを体験するために、ご自身の番号を使用することをお勧めします。上記のように、この値にはE.164形式を使用します。

変更内容を保存し、ターミナルからこのJavaクラスをコンパイルします。

着信通話を受け応答する

お使いのTwilio番号が着信通話を受けると、お使いのサーバーにHTTPリクエストが送信されます。このコールバックメカニズムのことをWebhookといいます。 Twilioがアプリケーションにリクエストを送信すると、Twilioは、メッセージへの応答方法を説明する応答をTwiML XML形式で受け付けます。

Spark Webアプリケーションフレームワークを使用し、Javaで構築する方法を見てみましょう。Sparkは軽量のWebアプリケーションフレームワークであり、Apache Sparkというビッグデータソフトウェアとは完全に別物です。

Sparkには、TwilioのJavaヘルパーライブラリーとは別に、独自のライブラリーが必要です。Spark Javaのダウンロードページに記載されている指示に従い、インストールしてください。SparkをMaven、Gradleで使用する方法、またはスタンドアロンのダウンロードとして使用する方法をご覧ください。Sparkにはログ機能は実装されていませんが、Simple Logging Facade 4 Java(SLF4J)と連携でき、これをJavaクラスパスに含めることもできます。

上記のセクションでTwilioを使用し電話をかけたとき同様に、コマンドラインですべての依存関係を確実に設定できますが、Javaの統合開発環境(IDE)を使用し、すべての設定を行う方が少し簡単です。JetBrainsからダウンロードできるIntelliJ IDEAの無料のコミュニティエディションを使用します。JARファイルをダウンロードしIntelliJ IDEAで直接使用することも、MavenやGradleなどの依存関係マネージャーを使用することもできます。ここでは、GradleとIntelliJ IDEAを使用しアプリケーションを構築します。

IntelliJ IDEAとGradleを使用しWebアプリケーションを作成する

IntelliJ IDEAのコミュニティエディションをダウンロードし、インストールしていない場合は今すぐダウンロードしてください!IDEAを初めて実行すると、次のような画面が表示されます。

[Create New Project](プロジェクトの新規作成)を選択すると、新しいプロジェクトのウィザードが起動します。

そのダイアログボックスの左側で、(Javaではなく)[Gradle]を選択すると、IntelliJ IDEAが依存関係の管理にGradleを使用するようにプロジェクトを設定してくれます。ここでは、代わりにMavenを使用することもできます。プロセスはほとんど同じです。

[Gradle]を選択した後、IntelliJ IDEAにプロジェクトSDKがあることを確認してから(Java 8以降、つまりバージョン1.8以降が必要)、[Next](次へ)をクリックします。

ウィザードの次の画面では、group id、artifact id、version numberの入力を求められます。group idにはcom.yourcompany.voiceのようなリバースドメイン名を使用でき、artifact idにはvoice-quickstart-appのようなプロジェクト名を使用する必要があります。バージョンは、1.0-SNAPSHOTのままでも構いません。これらのフィールドに入力した後、[Next]」(次へ)をクリックします。

このGradle設定画面において、デフォルトのままで[Next]」(次へ)をクリックできます。

最後に、クイックスタートWebアプリケーションに使用するプロジェクト名とプロジェクトディレクトリを確認します。ここでもデフォルトのままで問題ありません。[Finish](完了)をクリックすると、新しいIntelliJプロジェクトに移動します。IntelliJ IDEAをインストールしたばかりの場合、IDEはGradleをダウンロードし、セットアップとインストールを行います。

これでプロジェクトのセットアップが完了し、あとはいくつかのステップだけです!Twilio Javaヘルパーライブラリーと依存関係としてのSpark Java Webアプリケーションフレームワーク、そしてSparkからのステータスメッセージを表示できるようにログ機能の実装が必要です。Gradleを使用すると、IntelliJが作成したbuild.gradleファイルにそれらを追加できます。先に進み、サイドバーでbuild.gradleを見つけ、クリックし開きます。

build.gradleに依存関係を追加する

依存関係グループのbuild.gradleファイルに、次の3行を追加する必要があります。

compile group: "com.twilio.sdk", name: "twilio", version: "8.0.+"
compile group: "com.sparkjava", name: "spark-core", version: "2.7.1"
compile group: "org.slf4j", name: "slf4j-simple", version: "1.7.21"

こうした3つの依存関係により、Gradleは適切なライブラリーをダウンロードし、Javaアプリケーションを構築・実行するためのクラスパスに追加してくれます。

これで準備ができたため、次はコードを書いてみましょう!

着信通話に応答する

プロジェクト内にJavaクラスを作成することから始めます。IntelliJ IDEAで、srcとmain.配下のjavaフォルダを選択します。次に、画面上部の[File](ファイル)メニューを開きます。[New](新規作成)サブメニューを選択してから、[Java Class](Javaクラス)を選択します。

小さなポップアップウィンドウが表示され、新しいクラスを作成できます。クラスにVoiceAppという名前を付けます。コードサンプルと一致させる必要があるため、大文字と小文字を区別することが重要です。

これでVoiceApp.javaソースコードファイルができました。コードサンプルからそのソースコードファイルにコードをコピーし貼り付けます。

このJavaコードは、「/hello」へのインバウンドHTTP GETリクエストをリッスンし、「Hello Web」で応答し、さらに「/」へのインバウンドHTTP POSTリクエストをリッスンし、TwiMLマークアップで応答します!

ngrokを使用し、TwilioをJavaアプリケーションと通信させる

着信通話を受け付けるための小規模なJava Webアプリケーションを構築しました。これが機能するには、Twilioがアプリケーションにアクセスできるようにする必要があります。

大半のTwilioサービスは、Webhookを使用することによりアプリケーションと通信します。例えば、Twilioが着信通話を受けると、メッセージの処理方法の指示を受けるためにアプリケーションを使用しURLに接続します。

自分の開発環境にあるJava Webアプリケーションの作業をしている場合、そのコンピューター上の他のプログラムからしかアプリにアクセスできません。つまり、Twilioからはアクセスできません。インターネットでアプリケーションにアクセスできるようにし、この問題を解決する必要があります。

アプリケーションをHerokuやAWSにデプロイするなど、方法はいくつかありますが、Twilioアプリケーションのテストには手間の少ない方法を採用します。インターネットでアプリケーションに簡単にアクセスできるようにするためには、ngrokというツールをお勧めします。ngrokは、ローカルWebサーバーが実行されているのと同じポートでリッスンし、ngrok.ioドメインで一意のURLを指定し、着信リクエストをローカルの開発環境に転送します。以下のように機能します。

まだインストールしていない場合は、ngrokをインストールします。オペレーティングシステムに適したngrokバージョンであることを確認し、「ngrok」コマンドがシステムパス上にあることを確認してください。MacまたはLinuxをお使いの場合には、これだけで作業は終わりです。Windowsをご使用の場合は、Windowsにngrokをインストールし、設定する方法についてのガイドを参照してください。ngrokの活用方法などの詳細については、こちらの詳細なブログ記事をご覧ください。

これで、新しい外部URLができました。

Webhook URLを設定する

次にコンソールを使用し、その公開URLを、電話番号の1つのWebhookとして設定する必要があります。コンソールに戻り、電話番号を選択し、以下に示すように[A CALL COMES IN](着信)を「Webhook」に変更し、次に「https://069a61b7.ngrok.io/」など、サービスへの外部URLを入力します。

変更内容を保存すると、準備完了です。

アプリケーションをテストする

コマンドラインで「ngrok」コマンドを実行し、IntelliJ IDEAからWebアプリケーションを実行していることを確認してください。ngrokを再起動した場合は、正しいURLを使用するようにコンソールでWebhookを更新する必要があります。

これらの両方が実行されている状態のまま、新しいJava Webアプリケーションをテストします。

このWebhookで設定したTwilio電話番号に電話をかけます。ngrokコンソールに200 OKのHTTP POSTリクエストが表示されます。Java WebアプリケーションがTwiML応答でTwilioに応答し、メッセージが読み上げられるのが聞こえます!

次のステップ

Javaを使用した通話の発着信に関する基本が理解できました。

このアプリでは、TwiML動詞<Say>のみを使用し、音声合成機能により発信者に向けてメッセージを読み上げました。別のTwiML動詞を使用すると、他のパワフルな構成や通話フローを作成できます。<Record>、<Gather>、<Conference>など、いくつか試してみてください。

詳細については、以下のページをご覧ください。

• Programmable Voice APIのリファレンスドキュメントを読む
• TwiMLリファレンスドキュメント
• Javaでのサンプルアプリケーションのチュートリアル
• IntelliJでSparkとJava 8を使用し、通話の発着信をする方法

コーディングを楽しみましょう!