Twilio Client 1.6 でメリークリスマス

ども、@kimihom です。

f:id:cevid_cpp:20181216135254j:plain

この記事は、Twilio Advent Calendar 23 日目の記事です。

Twilio Client 1.6 での変化

最近、Twilio Client はバージョンの変化が激しいアップデートが続いている。今年の8月にメジャーアップデートである Twilio Client 1.5 がリリースされたと思ったら、同8月にまさかの Twilio Client 1.6 がリリースされた。Twilio Client 1.5 は単にイベントの書き方が変わったくらいの変化なので、最新の Twilio Client による恩恵を受けたいのなら Twilio Client 1.6 へアップデートする流れになるだろう。

Twilio Client JavaScript SDK Changelog - Twilio

Twilio Client を使っているほとんどの方は Twilio Client 1.4 を使っていたと思うので、そこから変わった Twilio Client 新機能(プレゼント)について情報共有できればと思う。

イベントの書き方が変わった (Twilio Client 1.5)

今までは Twilio.Device のメソッドとして公開されていたイベント定義だが、on を使った EventEmitter 風な書き方に変わった。

// before
Device.cancel(handler)
Device.connect(handler)
Device.disconnect(handler)
Device.error(handler)
Device.incoming(handler)
Device.offline(handler)
Device.ready(handler)

// after
Device.on('cancel', handler)
Device.on('connect', handler)
Device.on('disconnect', handler)
Device.on('error', handler)
Device.on('incoming', handler)
Device.on('offline', handler)
Device.on('ready', handler)

また、おそらく 1.5 からのアップデートからだと思うんだけど、Twilio.Device のインスタンス変数にイベントが定義できるようになった。これによってグローバルなイベントとして定義しなくてよくなったため、より安全なコードが書けるようになったと思う。

const device = new Twilio.Device(token, options);
device.on('ready', handler)

通話中の着信を受け取れるようになった

今までは通話中に着信を受けたとしても、通話切断してその着信を受け取ることができなかった。Twilio Client 1.6 からは、allowIncomingWhileBusy オプションを true にすることで、通話中に着信が来たとしても通話を切断して新たな着信を受け取れるようになっている。なお、この場合着信時の着信音は流れないので注意だ。

Twilio.Device の初期化と、disconnect や cancel 次のイベント処理についてのサンプルを以下に記す。

const twilioDevice = new Twilio.Device(token, {
      closeProtection: "通話中です。通話が終了しますが、移動しますか？",
      allowIncomingWhileBusy: true,
      debug: true,
      region: "jp1"
    });

// disconnect や cancel 時
var connection = twilioDevice.activeConnection();
if (connection) {
  // 他に着信が来ている
} else {
  // 通話終了
}

あんまりにもこの "通話中に着信が来て、それを受け取りたい" ってケースが頻発するのなら、<Enqueue> を通じて発信者の通話を音楽を流して待ってもらうようなよくある処理を実装する方が適切である場合が多い。allowIncomingWhileBusyの利用を見極めよう。

TwiML の Dial Client にパラメータを渡せるようになった

これ！便利。Twilio Cleint 1.6 をアップデートすべき一番のモチベーションになりうる機能だ。

今までは Twilio Client へ Dial する TwiML を書くときは単に Client アイデンティティを指定するだけだったが、そこにパラメータを渡せるようになった。TwiML にIdentity に加えて Parameter ってのが付与できるようになっている。なおこの最新 TwiML 書けるようにするには各 Twilio SDK を最新にアップデートする必要がある。 Twilio Ruby の場合は 5.15.0 でこの記法が提供されている。

// before
  <Dial>
    <Client>alice</Client>
  </Dial>

// after
  <Dial>
    <Client>
      <Identity>alice</Identity>
      <Parameter name="foo" value="bar"/>
      <Parameter name="baz" value="123"/>
    </Client>
  </Dial>

このように TwiML を書いておくと、Twilio Client 側でパラメータを JavaScript で取ってこれる。

twilioDevice.on('incoming', function(connection) {
  connection.customParameters.get('foo')  // -> bar
});

カスタムパラメータの利用サンプル

Twilio Client の実装で必ず出てくるハードルの一つである "保留" の実装を考えてみよう。これを実現するには、Client のコールとはまた別の親コールをアップデートする必要が出てくる。

親コール 03-1111-1111 -> Twilio 050
子コール Twilio 050 -> Twilio Client

保留を実現するにはこの親コールをアップデートして、Queue に入れる必要がある。そのアップデートに必要なのが、CallSid である。親の CallSid をどうやって取ってくるかといえば、今までは Twilio API を呼んで取得したり何かしらキャッシュで保存したりする必要があり、そのためだけに twilioDevice.on('incoming')着信の度に Sid を取得する必要があった。

もうそんなことをする必要はない。このカスタムパラメータを使えばね！

    <Client>
      <Identity>alice</Identity>
      <Parameter name="parentCallSid" value="CAaaaaaaa11111111"/>
    </Client>

保留するときはこの CallSid をアップデートすればいいだけだ。

call = @client.calls('CAaaaaaaa11111111')
              .update(method: 'POST', url: 'http://demo.twilio.com/docs/voice.xml')

また、それ以外にも着信時に相手の電話番号を取得したいとは誰もが思うはずだろう。これも簡単に実装できる。

    <Client>
      <Identity>alice</Identity>
      <Parameter name="from" value="#{params[:From]}"/>
    </Client>

発信時のカスタムパラメータ

発信時はどうなるのって話になると思うけど、これは Device.connect() のパラメータを取ってこれるようになっている。発信時にもこのカスタムパラメータは便利だ。

let params = {
  "foo": "bar"
};
twilioDevice.connect(params);

// twilioDevice.on('connect')
connection.customParameters.get('foo') // -> bar

ちなみにこのカスタムパラメータだが、TwiML に<Client> と <Number> を組み合わせるとそのカスタムパラメータが取ってこれない問題がある。既に US Twilio へ本件を報告済みなので、そのうち対応してくれるだろう。

Twilio Client アップデートはお早めに

Twilio は Chrome の仕様変更に伴い Twilio Client のアップデートをアナウンスしている。

Breaking Changes in Twilio Client JavaScript SDKs (December 2018) – Twilio Support

概要はこんな感じ(最終的な確認は各自行って欲しい)

Chrome がそのうち WebRTC Unified Plan ってのに変わるが、Client の一部の機能は Plan B の実装に依存している機能がある。
例えば通話中にヘッドセットを抜いてしまった場合、Client はデフォルトのPCマイクで通話を繋げようとするけど、それが止まっちゃう?
2019の春には PlanBサポートを打ち切る。
Chrome 72 から適用予定

もうすでに Chrome 71 がリリースされている。次のバージョンから適用予定ってことで、まだ古い Twilio Client 使ってる場合は今すぐくらいのレベルで早急に対応する必要がある。

終わりに

今回は最新の Twilio Client 情報について記した。

今年 Twilio 本社に行って中の方とお話ししたところ、「常に Twilio Client は音質や安定性のアップデート改善を行っており、最新を使い続けて欲しい」というメッセージをいただいた。にしてはバグがよく発生するよねと釘を刺しておいたが、「バグも定期的に直してるよ！」ってことで最終的に信じるか信じないか、あなたがアップデートのたびに熱心にテストができるかどうかにかかってくるだろう。

そんなこんなでメリークリスマス！

Twilio Client 1.6 で素敵なクリスマスを。( Twilio Client と素敵なクリスマスを過ごせるエンジニアが何人いることか！)