Java向けProgrammable Voiceクイックスタート
Javaを使用し、Twilio Programmable Voiceを使用した通話の発着信を始める準備はできましたか?
このJava向けProgrammable Voiceクイックスタートでは、REST API用のTwilio Javaヘルパーライブラリーを使用し発着信する方法を説明します。
このクイックスタートでは、以下について説明します。
- Twilioにサインアップし、音声対応のTwilioの電話番号を初めて取得する
- 開発環境を設定し、通話の発着信を行う
- Twilioを使用し最初の電話をかけましょう!
- 通話の着信・応答時に、Text to Speechを使用し発信側に対しメッセージを読み上げる
ビデオもご用意しています。Java Voiceクイックスタートビデオ(YouTube)をご覧ください。
Twilioにサインアップし、Twilioの電話番号を取得する
Twilioアカウント、音声対応のTwilio電話番号をすでにお持ちの場合は、次のステップに進んでください。
Javaから電話をかける前に、Twilioアカウントにサインアップするか、既存のアカウントにサインインし音声対応の電話番号を購入する必要があります。
音声機能付きのTwilio電話番号をまだお持ちではない場合には、ご購入いただく必要があります。 [Buy a Number](番号を購入する)ページに移動し、[Voice]ボックスをチェックし、[Search](検索)をクリックします。
使用可能な電話番号とその機能のリストが表示されます。好みの番号を探し、[Buy](購入)をクリックし、アカウントに追加します。
これでTwilioアカウントとプログラム可能な電話番号が作成できたため、早速コードを書いてみましょう!次に、Java環境を設定し、Javaアプリケーション用のTwilio公式ヘルパーライブラリーをダウンロードします。
Java環境を設定する
すでにJava開発環境がすべて設定されており、クラスパスにTwilio Javaヘルパーライブラリーが設定されていますか?次の2つのセクションをスキップし、Twilioを使用し最初の電話をかけることができます!
最初の電話をかけるには、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ヘルパーライブラリーページで確認してください。
このTwilio Javaヘルパーライブラリーは、Androidアプリケーションでの使用を目的としたものではありません!このライブラリーは、サーバー、コマンドラインアプリケーション、同様のプロジェクトに使用します。TwilioのアカウントSIDと認証トークンをエンドユーザーに配布することは、Twilioアカウントのセキュリティリスクになります。
モバイルアプリケーション(AndroidまたはiOS)から通話を発着信する場合は、Twilio Programmable Voice SDKを使用する必要があります。開始方法については、こちらのページをご覧ください!
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クラスをコンパイルします。
javac -cp twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall.java
コマンドラインからクラスをコンパイルするには、Twilio jarを依存関係に含める必要があります。IntelliJ IDEA、NetBeans、Eclipseなどの統合開発環境(IDE)を使用している場合は、他の依存関係と同様に、そのTwilio jarをクラスパスまたはプロジェクトライブラリーに追加するだけです。MavenやGradleなどのビルドツールを使用し、Javaアプリケーションをビルドして実行することもできます。依存関係としてTwilioのヘルパーライブラリーを指定するだけです。
Javaクラスをビルドした後、実行する必要があります。macOSまたはLinuxのコマンドラインから実行している場合、コマンドは次のようになります。
java -cp .:twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall
Windowsでは、これに相当するコマンドは次のようになります。
java -cp .;twilio-8.0.0-jar-with-dependencies.jar MakePhoneCall
違いは、WindowsではコマンドラインのJavaクラスパス区切り文字がセミコロンであり、macOSまたはLinuxではコロンであるということです。
これで完了です。すぐに、Twilioの電話番号から、通話の着信があるはずです。
Twilioのトライアルアカウントを使用している場合は、Twilioにより確認された電話番号のみに音声通話を発信できます。電話番号は、Twilio Consoleの認証済み発信者IDにより認証できます。
着信通話を受け応答する
お使いの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マークアップで応答します!
コードを配置した後、左側のプロジェクトアウトラインでVoiceAppクラスを右クリックしてから、[Run VoiceApp.main()](VoiceApp.main()を実行)メニューの項目を選択できます。
Java Spark Webアプリケーションサーバーは、ポート4567でリスニングを開始します。
http://localhost:4567/hello
にアクセスし、サーバーが機能していることを確認してください。Webブラウザーに「Hello Web」が表示されるはずです。
ここで注意が必要な点として、コードに変更を加えサーバーを再度実行する場合は、現在実行中のアプリケーションを赤い停止ボタンで停止する必要があります。一度にポート4567を使用できるアプリケーションは1つだけであるため、古いバージョンがまだ実行しているときにJavaアプリケーションを実行すると、新しいアプリケーションはすぐに終了します。
アプリケーションをインターネット経由でアクセスできるようにする必要があります。これはさまざまな方法で可能ですが、ngrokという外部からアクセス可能なURLを提供するツールをお勧めします。アプリケーションが通話を着信できるように、次の設定を行います。
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の活用方法などの詳細については、こちらの詳細なブログ記事をご覧ください。
次のコマンドは、ngrokを使用しport 4567
を公衆インターネットに公開します。コマンドラインに次のコマンドを入力します。
ngrok http 4567
そして、次のような出力が表示されます。
これで、新しい外部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を使用し、通話の発着信をする方法
コーディングを楽しみましょう!
サポートが必要ですか?
コーディングに関するご質問、ご不明点等ございましたら、お問い合わせからご連絡いただくか、TwilioのStack Overflow Collectiveにアクセスいただくか、Stack OverflowサイトでTwilioタグを検索してください。