Twilio Voice JavaScript SDKを使って電話の発信、着信をしてみる

はじめに

Twilio Programmable Voiceでは、APIを使ったり、SDKを使ったりして、下記のように電話の発信、着信などを行うことができます。

• 発信の場合

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.calls
      .create({
         twiml: '<Response><Say>Ahoy, World!</Say></Response>',
         to: '+14155551212',
         from: '+15017122661'
       })
      .then(call => console.log(call.sid));

• 着信の場合

const express = require('express');
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const app = express();

// Create a route that will handle Twilio webhook requests, sent as an
// HTTP POST to /voice in our application
app.post('/voice', (request, response) => {
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();
  twiml.say({ voice: 'alice' }, 'hello world!');

  // Render the response as XML in reply to the webhook request
  response.type('text/xml');
  response.send(twiml.toString());
});

// Create an HTTP server and listen for requests on port 3000
app.listen(3000, () => {
  console.log(
    'Now listening on port 3000. ' +
    'Be sure to restart when you make code changes!'
  );
});

と言いましても、実際に電話応対で使うには下記のことなどをしないといけません。

• 発信して、発信先が応答したらどうするか？
  • 発信先と発信元で通話を確立させる
• 着信したら、どうするのか？
  • 対応できる担当者に着信させる

この場合、ソフトフォンと呼ばれる電話操作を行うための画面を作る必要があります。

Twilioは各種APIが提供されているのでAPIを呼び出すことができれば自由に作ることができますが、SDKも提供されております（SDKを使うと開発しやすいです）。

• iOS SDK
• Android SDK
• JavaScrip SDK

ウェブアプリの場合はJavaScript SDKを使うことになります。SDKは使いやすいですが、アプリケーションをイチから作成するのは大変だったりもします。 しかし、ありがたいことにTwilio社はサンプルアプリケーションを公開しておりますので、それを参考に開発するのが良いと思います。

サンプルアプリケーションについて

こちらを使用します。

https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node

電話を発信または着信するまでの流れ

こちらの記事にある画像を使って説明します。

https://www.twilio.com/docs/voice/sdks/javascript

発信する場合

物理的な電話機（ハードフォン）を使って発信する場合は、電話機に発信先の電話番号を入力して、そこから発信することになります。 相手が応答すれば、その結果を電話機が受け取って通話が確立します。

Twilioの場合は、電話機の代わりにTwilioに発信の要求をして、Twilioから発信することになります（図の真ん中のアイコンがTwilioです）。 発信して、相手が応答したらText To Speech（TTS）のメッセージを流して終わりならば、発信とTTS処理を記載したソースコードを書けば終わりです。

そうではなく、相手が応答したら通話をしたいという場合は、Twilioに発信の要求をするソースコードを書くだけでは終わりません。 発信したら、その結果をTwilioが返してくるので、それを受けてどうするか？という処理を書かないといけません。 具体的には発信が確立したイベント（acceptイベント）や切断されたイベント（disconnectイベント）などをフックして必要な処理を書いていきます。

これは図の Your Web Application + Twilio JS SDK と Twilio との処理になります。

着信する場合

物理的な電話機（ハードフォン）を使って着信する場合は、そこに電話がかかってきたら応答するなり、拒否するなりすることになります。

Twilioの場合は、まずTwilioに電話がかかってきます。そのことをTwilioがイベントで教えてくれます。 着信したらText To Speech（TTS）のメッセージを流して終わりならば、着信イベントをフックする処理とTTS処理を記載したソースコードを書けば終わりです。

そうではなく、着信したら応答として通話を確立したいという場合は、Twilioからの着信イベントを受けて、どのような処理をするかをTwilioに返す必要があります。 それを行うことでアプリケーション（Your Web Application + Twilio JS SDK）に着信させたり、電話番号に転送したりすることができます。

図に記載されている説明を補足しますと、最初にTwilioが着信を受けて、着信イベントを通知してくれます。 このイベントは具体的にはWebhookです。そのため、これを受けるためのウェブアプリケーションが必要です。 それが図にある Your Backend です。ここで着信イベントを受けたら、そのあとどうするかをTwilioに返します。 返し方として、TwiMLというTwilioへ指示するためのマークアップ言語を使うと、いろいろなことができます。

例えば着信だと、以下のようなことをします。

• 携帯電話などに転送する
  • この場合はTwilioから携帯に転送されるので、転送された電話に応答してからは、Twilioの管理を離れます。
• SIPクライアントに着信させる
  • TwilioにはSIPクライアントを登録して（レジストして）発信、着信を行える機能がありますので、ある特定のSIPクライアントに着信させることができます。この場合、具体的にはSIPクライアントに発信する処理を行います。
• アプリケーションに着信させる
  • 今回話題にする内容ですが、電話応対アプリなどソフトフォンに着信させる方法です。これは具体的にはデバイス（Device）としてTwilioに登録されている（レジストされている）ものに対して発信する処理を行います。図では Your Web Application + Twilio JS SDK が電話応対アプリなどソフトフォンに該当するものなのですが、このアプリを最初にデバイス（Device）としてTwilioに登録（レジスト）します。それにより、Twilioからデバイスに発信することができ、つまりは着信を受けることができるのです。

ちなみに言い方を変えると、Twilioは下記の3つのいずれかに発信することができます。

• 電話番号（携帯など）
• SIPクライアント（TwilioにレジストされているSIPクライアント）
• デバイス（Twilioにレジストされているデバイス）

発信APIの説明文を引用すると、こうなります。

The phone number, SIP address, or client identifier to call.

さて、今回は前置きが長くなりましたが、このあとはサンプルアプリケーションをセットアップして実際に動かしてみます。

作業環境の準備

node.js

version 14.0以上が必要です。直接インストールするか、nvmを使ってインストールしておきます。

• nvm
  • https://github.com/nvm-sh/nvm

ngrok

今回はローカル環境のソースを動かすのですが、インターネット経由でのアクセスが必要なため使用します。

ngrokのサイトでサインアップし、インストールします。

• ngrok
  • https://ngrok.com/

ブラウザ

WebRTCに対応しているブラウザが必要です。Google Chrome や Mozilla Firefoxが候補になります。

サンプルアプリケーションのセットアップ

TwiML アプリケーションの作成

Twilioコンソールのメニューから Programmable Voice > TwiML > TwiML Apps を選択します。

Create new TwiML App ボタンを押します。

Friendly Name に任意のものを入力して、他の項目はあとで設定しますので Create ボタンを押します。

作成した TwiML Appを選択して TwiML App SID を控えておきます。

電話番号の購入

Twilioコンソールのメニューから Phone Numbers を選択します。

Active Numbers を選択して画面上の Buy a Number を選択します。

番号を購入したい国を Country 欄で選択します。 Search ボタンを選択します。

購入可能な電話番号が一覧に表示されます。購入したい番号の行にある Buy ボタンを選択します。

確認画面が表示されますので、 Next ボタンを選択します。

番号の利用者が Business なのか Indivisual なのか選択します。選択したら Next ボタンを選択します。

日本の電話番号を購入する場合は、 本人情報をTwilio上に登録し、Twilio社のレビュープロセスを完了させておく必要があります。（参考）https://github.com/neri78/Twilio-HandsOn-101-JP/blob/master/docs/00-Misc/00-00-IdentitySid.md

承認を得ている住所情報を選択して、 Buy ボタンを選択します。

API Keyの作成

Twilioコンソールのメニューから Console Dashboard > API Keys を選択します。

+ ボタンを押します。

Friendly Name に任意のものを入力して、 Create API Key ボタンを押します。

画面に表示されている SID と SECRET を控えておきます。特にメッセージが出ている通り SECRET は二度と確認することができません。

SID と SECRET を控えたら、 Got it! I Have・・・ のところにチェックをつけます。チェックをつけると Done ボタンが押せるようになりますので、押します。

API Keyが作成されました。

サンプルアプリケーションのソースコードをダウンロード

下記のリポジトリからダウンロードします。

git clone https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node.git

依存するライブラリのインストール

プロジェクトディレクトリに移動します。

cd voice-javascript-sdk-quickstart-node

下記を実行します。

npm install

node_modulesにある twilio.min.js を public ディレクトリにコピー

Twilio Voice ClientのSDKファイルを下記コマンドでコピーします。

cp node_modules/@twilio/voice-sdk/dist/twilio.min.js public

これは、サンプルのソフトフォン画面である public/index.html で読み込むためです。

・・略・・
    <script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
    <script type="text/javascript" src="twilio.min.js"></script>
    <script src="quickstart.js"></script>
  </body>
</html>

envファイルの編集

envファイルを編集するため、デフォルトの .env.example から .env を作成します。

cp .env.example .env

下記の値を設定します。

設定項目	値
TWILIO_ACCOUNT_SID	Twilioコンソールのダッシュボード画面で確認できます。
TWILIO_TWIML_APP_SID	作成したTwiml アプリケーションのSIDを設定します。
TWILIO_CALLER_ID	購入した電話番号を E.164形式で設定します。（例）+815012345678
TWILIO_API_KEY	作成したAPI KEYを設定します。
TWILIO_API_SECRET	作成したAPI KEYを設定します。

サンプルアプリケーションの起動

下記コマンドでサンプルアプリケーションを起動させます。

npm start

起動したらngrokも起動させます。

ngrok http 3000

TwiML アプリケーションの設定

Twilioコンソールのメニューから Programmable Voice > TwiML > TwiML Apps を選択します。さきほど作成したアプリケーションを選択します。

Voice Configuration の下記を設定します。設定したら保存します。

電話番号の設定

Twilioコンソールのメニューから Phone Numbers > Manage Numbers > Active Numbers を選択します。

Voice & Fax の下記を設定します。設定したら保存します。

サンプルアプリケーションの動作確認

https://{{ngrokのドメイン}}/ にブラウザからアクセスします。

このような画面が出ますので、 Start up the Device ボタンを押します。

これをすると、サンプルアプリ側でアクセストークンを取得したり、このサンプルアプリをTwilioにデバイスとしてレジストしたりしてます。 Event Log欄をみると、どんなことをしているかわかります（私はテキストエリアのサイズを大きく変えてます）。

発信（発信して、拒否する）

まずは発信して、発信先が応答しない（拒否する）場合を見てみます。

電話がかかってきたら拒否します。すると、Event Log欄に発信が切断されたことを意味するログが出ます。この一連のやりとりが、サンプルアプリとTwilioの間で行われております。

発信（発信して、応答する）

今度は発信して、発信先が応答する場合を見てみます。

Make a Callにあるテキストボックスに発信先の電話番号を入力します。電話番号はE.164形式で入力してください。入力したら Call ボタンを押します。 そうすると、Event Log欄に発信していることを意味するログが出ます。

応答します。切断していないので、切断のログは出ません。

通話を終了します。切断されたので、切断のログが出ます。

着信（着信して、拒否する）

今度はTwilioの電話番号に発信して、着信させてみます。 Event Log欄に着信イベントを受けていることが出ております。

拒否するので、 Reject ボタンを押します。

拒否したことがEvent Log欄に出ております。

着信（着信して、応答する）

再度Twilioの電話番号に発信して、着信させてみます。 着信したことがEvent Log欄に出ております。

今度は応答しますので、 Accept ボタンを押します。応答したことがEvent Log欄に出ております。

通話を終了させます。 Hangup ボタンを押します。切断したことがEvent Log欄に出ております。

デバイス間の発信

今度はサンプルアプリ同士（デバイス同士）で発信、着信させてみます。 これをするために2台の端末でそれぞれサンプルアプリを起動させます。

このサンプルアプリでは、毎回ランダムでデバイス名が決定されます。

発信する場合は、デバイス名を入れて発信すれば良いので、片方のをコピペして貼り付けます。 Event Log欄にデバイス名に向けて発信しているログが出ます。

応答、切断は電話番号の場合と同様です。

このデバイス同士の通話は、アプリ間の通話や、slack callみたいなものをイメージしていただくとわかりやすいかと思います。

おわりに

サンプルアプリの処理内容やProgrammable Voice JavaScript SDKについても記載していきたいのですが、長くなりましたので別の記事にしたいと思います。

関連情報

• Programmable Voice JavaScript SDK
  • https://www.twilio.com/docs/voice/sdks/javascript
• Programmable Voice JavaScript SDK API Reference
  • https://twilio.github.io/twilio-voice.js/modules/voice.html
• TwiML Applications
  • https://www.twilio.com/docs/usage/api/applications
• Twilio Voice JavaScript SDK Quickstart for Node.js
  • https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node