LEXUES BLOG

レキサスブログ

Hello, Twilio! たった4行のコードで電話機能を実装するクラウド電話APIに触れてみよう

こんにちは!あげなかずと@新入社員です!
この度沖縄からTwilio UGを立ち上げるに当たり、ハンズオン資料を書きました。

今回は
Heroku + Sinatra + twilio-ruby を使って、Twilioの基本的な機能、

・電話を着信する
・音声を再生
・プッシュによる分岐
・通話を録音する
・電話をかける

を行いたいと思います。

なお、このドキュメントはTwilio公式サイトの「Ruby REST クイックスタート チュートリアル」を参考にしておりますm(__)m

また、ソースコードは rice-american/twilio-ruby-tutorial に push しております。ご参照下さいm(__)m

事前確認

このハンズオンでは、Twilioのアカウントが必要です。もし取得していない場合は、下記ブログなどを参考に、取得してください。

・新規登録ですぐ使える-クラウド電話-sms-api-twilioの新規登録
Twilio(トゥイリオ)を触ってみた
また、このハンズオンではRuby, Herokuを使用します。もしインストールされていない場合は、下記URLからダウンロードし、インストールしてください。

Ruby公式ドキュメント
・HerokuToolbelt

1. Heroku上にアプリケーションを作成する

1.1. 任意の場所にディレクトリを作成し、移動します。

※注: Windowsのコマンドプロンプトの場合、mkdirコマンドは一度に複数階層作成できないため、1つずつ作成する必要があります。

1.2. heroku loginを実行

先ほど作成したディレクトリに移動し、heroku loginを実行しましょう。

これでコマンドラインからherokuへログインできました。

1.3. gitリポジトリの用意

git initを実行し、Gitリポジトリを作成します。

続いて.gitignoreファイルを生成します。

次にgit commit -am "add .gitignore"を実行します。

※注: git add時に改行コードについて警告が出た場合は、下記のように対処してください。
warning: LF will be replaced by CRLF in {ファイル名}.
対処方法:git config --global core.autoCRLF false を実行

1.5. heroku createを実行

heroku createを実行します。この時、heroku create {アプリケーション名前} とすることで、アプリに任意の名前をつけられます。
なお、アプリケーションの名前は過去に誰にも付けられていないものでなければなりません。

今回はtwilio-ruby-agenaというアプリ名をつけます。

2. Sinatra アプリ作成

2.1 ライブラリ(sinatra, twilio-ruby)をインストール

必要なライブラリをインストールするのに、bundleを使用します。
(bundle がインストールされていない方は gem install bundle でbundleをインストールしてください。)

最初にGemfileを生成します。

生成されたGemfileを下記のように編集します。

続いてbundle install --path=vendor/bundleを実行し、ライブラリをインストールします。

ここで、一度git commitを行いましょう。

3. 電話をかけて、音声を再生してみよう

3.1 Twilioにおけるプログラミング

前提知識として、Twilioを使用するプログラミングは、Twimlを動的に生成することを目的とします。
Twimlとは、マークアップ言語で書かれた「通話や SMS を受信した時の動作を Twilio に指示するための、命令のセット」です。
Twilioは、ユーザからTwilio電話番号に対して着信すると、そのTwilio電話番号に紐付けられたTwimlのURLへアクセスします。
そして、そのTwimlに書かれた命令(音声を再生する、音声を録音するなど)を実行します。
そのため、Twimlはインターネット上からアクセスできるサーバにアップロードし、アクセスが出来るようにしてておく必要があります。
今回ははherokuを使用することで、サーバを用意することなく、Twimlを使用できる場所にアップロードでき、sinatraを使うことで、
アクセスに対してレスポンスできます。

3.2 Hello, Twilio!

Twilioプログラミングの第一歩として、音声を読み上げるプログラムを作成しましょう。

twiml-quickstart.rbというファイルに下記を記入してください。

3.3 プログラムの解説

<6行目>

動詞にはデフォルトで英語(en)が設定されているため、そのままでは日本語を再生できません。
日本語を再生する場合は、下記のように、languageオプションに’ja-jp’を指定します。

より詳細な仕様は https://jp.twilio.com/docs/api/twiml/say をご参照下さい。

3.4 ローカルでsinatraを起動してみよう

今回、herokuでsinatraを起動するため、先ほどgem installしたライブラリ、rackを使用します。
rackを起動させるため、config.ru(設定ファイル)に下記のように記入します。

キチンと動くか、 bundle exec rackup config.ruを実行して確認しましょう。

listenしているポート番号は9292と表示されているため、http://localhost:9292/hello-twilio にWebブラウザからアクセスします。

成功していればHello Twilio!が表示されていると思います。
次に、ソースコードを表示してみましょう。下記のようなTwiMLが生成されていると思います。

このTwimlは、アクセスされると”Hello Twilio!”と返答します。

3.5. herokuへデプロイする

起動していたサーバを<ctrl-c>を押して終了し、ここまでの修正をgit commitし、herokuへデプロイしましょう。

※注: Windowsの場合、pushに失敗することが有ります。その際は、下記のコマンドを実行してください。

ブラウザから https://{作成したherokuアプリ名}.herokuapp.com/hello-twilio へアクセスしてみましょう。
ローカルと同様、のTwiMLが生成されていれば成功です!

3.6.「Herllo Twilio!」を聞きに行く

TwiMLを設置できたので、早速メッセージを聞きましょう!
まずは下記URLからTwilio電話番号を取得します。

Twilio User – Account Phone Numbers Getting Started
https://jp.twilio.com/user/account/phone-numbers/getting-started

画面上の「最初のTwilio電話番号を取得」を押して、「Choose this Number」を選択します。

続いて、下記URLから取得したTwilio電話番号にVoiceURLを登録します。
これによって、この電話番号へ発信すると、VoiceURLの指し示すTwiMLを読み込みに行きます。

下記リンクから、先ほど取得したTwilio電話番号のリンクをクリックします。(図1)

Twilio User – Account Phone Numbers Incoming
https://jp.twilio.com/user/account/phone-numbers/incoming

図1: TwimlのURLを設定(1)

図1: TwimlのURLを設定(1)

すると、Twilio電話番号の設定画面へ遷移するので、画面中腹にある「Request URL」にhttps://{作成したherokuアプリ名}.herokuapp.com/hello-twilio を記入しましょう。この時、メソッドをHTTP POSTからHTTP GETへ変更しておきます。(図2)

図2:

             図2: (2) TwimlのURLを記入する

変更したら、画面下部の「保存」ボタンを押します。

設定したら、実際にTwilio電話番号へ電話をかけてみましょう!
英語で「このメッセージはアカウントをアップグレードをすると流れなくなります。何かダイヤルキーを押してください」という旨のメッセージがなれるので、何かしらのキーを押した後、「Hello, Twilio!」と音声が聞こえたら成功です!

4. プッシュによる分岐 & 通話を録音してみよう

4.1 実装

続いて、プッシュによる分岐・通話の録音機能を実装しましょう。

先ほど作成したtwiml-quickstart.rbを下記のように編集します。

4.2 プログラムの解説

<10行目>

動詞は、ユーザからの入力受付を行います。numDigits => '1’ は “1以上の整数”を意味しており、:action => '/hello-twilio/handle-gatherは”ユーザからの入力値を/hello-twilio/handle-gatherのTwiMLへ渡す”、:method => 'get'は、actionに指定したURLに対して”GETリクエストを送信する”ことを意味しています。

より詳細な仕様はhttps://jp.twilio.com/docs/api/twiml/gatherをご参照ください。

<29行目>

動詞は、ユーザの音声を録音します。:maxLength => '30'と指定することで、「最大30秒」録音できることを意味しています。maxLengthの最大値は3600秒(1時間)です。録音した音声へアクセスするためのURLは、Rubyの場合params[‘RecordingUrl’]でアクセスできます。

より詳細な仕様は https://jp.twilio.com/docs/api/twiml/record をご参照下さい。

<45行目>

動詞では、指定されたURLの音声を再生します。params[‘RecordingURL’]を指定することで、ユーザが録音した音声が再生できます。
より詳細な仕様は https://jp.twilio.com/docs/api/twiml/playをご参照下さい。

4.3 録音してみよう

先ほどのプログラムを保存し、git commitを行ったのち、git push heroku masterを行いましょう。

『3.4.「Herllo Twilio!」を聞きに行く』で取得したTwilio電話番号に発信してみましょう。
うまく、録音した自分の音声を聞くことが出来たでしょうか?

5. 発信してみよう

URLを叩いたら、自分の携帯電話に発信し、紐付けられたURLのTwimlを再生する機能を作りましょう!
先ほど編集したtwiml-quickstart.rbを下記のように編集します。

5.1 実装

5.2 プログラムの解説

電話の発信にはTwilio クライアントを使用します。
Twilioクライアントを使用するには、ユーザの使用しているアカウントを特定するため、2つのクレデンシャル「Account SID」と「Auth Token」 が必要です。
(※これらのキーの取得方法については後述します)

Rubyでは、下記のように書くことでTwilioクライアントオブジェクトを生成できます。

ここで、ENV['TWILIO_ACCOUNT_SID'], ENV['TWILIO_AUTH_TOKEN']という表記が出てきました。
これにより、それぞれ環境変数 “TWILIO_ACCOUNT_SID”, TWILIO_AUTH_TOKENが展開されます。
こうしているのは、プログラム上に直接クレデンシャルを記入した場合、Githubなどに公開した際にクレデンシャルを使われてしまう危険性があるためです。

続いて、下記のコードを解説します。

ここでは、作成したclientオブジェクトに対してオプションを設定しています。:fromには発信元の電話番号、ここでは、Twilio電話番号、:toには発信先の電話番号。ここでは、アカウント登録時に認証した電話番号を入れます。

発信先電話番号の表記は、たとえば「090-1234-5678」という電話番号の場合、「+819012345678」と入力しましょう。

:urlには、発信先で電話を受け取られた時に遷移するURLです。今回は、前章「4. プッシュによる分岐 & 通話を録音してみよう」で作成したルート、hello-twilioへ飛ばします。

また、一つ重要なポイントとして、下記のように、hello-twilioルートのメソッドがGETメソッドからPOSメソッドに変更されています。

これは、クライアントが:urlのパラメタに遷移するときにPOSTメソッドでアクセスするためです。GETメソッドのままだと404エラーとなってしまいます。

解説は以上です。続いてHerokuへデプロイしてみましょう!

5.3 「Account SID」と「Auth Token」を取得

Twilioクライアントを使用するのに必要な「Account SID」と「Auth Token」は、Twilioの自分のアカウントページから新しく生成する必要があります。まず、図3のように、アカウントページの「APIキー」をクリックします。

 

図3: APIキーをクリック

 図3: APIキーをクリック

 

遷移先で「APIキーを作成する」を押した後の画面(図4)で、
フレンドリーネーム(Twilio電話番号から先頭の+を除いたもの)を入力し、「Create API Key」を押します。

図4: フレンドリーネームを入力して鍵を作成

図4: フレンドリーネームを入力して鍵を作成

 

次に、一度だけ表示される「Auth Token」を控えておいてください。

これで、「Account SID」と「Auth Token」が取得できました!

5.3 Herokuへデプロイ

Herokuへデプロイを行う前に、Heroku上に、プログラムで使用している環境変数を定義します。

下記のコマンドに適宜パラメタを入力し、実行してください。

先ほどのプログラムを保存し、git commitを行ったのち、git push heroku masterを行いましょう。

それでは、ブラウザから https://{作成したherokuアプリ名}.herokuapp.com/hello-twilio/make-call へアクセスしてみましょう。

自分の携帯に電話がかかり、例の音声が聴こえれば成功です!

さいごに

みなさま、ハンズオンお疲れ様でした!

今回のイベントを通して、「Twilioを使ってこんな新しいサービスが作れるのではないか」、「Twilioと今自分がやっている仕事のあの部分は、Twilioを使えば効率化出来るのではないか」、など、Twilioでだいぶ夢が広がっただろうと思います。

沖縄UGでは、今後もそんな素敵API、Twilioを沖縄で広めるべく、活動していこうと思っております。
今回参加してくださった皆様も、機会があれば、またお会いしましょう!

以上!あげなかずと@新入社員でした。m(__)m

この記事のライター

みなさまからのご連絡をお待ちしております。

CONTACT US