この記事を読むと分かること

• プロダクションで使うTaskrouterガチ構成が見れる
• WorkflowのルーティングのJSONファイルを公開するので、ドキュメントとは違うユースケースのルーティングを見れる

こんにちは、@24guchiaです。

Twilio Advent Calendar 2017 の13日目です。

Taskrouterと1ヶ月ほど格闘し、得られた情報を社外秘のみ取り除いて、全部公開します。

Twilioドキュメント以外で、Taskrouterの記事が少なくいろいろと苦戦したので、

今後Taskrouter使う人の参考になれば良いなーと思います。

弊社の受電の仕様

受電の仕様は下記です。

• 受電した番号でDB検索し、担当者が存在するか確認する
• 担当者が存在する場合、担当者の電話機を鳴らす
• 担当者が電話を取らないか不在の場合、担当者と同じ部署の人の電話機をランダムで鳴らす
• 誰も受電出来ない場合、機械音声で担当できるものがいない旨を通知

企業側としては受電担当部門が不要になり、

お客様としては余計な取次による待ち時間が減らせることができます。

CTIの効果を感じられる仕組みだと思います。

Taskrouterに落とし込むとどうなるか

Workerの設定

Workerは電話機を使う人、一人に対して1Workerを必ず発行します。

独自で持たせている属性はメールアドレスと部署IDだけです。

FriendlyNameはemailからピリオドをアンダースコアにしただけのものを使用しています。

例：

{"email":"hiroshi.abe@example.com,"contact_uri":"client:hiroshi_abe","department_id":1}

Activityの設定

デフォルトで生成されるものをそのまま使っています。

Taskqueueの設定

TARGET WORKER EXPRESSIONに1==1を入れているだけの

キューをひとつだけ使用しています。Workflowだけでなんとかしています。

Workflowの設定

設定しているJSONファイルは下記。

これだけだと、何も出来ないので好きに使ってください。

{
  "task_routing": {
    "filters": [
      {
        "targets": [
          {
            "queue": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "expression": "task.email==worker.email",
            "priority": "1",
            "timeout": "10"
          },
          {
            "queue": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "expression": "task.department_id==worker.department_id",
            "priority": "2"
          }
        ],
        "filter_friendly_name": "email",
        "expression": "filter=='email'"
      },
      {
        "targets": [
          {
            "queue": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "expression": "worker.department_id IN task.department_id",
            "priority": "3"
          }
        ],
        "filter_friendly_name": "department_id",
        "expression": "filter=='department_id'"
      }
    ],
    "default_filter": {
      "queue": "WQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

WorkflowのJSONの解説

パッと見、filterって何してるんだろうと感じると思います。

これを説明するためにまず、Taskqueueの仕様について理解が必要です。

Taskqueueの仕様

Taskqueueはキュー内に存在する、WorkerのAvailabilityはチェックしません。

そのため、割り振りしたけど、そのWorkerが離席してて受電できなかったというようなことが発生しました。

こうやって回避した

離席している人の電話機を鳴らすということを回避するために、

Task発行前に担当するWorkerのAvailabilityをチェックするように変更しました。

Availabilityがtrueの場合、taskにキーがfilter、値がemailの属性を設定します。

falseの場合、taskにキーがfilter、値がdepartment_idの属性を設定します。

この属性はfilter_friendly_nameがemail、department_idの下にあるexpressionで評価される際に使用します。

filterがemailの場合

targetsの中に2つのキューだけあります。

taskにemailの属性が設定されてあり、担当者のメールアドレスが情報として持たせてあります。

この属性を設定することにより、Taskqueueの中からWorkerのemailの属性が合致するものが選択されるため、

まず担当者の電話機が直通で鳴るようになります。

timeoutを10秒にしてあり、在席しているが取ることができなかった場合でも、

自動で次のQueueにエスカレートされ、次の判定であるdepartment_idが一致するWorkerの電話機を鳴らすようにしてあります。

担当者に直通で電話機を鳴らす場合の具体例：{"person_name":"Alice","email":"hiroshi.abe@example.com","department_id":1,"filter":"email"}

filterがdepartment_idの場合

targetsの中に1つだけキューがあります。

先の例と同様ですが、email情報は持っていません。

そのため、Taskqueueの中からWorkerのdepartmnet_idの属性が合致するWorkerが選択され、

担当者と同じ部署の誰かの電話機が鳴らすようにしています。

こちらはtimeoutを設定していないため、電話を切られるまでか、

同じ部署内の誰かが電話を取るまで鳴り続けます。

担当者と同じ事業部の誰かの電話機を鳴らす具体例：{"person_name":"Bob","department_id":1,"filter":"department_id"}

回避した結果

この仕組で不在の担当者に一度着信させて、お客様を待たせるということをなくすことができました。

まとめ

Twilioを利用するメリットはいくつもありますが、

受電から担当者への取次時間を減らせるということは

Twilioを導入する企業、架電するお客様の双方に大きなメリットがあります。

• 直通で担当者につながることにより
  • お客様への安心感の提供
  • 取次が減らせるため、オペレーターが電話業務に取り掛かる時間が減る
  • 通話時間が減るので金銭的に通話料を節約できる

このようなメリットを感じられたら、ぜひTaskrouterの導入をおすすめします。

この記事の主張

• Twilioを用いたWebCTI構築で一番難しいのは受電である
• 保留も難しいと言われるが、保留の実装はドキュメントだけで解決する
• 手を動かす前に、仕様洗い出しと実装のイメージ作りをしましょう

こんにちは、@24guchiaです。

Twilio Advent Calendar 2017 の9日目です。

弊社では営業管理ツールリニューアルに伴い、

電話システムも某IP電話会社から、Twilioへの置き換えを行い、新たにCTIの仕組みを導入しています。

導入にあたり、仕様の洗い出しや提案、実装から各社間の調整まで仕事させてもらっています。

僕はTwilioに触る前まで、IP電話のサービスを使ってなかったし、Twilioは名前も知りませんでした。

1年ほどで得た経験を基に受電の難しさをまとめますので、参考にしてください。

この記事に書いてある内容はTwilioに詳しい人に質問できる環境にありながらも、

基本的には1人で得た知識と経験のため、これがベストプラクティスではないです。

むしろそんなのあったら教えて欲しい。

なぜ受電が難しいのか

IP電話やTwilioについて詳しくない人が、

そもそもネットワークを用いた電話の仕組みを理解できていないからです。

携帯電話はほとんどの人が持っていますが、仕組みが異なります。

電話番号1つに対して、通話を発信・着信できる端末が複数ある

普通の電話は番号1つに対して、発信・着信できる端末は1つだけです。

ですが、Twilioでは1つの電話番号で、複数人が同時に発信・着信できます。

一般的に思い込んでいる、電話番号と端末が1対1なのに対し、Twilioは一対多の関係にあります。

もちろん、1対1の作りでも構築できますが、月額108円が最低でも1人ずつにかかり、

管理コストも膨大なことになります。

これはTwilioが提供しているJavaScriptライブラリや、iOS/AndroidのSDKを使用し、

ブラウザなりアプリなりで仮想電話端末を実装することで解決します。

言われれば当然ですが、いざやってみないと身にしみて分からないこともあります。

同じ電話番号にかかってきた通話を誰に割り振るかを考えないといけない

先のことを理解した時に、この問題にぶつかります。

Twilioへ指示を出すことで誰に割り振るかの指示は出せますが、

誰に割り振るか自体は自分たちで考える必要があります。

この時点で、システムだけでは解決できず、現場で仕事している

営業やオペレーターなどと連携が必要です。

また、先の事実はエンジニアであればすぐに理解できるかもしれませんが、

必ずしもITリテラシーの高くない人へ納得性のある説明をした上で、

現場でどう割り振るのがベストなのかコミュニケーションを取る必要があります。

新しい技術に触れながら、現場の知識も取り込んでいかないといけない。

リアルタイムとの戦い

仕様も無事に決まりました。次に襲いかかる問題がこれです。

一般的なWebエンジニアであれば、実戦経験の少ない

リアルタイムとの戦いが待っています。

受電した通話を誰に割り振るかは決まっても、

その人が在席していないとその通話は空振りになりお客様を待たせることになります。

そこでかかってきた時点のオペレーターの状態を取得する必要があります。

リアルタイムで状態を取得する方法

下記3つが簡単に思いつきます。

1. DBなどに管理し、逐一問い合わせてみる
2. Twilio.Syncを使ってみる
3. Twilio.Taskrouterを使ってみる

DBで管理する場合

在席状態を管理するために、逐一ajaxなどでその人の状態をupdateし続ける必要があります

これはサバクラ両方を1人でスクラッチしつつ、

保守フェーズですべて管理する必要があります。

人数が少なければ可能かもしれないですが、あまり現実的ではなさそうです。

Twilio.Syncを使う場合

SyncとはTwilioが提供しているWebsocketを用いた、リアルタイム通信ができる機能です。

最初に僕がやってみたのがこれでした。

Syncを使うとサーバ側実装がなく、インフラの設定や保守が不要で、

使用した分だけの料金で使うことが出来ます。

ただこの機能は検索性が高くなく、500件のデータを入れたSyncを検索した所、

10秒ほどかかってしまい、受電で使うには難しかったです。

人数次第では選択肢に入ってくるかもしれませんが、実装した上で弊社では採用しませんでした。

Syncを使おうとした時の記事は下記を参照。

Twilio Developer Meetup 2017 – LT用スライド

Twilio.Taskrouterを使う場合

TaskrouterとはTwilioが提供しているACDです。

ACDとは通話を誰に割り振るか分配する機能です。

ロードバランサーというとイメージが付きやすいと思います。

Taskrouterは受電に特化した機能です。最終的に弊社で採用したのはTaskrouterです。

Taskrouterについては、下記記事参照。

Twilio.TaskRouterを調べて使ってみた【長文】

Taskrouter実装との戦い

ライブラリは提供されているだけなので、当然実装する必要があります。

実装するにあたり、一番苦戦した点はドキュメントではもっとも単純なケースの例しかなく、

弊社の仕様ではどうTaskrouterを構築し、実装すべきなのかわからなかったことです。

自分のベストを尽くしたつもりだけど、

構築した環境が良いのかどうかは運用フェーズまで明らかにならないと思われます。

デバッグの大変さ

最終的にはPC4台＋サブディスプレイ2枚＋電話機1台＋私用携帯電話1台を用いた

デバッグ構成で実機デバッグをしました。

一般的なTwilioエンジニアの開発風景

受電した通話の情報を元にどのようなタスクが作成され、誰に割り振られるかまでは

実機がなくてもデバッグ可能です。(これもまあまあ大変ですが)

ですが、在席離席の挙動は想定通りか、リアルタイムで在席状態が正しく取得できるか、

クライアントの通話に問題はないか、タイムアウトとエスカレートの挙動の確認など、

実機で試さないとわからないことが多いです。

物理的にデバッグ環境構築が大変なのは初めてでした。

構築した後もなかなか大変なデバッグ作業になります。

すべてを乗り越えて

晴れて受電の機能が完成です。

受電1つ取ってもこれだけの大ボリュームが待っています。

特に失敗したなと感じたのは、Syncの速度感をもっと早く調べておくべきだと思いました。

弊社では、SyncもTaskrouterもどっちも使うよくばりプランなので、

Syncの実装自体は有用でしたが、最速の実装かと言われるとそうではなかったです。

弊社の場合、ACDを導入していなかったため、

とりあえず導入するだけでも改善効果が見込めます。

具体的には担当営業へ直接つながることによるお客様への安心感の提供、

取次時間を減らせることへの業務改善です。

タイムアウトやエスカレートの仕組みは今回あまり活用できていませんが、

今後の改善へ手が打ちやすくなる布石として考えています。

やっぱり難しそうだな〜と思うあなたへのメッセージ

https://twiliomeetup.doorkeeper.jp/events/68355

このイベントに参加しますので、ぜひ話しましょう！

僕だけでなく、Twilio開発に携わるエンジニアがたくさん参加しますので、

得られることもたくさんありますよ。

次回予告

12/13のアドベントカレンダーで具体的なTaskrouterの設定例を載せますのでお楽しみに。

こんにちは、@24guchia です。

掲題通り、便利そうだけどなんか難しそうだな・・・

と思って避けていたTwilio.Taskrouter導入しました。

最初にお伝えします。

理解が難しいですが、とても便利な機能です。

顧客を待たせることになる受電、手を抜かずにやりきりましょう。

2017/11/04 追記

なんと、Twilio.TaskrouterのプロマネからTwitterでコメントありました。

後ほど、まとめますが、気になる方は僕のTwitterアカウント参照してください。

@24guchia

2017/11/06 追記

一部、不明点やアドバイス頂いた点を追記しました。

Twilio.Syncで受電割り振りすると言ったな

Twilio Developer Meetup 2017 – LT用スライド

あれは嘘だ。

すいません、Syncの使い方間違えてました。

Sync自体は在席管理で使い続けます。Syncも便利です。

Sync → Taskrouter変更の経緯

そもそもSyncでデータの中身に対して、クエリを発行する方法がない。

そのため、全件取得して中身を取り出して、該当する人だったら

その人に通話を割り振るとしていたが、500件mapに入れたら検索だけで10秒位かかった。

遅すぎて流石に厳しいので、ACDに特化したTaskrouterについて調べることにしました。

Taskrouter概要

理解が必要な概念は下記の通り。

• Workspace
  • 以下概念を入れるための入れ物
• Workflow
  • ACDとして、どの呼をどのTaskqueue（後述）に入れるかのルール設定ができる
  • 挙動としては、一般的なSwitch文に似ている。JSON形式で記述方法はSQLライクな文法で設定することが出来る
• Taskqueue
  • 呼を入れて、待たせる。保留と同等なので、架電側には保留音が流れる(電話の場合)
  • FIFOとLIFOが選べる
  • このTaskqueueに入っているTask(後述)をどの属性を持ったWorker(後述)が対応可能かフィルタできる
  • 一般的な使い方はTaskqueueにセールス部門、サポート部門、全社員というような使い分けを行う
• Task
  • 受電した呼に属性をJSONで持たせたもの
  • Taskが持っている属性でWorkflowの評価が行われ、Taskqueueへキューされる
  • 受電以外に問い合わせメールとかにも使えるらしいので、Taskという名前らしい
• Worker
  • Taskを対応する人。オペレーターや営業など
  • Task同様、JSONで属性を持つ。Taskqueueのフィルタの際に評価される
  • 例えば、Aさんにセールス部門という属性をもたせ、Bさんにサポート部門という属性をもたせて、得意なTaskをこなせるように設定する
  • Task対応できるかどうかの属性(Available)やどういう状況(Activity)を持たせる

• その他
  • Workflowによって、タスクキューという通話一覧にキューされる。
  • 優先度と時間によってエスカレートする仕組みがある。
  • タイムアウトの時間設定ができるので何秒か対応できなかったら、自動でエスカレートし、次の評価されたQueueに入る。

概念はこのようになっています。

振り分け処理について

先述の通り、Workflowsに設定しているJSONで振り分けを行っている。

task_routingに設定されているfiltersはSwitch文のように動作する。

filtersのexpressionに合致するタスクは、そのfilter内のtargetsに沿って通話振り分けが行われる。

いずれにも一致しない場合、default_filterのキューに入れられる。

switch caseとdefaultと同じです。

expressionの文法

SQLライク。JSONのキーバリューを走査してくれる。

ANDとORで接続する。一般的な比較ができる、==,!=,>,<,HAS,CONTAINS,IN,NOT INが使える。

型はString,Numbers(int and float),Booleanがある。配列も使える。

タスクにJSONで属性つけるとexpressionでの評価対象になる。

ここらへんはドキュメント読んでください。

Taskrouterってどうやって作るの

いつも通り、管理コンソールかREST APIで作る。

https://jp.twilio.com/console/taskrouter/workspaces/create

で、Twimlでどうやって使うの

Enqueueでworkflowに入れる。

そのときにTask名詞でexpressionの評価対象になる属性をJSON形式で設定できる。

で、クライアントではどう使うの

Taskrouter.jsというJavaScriptSDKが用意されているのでそれを使う。

トークン生成が必要なので、サーバ必須。

ここのところ激プッシュしてるFunctionsでもOKらしい。動画参照

https://www.youtube.com/watch?v=XMg5ytgyn1E

FunctionsだとCRM連携ってどうやるんだろう?

Taskrouterを使う場合の受電の流れ

1. 受電するとTwilioの受電時Webhookが呼ばれる
   1. この画面で管理してるやつ → https://jp.twilio.com/console/phone-numbers/incoming
2. 1で呼び出されたWebhook内でTaskをあるWorkflowにenqueueするtwimlを生成する
3. Workflowの処理が呼び出だされTaskの属性とWorkerの属性によってタスク割り振りが決定し、予約が作成する
4. 割り振りされたら、コールバックが呼ばれる
   1. この画面で管理してるやつ → https://jp.twilio.com/console/taskrouter/workspaces/WSxxx/workflows/WWxxx
5. 4で呼び出されたコールバック内で、タスクをどうするかを決める処理を行う
   1. 今のところ使っているのはVoiceのみのため、基本的に全部callでWorkerのcontact_uriに電話かける
   2. Voice以外のタスクを取り扱うようになったら、適切なチャネルに流れるように設計する必要がある
6. クライアントに電話がかかる
   1. 具体的にはTwilio.Device.incomingとworkerのイベントでresevation.createdが並行して呼ばれる。
   2. 並行に呼ばれるのはかなり厄介なので、他はどうしてるか知りたい

受電のフローはこうです。

TaskRouterの勘所

Taskとあるが、Queue(保留)の仕組みを組み合わせているだけ

これが理解できておらず、苦労しました。

Taskrouterで割り振られた通話の親通話がなぜか取れない

callAPIの受電では親通話に紐付いて、

クライアント側は子通話が生成されるが、Queueと同じ仕組みのため、

割り振られた受電でも、Queueに入っている通話に対して架電しているので、

親子関係が生成されない。

追記：親子関係が生成されない件について

下記ドキュメントにあるようにinstruction:conferenceを使用することで親子関係が生成されるようです。

https://www.twilio.com/docs/api/taskrouter/reservations#conference

現在はdequeueでクライアントにかけているため、

conferenceに変更し、どう挙動するか後ほどまとめます。

ACDって要するにロードバランサーだよね

Automatic Call Distributor/着信呼自動分配装置って、名前いかついし

そんなのWebで似た概念ないよな・・・って思ってたけど、

ロードバランサーと同じってのに気づくと、よく分からないものから

なんとなくイメージが付けやすくなると思います。

良いところ

• 振り分け、タイムアウト、エスカレートできる
  • 振り分けはともかく、タイムアウトとエスカレートの処理を書くのはなかなかしんどいと思う
• ソースを修正せずに、管理コンソールだけで受電振り分け設定を変更できる
  • 注意として、管理コンソールだけでは使用できない設定があり、更にAPIで設定しても管理コンソールに表示されないようなので、この事情を知らない人が勝手に変えると壊れる可能性があります
• 受電したとき、clientだとcurrentの親callを取らないどこからの受電分からないが、taskrouterだとreservation.task.attributesに入ってる
  • 2017/11/06追記： conferenceでTaskを割り振りすることで親受電を取れるようです。現在、確認中
• taskの生成を行う際、JSONになんでも情報を持たせることができ、クライアントでtask.attributesで参照できる
  • task.attibutesはめちゃくちゃ便利です！DBで取得した値を設定することで、クライアント側に受電と同時に取得した値の参照が出来るようになります。
  • API呼び出しとAPI保守費用が下がるので、めちゃくちゃ単純な割り振りしかないからいいやって思わずに、使うと良いです

困りどころ

• dequeue/callを使うと、クライアントの受電とアサインされたtaskの受電で2つとも同じ処理(Twilio.Device.incoming)を通るので、処理の切り分けが必要
  • dequeueだと、connection.parameters.ApiVersionがなぜかないが判断基準にするには微妙（そもそもない事自体がバグなのでは？）
• dequeue/callを使うと、Twilio.Device.incomingがreservation.createdより先に発火する事が多い。
  • 電話は鳴るが、アサインされたtaskが参照できないので若干無駄な瞬間がある
  • たまにreservationの方が速かったりするので、reservation.createdを必ず待つことができない
• ワーカーのavailabilityを見て、割り振りするかの設定であるskip_ifが管理コンソールで変更できない
  • API呼び出しで解決しました
  • APIでskip_if付けても、管理コンソールに表示されないっぽい?
  • 挙動確認したところ、ドキュメント通りなので反映はされているらしい
  • StackOverflowで聞いてるけど、回答が来なくて悲しかったのはちょっと前の話
  • https://stackoverflow.com/questions/46884250/how-do-i-configure-skip-if-on-twilio-taskrouter-workflow
  • 2017/11/06追記：↑先日、回答がありました。現在はAPIで更新／参照の必要があります
  • なんとドキュメントに見れない件がNoteとして記載されていました。嬉しい:)
  • https://www.twilio.com/docs/api/taskrouter/worker-presence
• TaskQueueに対応可能Workerがいなくても、一旦キューに入ってタイムアウトまで待つ
  • 対応可能Workerがいない場合、次のキュー判定に入るかどうかの設定がほしい
• TaskAttributesがマルチバイト文字が未サポート
  • 下記、気合のエンコードとデコードで解決
  • サーバ側(Php)でurlencode()でエンコードして、クライアント側(Taskrouter.js)でdecodeURIComponent(reservation.task.attributes.name)でデコードする
  • Syncではマルチバイト文字対応してるのになんでだろう
  • 2017/11/06追記：Taskの割り振りに関係ないため、対応していないらしい。現在、対応を希望していますが、同上の理由により優先度を上げて対応は難しいとのこと。

REST APIではまったとこ(Php)

https://www.twilio.com/docs/api/taskrouter/workers

• Workerを作るAPIのオプショナルパラメータでドキュメントのFIELDがプログラムで使う連想配列のキーと一致しない
  • ActivitySidはactivitySid、Attributesはattributesをキーにする必要がある。ドキュメント仕事してくれ
  • パラメータ変換するだけのクラス作りました

• Attributesに設定するのは単純な配列じゃなくて、JSON化する必要がある
  • JSON化はTwilioのライブラリ側でやるでも良いような気がする
  • json_encode,json_decodeしないで文字列でゴリゴリJSONを扱うってあんまりしないし
• Worker削除しようとする時に、そのWorkerのavailableがtrueだと削除できない。
  • 対応として、削除する関数にforce引数を付けて、force=trueだったら削除前にavailableがfalseのactivityに変えている。
• QuickStartのドキュメントは更新されてないので、APIは別でドキュメントを読む必要あり
  • https://www.twilio.com/docs/quickstart/php/taskrouter/reservations-create-task-rest
  • まあしょうがないね

Taskrouter.jsではまったとこ（クライアント側）

• Workerのトークン生成でreservation更新を許可しておらず、403が出た
  • エラーメッセージがちょっと分かりづらかった
  • 403 Policies defined such that we cannot access the given resource
  • dequeueでかかってきた通話をconnectするとreservationが更新されたのでより混乱してしまった
• Worker生成のオプションでdisconnectActivitySid設定しても、アクティビティが変わらない？
  • 60秒経ったらタイムアウトするっぽい？↓
  • https://www.twilio.com/docs/api/taskrouter/js-sdk/changelog#193-february-7-2017

まとめ

困りどころ多いですね！

ただそれを差し引いても便利機能なので、がんばって実装しましょう。

後で使いそうなドキュメント

• 時間や曜日ルーティング
  • https://www.twilio.com/docs/api/taskrouter/time-day-routing