This article is a Private article. Only a writer and users who know the URL can access it.
Please change open range to public in publish setting if you want to share this article with other users.

More than 5 years have passed since last update.

Twilioハンズオン Vol.2

twilio

Last updated at 2016-07-14Posted at 2016-07-10

1 / 38

本日の資料

以下にアップされています（限定公開URL）
http://goo.gl/q2HXW6

Vol.2の目的

音声通話のノウハウを習得しよう

コール（呼）とは何かを理解します
キューやカンファレンスなどの機能を理解します
コールがデザインできるようになります

参考

Vol.1 Twilioのことをよく知ろう（終了）
Vol.3 TwilioベースにクラウドPBXを作ろう

プロモーションアカウントについて

トライアルアカウントではありません
一定額のポイントがチャージされています
利用規約に同意していただく必要があります
ハンズオン終了後も使い続けられます
メールアドレスとパスワードを変更してください
vol.3でも引き続き使います

CPIサーバーアカウントについて

SSH秘密鍵のセットアップが必要です
各自の仮想環境が提供されています
ユーザ名、ドメイン名を忘れないようにしてください
８月末まで使うことができます
vol.3でも引き続き使います

アジェンダ

コール（呼）の基本
コールの状態を変更する
コールログ
キュー
カンファレンス
コールをデザインする

自己紹介

髙橋克己（たかはしかつみ）

（株）KDDIウェブコミュニケーションズ
Twilio事業部　ソリューションアーキテクト

katsumi.takahashi@kddi-web.com

CPIサーバーのセットアップ

秘密鍵のダウンロード（ダウンロード先は講師の指示に従ってください）
秘密鍵のセットアップ http://goo.gl/64pg0F
SSH接続の確認

コール（呼）の基本

Twilioにおける通話の単位
状態を持つ
コール単位にログが記録される

コールの生成方法

RestAPIのCalls.POSTで作成する

php

<?php
require_once('./twilio-php/Services/Twilio.php');

$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create(
"発信元番号", "発信先番号", 
"http://demo.twilio.com/docs/voice.xml", array());
echo $call->sid;

<Dial>動詞で生成する（転送する）

TwiML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="発信者番号">
    <Number url="http://demo.twilio.com/docs/voice.xml">
      発信先番号
    </Number>
  </Dial>
</Response>

コールの状態

コールには以下の状態が存在します
queued: Twilioの発信キューに入っている状態
initiated: キャリアに向けて発信作業中
ringing: 相手先を呼出中
in-progress: 相手が応答している状態
completed: 通話が終了している状態

コールの状態を取得する

statusCallbackというWebHookを利用
取得したいイベント（Initiated/Ringing/Answed/Completed）を指定
Completedイベント以外は有料（0.015円/イベント）
statusCallbackを持つもの
- <Dial><Number>
- <Dial><Client>
- <Dial><Conference>
- <Dial><Sip>
- <Sms>
- RestAPIのCalls.POST
- RestAPIのCalls.CallSid.POST

コールの結果

コールのCallStatusパラメータ
<Dial>のactionUrlで取得
statusCallbackのcompletedイベントで取得
代表的なコールの結果には以下の5つがあります。
- completed: 相手が応答し、通話が正常に終了
- busy: 相手からビジー信号を受信
- failed: 通話を接続できませんでした
- no-answer: 相手が応答せず、通話が終了
- canceled: queued または ringing 中に、通話がキャンセル

実習１（statusCallback）

statusCallbackがどのタイミングで発行されるかを確認してみましょう。

サーバーにSSHでログインします。
実習の準備をします。

% cd
% git clone https://github.com/twilio/twilio-php.git
% git clone https://github.com/twilioforkwc/hands_on_2016_vol2.git
% cp hands_on_2016_vol2/practice001/statusCallback.php ./html/
% chmod 705 html/statusCallback.php
% cp hands_on_2016_vol2/status.txt ./

~/html/statusCallback.php

#!/usr/local/bin/php-cgi-7.0
<?php
  $param = $_POST["CallStatus"] . "\n";
  $file = '../status.txt';
  file_put_contents($file, $param, FILE_APPEND);
?>
<!DOCTYPE html>
<html><body>OK</body></html>

status.txtをリアルタイムで監視します。

% cd
% tail -f status.txt

次に、管理コンソールから次の作業を行います。

１．TwiML Binsで以下のTwiMLを作ります。

TwiML

<Response>
  <Dial callerId="購入済み番号">
    <Number 
statusCallbackEvent="initiated ringing answered completed" 
statusCallback="http://twilio:twilio@ドメイン名.secure.ne.jp/statusCallback.php" 
statusCallbackMethod="POST">ご自分の電話番号</Number>
  </Dial>
</Response>

２．TwiML Appsを作成します。

上で作成したTwiML BinsのURLを呼び出すTwiML Appsを適当な名前で作成します。

３．テスト

TwiML Appsを保存して、再度開くと、管理コンソール上から発信テストができます。
サーバー上のstatus.txtに、statusCallbackEventで指定したタイミングでWebHookが来ることを確認します。

コールの状態を変更する

通話中のコールに別のTwiMLを実行する
RestAPI経由でコールを制御する
Calls.CallSid.POST
利用シーン
- 通話中の呼を強制切断
- 通話中の呼に割り込み

実習２（コールの強制終了）

通話中のコールを強制的に切断してみます。

050番号に着信したら、<Play>動詞で音を再生
同時に、非同期で10秒待ってから切断するRestAPIを実行

手順
1. サーバーにSSHでログインします。
2. 以下のコマンドで準備をします。

% cd
% cp hands_on_2016_vol2/practice002/*.php ./html/
% chmod 705 html/*.php
% vi html/callDisconnect.php

$sidと$tokenに、ご自分のAccountSidとAuthTokenを記入します。
:wq で保存

実習で利用するのは以下の２つのphp

playMusic.php

#!/usr/local/bin/php-cgi-7.0
<?php
    header("content-type: text/xml");
    echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
    $callSid = $_POST["CallSid"];
    exec("nohup php-7.0 -c '' 'callDisconnect.php' $callSid > /dev/null &");
?>
<Response>
    <Play loop="0">https://api.twilio.com/cowbell.mp3</Play>
</Response>

callDisconnect.php

#!/usr/local/bin/php-cgi-7.0
<?php
  require_once('../twilio-php/Services/Twilio.php');
  # Todo: Replace XXX... to your AccountSID and token
  $sid = "ACXXXXXXXXXXXX";
  $token = "XXXXXXXXXXXXXXX";
  $client = new Services_Twilio($sid, $token);
  sleep(10);
  $callSid = $argv[1];
  $call = $client->account->calls->get($callSid);
  $call->hangup();
?>

3.着信URLを設定する

保有している050番号に着信WebHookの設定を行います。
http://twilio:twilio@ドメイン名.secure.ne.jp/playMusic.php

4.テスト

050番号に電話をかけると、カウベルの音がなり、10秒経つと電話が強制的に切れることを確認します。

コールログ

コールを記録しているログ
ログは削除しないかぎり永久に残る
削除するにはRestAPI（1件ずつ）
課金情報の更新には少し時間が必要

コールログの構成

コールログのプロパティ
- https://jp.twilio.com/docs/api/rest/call#instance-properties
親コールと子コール

コールログを取得する

コンソールからCSV形式でダウンロード
- 抽出できる項目（Sid,AccountSid,StartTime,EndTime,Duration,From,To,Direction,Status,ApiVersion,Price,PriceUnit）
RestAPI経由でダウンロード
- すべての項目（ドキュメントに書かれていない項目も含めて）が取得可能

ログサンプル

{ sid: 'CAf3f2e82e5b414881be5090e4ddb69dc2',
  date_created: 'Sat, 25 Jun 2016 10:51:37 +0000',
  date_updated: 'Sat, 25 Jun 2016 10:52:09 +0000',
  parent_call_sid: 'CA4b793333626b46e8ca0451a831baa727',
  account_sid: 'AC16fbca5fa1ee7376ac748c2e737f3547',
  to: '+81904532XXXX',
  to_formatted: '+81904532XXXX',
  from: '+81503188XXXX',
  from_formatted: '+81503188XXXX',
  phone_number_sid: 'PN226b1dca9d40f7a290bed7592e1eca75',
  status: 'completed',
  start_time: 'Sat, 25 Jun 2016 10:51:48 +0000',
  end_time: 'Sat, 25 Jun 2016 10:52:09 +0000',
  duration: '21',
  price: '-16.20000',
  price_unit: 'JPY',
  direction: 'outbound-dial',
  answered_by: null,
  api_version: '2010-04-01',
  annotation: null,
  forwarded_from: '0503188XXXX',
  group_sid: null,
  caller_name: null,
  uri: '/2010-04-01/Accounts/AC**********/Calls/CAf3f2e82e5b414881be5090e4ddb69dc2.json',
  subresource_uris:
   { notifications: '/2010-04-01/Accounts/AC**********/Calls/CAf3f2e82e5b414881be5090e4ddb69dc2/Notifications.json',
     recordings: '/2010-04-01/Accounts/AC**********/Calls/CAf3f2e82e5b414881be5090e4ddb69dc2/Recordings.json' },
  dateCreated: Sat Jun 25 2016 19:51:37 GMT+0900 (JST),
  dateUpdated: Sat Jun 25 2016 19:52:09 GMT+0900 (JST),
  parentCallSid: 'CA4b793333626b46e8ca0451a831baa727',
  accountSid: 'AC**********',
  toFormatted: '+81904532XXXX',
  fromFormatted: '+81503188XXXX',
  phoneNumberSid: 'PN226b1dca9d40f7a290bed7592e1eca75',
  startTime: Sat Jun 25 2016 19:51:48 GMT+0900 (JST),
  endTime: Sat Jun 25 2016 19:52:09 GMT+0900 (JST),
  priceUnit: 'JPY',
  answeredBy: null,
  apiVersion: '2010-04-01',
  forwardedFrom: '0503188XXXX',
  groupSid: null,
  callerName: null,
  subresourceUris:
   { notifications: '/2010-04-01/Accounts/AC**********/Calls/CAf3f2e82e5b414881be5090e4ddb69dc2/Notifications.json',
     recordings: '/2010-04-01/Accounts/AC**********/Calls/CAf3f2e82e5b414881be5090e4ddb69dc2/Recordings.json' } }

キュー

キューとは

コールを一時的に待機させておく領域
キューの利用料は無料
待機呼には上限あり（初期値は100、Maxで1,000）
待機呼はメンバーとして管理
平均待ち時間や待機呼の数を取得可能

キューのしくみ

<Enqueue>動詞でキューに入れます。
<Dial>でキューから取り出します（FIFO）。
<Leave>動詞でキューを<Enqueue>の直後に戻します。

キューに入れる

<Enqueue>動詞でキューに入る
キュー名を指定可能（なければ自動作成）
WaitUrlでキューに入った時の動作を定義可能
WaitUrlで指定できるのは、<Play>, <Say>, <Pause>, <Hangup>, <Redirect>, <Leave>, <Gather>
WaitUrlはキューにいる間は繰り返し呼ばれる（コール単位）

WaitUrlで状態を把握する

WaitUrlで渡されるパラメータ
- QueuePosition: 現在のキューの位置（1〜）
- QueueSid: キューのSid
- QueueTime: キューに入っている時間（秒）
- AveQueueTime: キューの平均待ち時間（秒）
- CurrentQueueSize: キューに入っている通話の数

キューから取り出す

<Dial><Queue>
- キューが空の場合、次の人がキューに入るのを待つか、タイムアウト(最大60秒)になるのを待ちます。
<Leave>
- <Enqueue>動詞の次の動詞に制御を戻します。
RestAPI
- Queues.QueueSid.Members.CallSid
- Queues.QueueSid.Members.Front
キューから外れた理由は、<Enqueue>動詞のactionで取得できます。
- bridged: 通話がキューから外れ、相手にブリッジされた
- bridging-in-progress: 通話がキューから外れ、相手と通話中
- error: エラー（waitUrlのエラーも含む）
- hangup: 待機中の発信者が切断
- leave: <Leave>動詞によりキューを外れた
- redirected: RestAPIによりリダイレクトされた
- redirected-from-bridged:
- queue-full: キューがいっぱいで入れなかった
- system-error: Twilio上でエラーが発生した

メンバーを管理する

RestAPIでメンバーの一覧を取得する
RestAPIでメンバーを取り出す

実習３（キューイング）

050-XXXX-XXXXに、キューに格納する処理を定義します（ただし、TwiML Appsを使うので、電話番号を用意する必要はありません）。
キューに入った通話には、enqueue.phpが繰り返し呼ばれ、現在の待ち位置が応答されます。
050-YYYY-YYYYに、キューから取り出す処理を定義します。

手順1. 以下のTwiML BinsをEnqueue という名前で作成します。

TwiML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Enqueue 
waitUrl="http://twilio:twilio@ドメイン名.secure.ne.jp/enqueue.php">
    testQueue
  </Enqueue>
</Response>

手順2. 以下のTwiML BinsをDequeueという名前で作成します。

TwiML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say language="ja-JP" voice="alice">
お待ちどうさまでした。お繋ぎいたします。</Say>
</Response>

※作成したTwiML BinsのURLをコピーしておきます。

手順3. 以下のTwiML BinsをDialQueueという名前で作成します。

TwiML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="購入済み050番号">
    <Queue url="手順2.で作成したTwiML BinsのURL">
testQueue</Queue>
  </Dial>
</Response>

手順4. サーバーに接続し、enqueue.phpを準備します。

% cd
% cp hands_on_2016_vol2/practice003/enqueue.php ./html/
% chmod 705 html/enqueue.php

enqueue.php

#!/usr/local/bin/php-cgi-7.0
<?php
  header("content-type: text/xml");
  echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";

  $queuePosition = $_POST["QueuePosition"];
  $talk = "お待たせしております。現在のあなたの順番は" . $queuePosition . "番目です。";
?>
<Response>
  <Say language="ja-JP" voice="alice">
    <?php
      echo($talk);
    ?>
  </Say>
</Response>

手順5. 050番号の着信設定を行います。

購入した電話番号の着信設定で、手順3.で作成したTwiML BinsのURLを設定します。

テスト

適当な名前でTwiML Appsを新規で作成し、手順1.で作成したTwiML BinsのURLを指定します。
作成したTwiML Appsを開き、「発信」を押します。
通話がキューに入り、現在の待ち位置が音声として流れます。
手順5.で設定した050番号に電話をかけ、キューに入っているコールがブリッジされることを確認します。

カンファレンス

2名以上の複数のユーザで会話をする機能
BasicカンファレンスとGlobalカンファレンスの2種類が存在
- Basic: 無料、最大40名、US経由で通話
- Global: 有料（東京0.6円/分/参加者）、最大250名、JP経由で通話
- 切り替えはアカウント単位
電話会議、コールセンターのモニターなどで利用

カンファレンスへの参加方法

<Dial><Conference>
RestAPIから直接カンファレンスには参加できない
主要な属性
- muted: 参加者の声を拾わない
- beep: 参加者が参加、退出した際に音をならすか
- startConferenceOnEnter: 参加した時点でカンファレンスが始まる
- endConferenceOnExit: 退出した時点でカンファレンスが終了する
- waitUrl: カンファレンスが始まる前に流す音楽のURL
- maxParticipants: 参加者の上限を設定
- statusCallback: カンファレンスに関するイベント（start/end/join/leave/mute/hold）が発生した際にWebHook

参加者の操作

RestAPIで参加者リストを取得
- Conferences/{ConferenceSid}/Participants
- 取得時点の参加者しか取得できない
参加者をホールドする
- 特定の参加者に音楽を流して、一時的に会議から外す
参加者のミュートする
- 特定の参加者のマイクをオフにする

コールをデザインする

TwiML動詞のフローを理解する
図にして設計することが重要
同期、非同期をイメージしながらデザイン
電話特有の動作（話中、発信キャンセル、応答なし）を考慮

コールダイアログ

コールダイアグラムの紹介（https://goo.gl/fiOroP）
url: 相手が応答したときにHookされます
action: 処理が終了した時にHookされます
statusCallback: イベント毎に非同期でHookされます
青い四角がRestAPI、グレーがTwiML、オレンジは着信