Twilio Flexの始め方（TaskRouter基礎編）

:::note alert
2023年5月1日を持ちまして、株式会社KDDIウェブコミュニケーションズのTwilioリセール事業が終了したため、本記事に記載されている内容は正確ではないことを予めご了承ください。
:::

# はじめに

みなさん、こんにちは。
KDDIウェブコミュニケーションズのTwilioエバンジェリストの高橋です。

[Twilio Flex Advent Calendar 2021](https://qiita.com/advent-calendar/2021/twilio-flex) 8日目の記事となります。
[前回の記事](https://qiita.com/mobilebiz/items/916b416af155bdab988b)では、GoogleSpreadsheetを使って顧客の名前を着信時に表示させる方法についてご紹介しました。

本記事から、 いよいよTaskRouterの機能について説明をします。TaskRouterにはいろいろな機能があるため、とても一つの記事では収まらないので、何回かに分けて説明をしていきます。
まず本記事では、TaskRouterの全体像を理解していただこうかと思います。

# TaskRouterとは何？

一言でいうと「スキルベースのタスクルーティングエンジン」です。
はい。よくわからないですよね。

まずは**タスク**について説明します。
我々はよく仕事のことをタスクと呼んだりしますね。「新しいタスクが振ってきてさー、めっちゃ忙しいんだよ」みたいな。
タスクとは、「課された仕事や課題」のことを指し、Twilio Flexでは着信や発信などをすべてタスクとして生成し、それを処理していくことを前提として作られています。

で、そのタスクにはいろいろな**情報（属性）**を付与することができます。たとえば、「これは電話の着信のタスクです」とか、「これはSMSの着信です」とかです。さらに、その属性はカスタマイズが可能なので、「営業の問い合わせです」とか「サポートの問い合わせです」といった情報も付加することができます。

そのタスクを処理する人たちのことを**ワーカー**と呼びます。コールセンターなどではオペレーターとか呼ばれることもありますが、Twilio Flexでは、ワーカー（Worker）もしくはエージェント（Agent）と呼びます。
このワーカーには、スキルを付与しておくことができます。たとえば、「この人は英語が話せます」とか、「営業の知識があります」とかです。さらにはスキルレベルも付与しておくことができますので、高度な質問が来たときはなるべくスキルの高いワーカーを割り当てたいといったニーズにも対応できます。また、ワーカーには状態があります。たとえば、「待受中」とか「離席中」、「おやすみ」といった感じです。

そして、タスクの属性を判定して、最適なワーカーにタスクをアサインするのが、**ルーティングエンジン**です。ルーティングエンジンの役割は今書いたとおりなのですが、もう少し細かく説明しましょう。

まず、タスクを一時的に保管しておく場所があります。TaskRouterでは、**タスクキュー（Task Queue）**と呼ばれます。この一時保管場所には、処理するワーカーをアサインしておくことができます。なので、たとえば「営業」という一時保管場所を作成して、営業のスキルをもったワーカーを割り当てておくことで、タスクをこの保管場所に入れてしまえば、あとは営業ワーカーが処理してくれることになります。

そして、タスクをタスクキューに割り当てる処理を行うのが、**ワークフロー**になります。すなわち、ワークフローはTaskRouterの中の仕分けをする役割を担っています。ワークフローはタスクに書かれた属性を判定し、最適なタスクキューにタスクを入れるのが仕事ですが、タスクキューの状況も監視しています。たとえば、営業のタスクキューにタスクを入れたのに、ワーカーが忙しくてタスクを処理してくれなかったときなどに、そのタスクを別の部屋に入れ直したりできます。
ワークフローの作り込み次第で、タスクの処理方法を色々とカスタマイズができるので、ワークフローはTaskRouterの中心的な機能になります。

以上の説明から、TaskRouterが「スキルベースのタスクルーティングエンジン」と呼ばれる理由がご理解いただけたかと思います。

これ以外にも知っておいてほしい用語としては、**タスクチャンネル（Task Channel）**があります。具体的には、Voice（音声）、SMS、WebChat、Videoなどですが、わかりやすくいえば、**タスクの質**を定義したマークのようなものです。たとえば、VoiceとかVideoというマークがついたタスクは、通常ワーカーは同時に一つしか対応できません。一方で、SMSやWebChatであれば、同時に複数の対応をすることもできます。
また、ワーカーに対してこのタスクはどんなものですよということを知らせるときに利用されます。

![スクリーンショット 2021-12-10 9.19.53.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/072add26-4a93-6d5c-0663-924644b40d01.png)
これはワーカーに対して電話の着信を知らせていますので、青い電話のアイコンが表示されています。このように、タスクチャネルはタスクの種類を知らせる役割ももっています。

# タスクの生成から終了までの流れ

では次に、実際にタスクが生成されてからタスクが終了するまでの流れを具体的に確認していきましょう。

[TaskRouterの動作のしくみ](https://jp.twilio.com/docs/taskrouter/how-taskrouter-works#how-taskrouter-works)より引用
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/43b1833d-b9d4-0372-636a-c63ae43d0aa1.png)

## 1. A Business Event

イベントが発生するところがすべての起点です。たとえば電話の着信であったり、SMSの受信、電話を発信するというのもイベントに含まれます。
Twilio Flexにおいて、電話の着信をイベントとして取得するには、**Phone Numbers**の**A CALL COMES IN**のWebHookなどでイベントを処理します。
![スクリーンショット 2021-12-10 13.59.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/173b66d1-5b1c-da4a-e4aa-0040172db296.png)

## 2. Your Application

イベントを受け取った後、システム側でイベントに応じたタスクを生成する必要があります。タスクの作成には、Twilioの[RestAPI](https://jp.twilio.com/docs/taskrouter/api/task?code-sample=code-create-a-task&code-language=Node.js&code-sdk-version=3.x#linkcode)や[TwiML](https://jp.twilio.com/docs/voice/twiml/enqueue)を利用することができますが、Twilio Studioには、タスクを生成するウィジェットも用意されているので、Twilio FlexではStudioを使うケースが多いです。

![スクリーンショット 2021-12-10 14.04.07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/e9489c6d-ca71-5db1-584a-a271c0fdec23.png)
**Send to Flex**ウィジェットは、内部的にはタスクの生成とそれを処理するワークフローへの接続を行います。

タスクの生成時に、**ATTRIBUTES**という属性を自由に指定ができます。
上の例では、タスクチャネルとして`Voice`、それ以外の属性として、`type`が着信、`name`に顧客名を付加しています。作成されたタスクは、`Assign To Anyone`というワークフローに渡されます。

## 3. Workflow

先にも書いたように、タスクの属性などを判断して最適なタスクキューに振り分ける仕事をするのがワークフローです。割り振るための情報には、タスクの属性が利用されます。
割り振るためのルールは、管理コンソール上で設定することができます。
![スクリーンショット 2021-12-10 14.57.14.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/b5d2f306-d384-f594-151f-b02a3711ffa3.png)

ワークフローには複数のルールを定義することができ、それらを**フィルター**として管理します。

### MATCHING TASKS

このフィルターで処理すべき**タスクの条件**を指定します。
例えば、`customer_value == 'Gold' AND type == 'ticket'`という条件を指定すると、タスクの中の`customer_value`の値が`Gold`で、かつ`type`が`ticket`のものが一致します。

### Routing Steps

上記の条件に一致したタスクの処理を指定します。処理の単位をステップと呼び、ステップは段階的に複数指定することができます。次のステップに移る条件としてタイムアウト値やプライオリティが指定できます。これらの設定を使うことで、長時間放置されているタスクを別のキューに割り当てたり、プライオリティの高いタスクを専用の担当者にエスカレーションするなどを実現することができます。


なお、ルールの作成はJSON形式で指定することもできます。

![スクリーンショット 2021-12-10 14.58.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/e826ddb0-c4b7-e75d-ed8e-f4f5f0e17f63.png)

## 4. Task Queue

ワークフローによってタスクがタスクキューに割り当てられ、割り当てられたタスクは、タスクキューにアサインされているワーカーに対して割り当てられます。アサインされているワーカーの中に待受中のワーカーがいない場合、タスクはタスクキューの中で待ち状態になり、ワーカーが空いた時点でそのワーカーに割り当てられます。

![スクリーンショット 2021-12-10 15.26.28.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/129bf33c-b660-71d7-f71d-76732fb3c8a9.png)

**TASK ORDER**は、処理すべきタスクの順序を指定します。通常はFIFO（First In First Out：先に入ったタスクから先に処理される）ですが、LIFO（Last In First Out）にすることもできます。

**RESERVATION ACTIVITY**は、タスクが特定のワーカーに割り当てられたときに、そのワーカーの状態をどのように遷移させるかを指定します。通常、タスクがワーカーに割り当てられると、システムがワーカーを呼び出します。呼び出し状態になったワーカーに対して、別のタスクが割り当てられないようにするため、TaskRouterはワーカーの状態を`Reserved`にします。

**ASSIGNMENT ACTIVITY**では、ワーカーが応答したときにワーカーの状態をどのように変えるかを指定します。デフォルトでは、`Busy`になります。

**MAX RESERVED WORKERS**は、タスクを**同時に**何人に予約できるかを指定するものです。通常、１つのタスクは一人のワーカーを呼び出しますが、たとえば同時に複数のワーカーを呼び出したいときには、ここの数字を変更します。デフォルトは１で、最大50まで指定が可能です。
ここを１より大きな数字にした場合、複数の１つのタスクは複数の予約タスクに分割されます。そして、それぞれのタスクに対して一番最初に応答したタスクが「割当済み」となり、それ以外の予約タスクは無効になり破棄されます。

**QUEUE EXPRESSION**は、このタスクキューに割り当てをするワーカーの条件を指定する部分になります。例えばこのフィールドに、`routing.skills HAS 'Sales'`と指定すると、以下のような属性を持ったワーカーがアサインされます。

```json
{
  "routing":{
    "skills":["Sales"],
    "levels":{}
  },
  "full_name":"katsumi takahashi",
  "image_url":"https:\/\/www.gravatar.com\/avatar\/acb69cfef89e268ee34cd6dedf260241?d=mp",
  "roles": ["admin","wfo.full_access"],
  "contact_uri":"client:katsumi_2Etakahashi",
  "disabled_skills":{
    "skills":[],
    "levels":{}
  },
  "email":"katsumi.takahashi@kddi-web.com"
}
```

条件に一致するワーカーが誰かは、タスクキューの設定画面の下部の**Matching Workers**に表示されます。

### 予約（Reservation）について

タスクキューによってタスクはワーカーに割り当てられますが、このときのタスクの状態は**予約中**になります。なぜなら、この時点でワーカーがタスクを本当に処理できるかわからないからです。
たとえば、ワーカーの状態が待受中になっていたとしても、実際には席を外してしまっている可能性もあります。そのような場合、多くのケースではワーカーの呼び出しが行われますがワーカーは反応しないので、タスクは処理されないままになります。ちなみに、ワーカーの呼び出しタイムアウトのデフォルトは120秒です（ワークフローの設定）。タイムアウトになったワーカーの状態は、デフォルトでは`offline`に遷移します。

## 5. Worker

すでに説明しているように、ワーカーはタスクを処理するためのオブジェクトで、通常はコンタクトセンターのオペレーターに対して割り当てます。Twilio Flex上には、デフォルトで15,000のワーカーを作成することができます。
なお、Flex をインストールした Twilioアカウントは、 自動的にワーカーとしても登録されています。そして、Flex をカスタマイズしたり、スーパーバイザーとしてエージェントの管理をしたり、もちろん Flex を利用して自身でコールに応対することができます。

では、それ以外のオペレーターをFlexにワーカーとして登録するにはどうすればよいでしょうか。
方法は２つあります。

1. Twilioアカウントを作成し、Flexプロジェクトに招待する。
1. 外部のSSO（Single Sign On）サービスを利用する。

1は簡単な方法ではありますが、Flexのエージェント毎にTwilioアカウントを作成するのは少々面倒です。ちなみに、Twilioアカウントの招待方法については、以下の記事を御覧ください。
[Twilioで開発を始める前に知っておくこと（ユーザー管理編）](https://qiita.com/mobilebiz/items/cfd8993bfeaf090f95a5)

そこで現実的な管理方法が外部のSSOサービスを利用することです。Twilio Flexでは、SAML2.0に対応したidPを利用することができます。例えば、以下のサービスへの設定方法はドキュメントも用意されています。

- [Okta](https://www.twilio.com/docs/flex/admin-guide/setup/sso-configuration/okta)
- [Microsoft Azure](https://www.twilio.com/docs/flex/admin-guide/setup/sso-configuration/azure-ad)
- [Google](https://www.twilio.com/docs/flex/admin-guide/setup/sso-configuration/google)
- [Salesforce](https://www.twilio.com/docs/flex/admin-guide/setup/sso-configuration/salesforce)
- [Microsoft ADFS](https://www.twilio.com/docs/flex/admin-guide/setup/sso-configuration/adfs)

次回の記事で、SSOとして Oktaサービスを利用したSSO連携を解説します。

### スキルの定義

先程の説明で、TaskRouterはスキルベースで動作すると説明しました。では、そのスキルはどのように設定するのでしょうか。
実はFlexには、スキル定義のツールが用意されています。

- 管理者としてFlexを起動します。
![スクリーンショット 2021-12-11 10.45.40.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/c868abdf-9a44-4720-2774-0c869e9a117d.png)

- **Admin View**画面を開き、**ASSIGNMENT**の**SKILLS**ボタンを押します。
![スクリーンショット 2021-12-11 10.48.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/4ed0f3ca-c754-2a77-3426-2cf5b9f343d3.png)

- **NAME OF SKILL**欄に「Sales」と入力します。
- **ADD NEW SKILL**ボタンを押します。
- 追加が成功すると、以下のようにこのスキルを定義するときの条件式が表示されます。
![スクリーンショット 2021-12-11 10.50.06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/3f6334d9-3d0b-76b6-1bdf-00f7c199fe2b.png)

- 同様に「Support」というスキルも登録しておきましょう。
![スクリーンショット 2021-12-11 10.52.26.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/416bb7b6-2e2b-22cf-c14e-7c0291e88869.png)

### ワーカーにスキルを割り当てる

- **Worker View**画面を開き、スキルを割り当てたいエージェントの行を選択します。
![スクリーンショット 2021-12-11 10.53.27.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/647e1bbe-3ed8-682d-8262-d9e8dd2e2f08.png)

- 右側の**PROFILE**パネルの**SKILLS**のプルダウンを開きます。
- 先程登録しておいた「Sales」と「Support」が表示されるようになるので、「Sales」を選択します。
- 右側の青い＋アイコンを押します（ここを押すことで登録されます）。
- 同様に、「Support」のスキルも登録しておきましょう。
![スクリーンショット 2021-12-11 10.58.02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/13d39e0a-0525-881b-839c-471013b69dce.png)

- **SAVE**ボタンを押して、設定を登録します。

以上の作業を行うことで、TaskRouterのWorkerに対するAttributesは以下のように登録されます。

```json
{
  "full_name":"克己 高橋",
  "image_url":"https:\/\/www.gravatar.com\/avatar\/5448f8c3e8571ba245c70536e9c8cd9a?d=mp",
  "roles":["admin"],
  "contact_uri":"client:katsumi",
  "email":"katsumi@example.com",
  "routing":{
    "skills":["Sales","Support"],
    "levels":{}
  },
  "disabled_skills":{
    "skills":[],
    "levels":{}
  }
}
```

routing.skillsに「Sales」と「Support」が登録されているのがわかります。

# まとめ

今回は、TaskRouterの基礎ということで、全体を俯瞰しながら各パーツの解説をしました。
次回以降はTaskRouterのそれぞれのパーツをより詳しく紹介していきたいと思います。

★次の記事
[Twilio Flexの始め方（エージェント管理）](https://qiita.com/mobilebiz/items/3c2f2582b7437f63dc14)

---
### Twilio（トゥイリオ）とは

https://cloudapi.kddi-web.com
Twilio は音声通話、メッセージング（SMS /チャット）、ビデオなどの 様々なコミュニケーション手段をアプリケーションやビジネスへ容易に組み込むことのできるクラウド API サービスです。初期費用不要な従量課金制で、各種開発言語に対応しているため、多くのハッカソンイベントやスタートアップなどにも、ご利用いただいております。

自己紹介|　
:--|:--
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/b51a8b88-abd5-ce5e-195a-de3564ba2ae6.png" height='200' width='150'/>|高橋克己（Katsumi Takahashi） 自称「<font color='red'>赤い芸人</font>」<br />グローバル・インターネット・ジャパン株式会社　代表取締役<br />株式会社KDDIウェブコミュニケーションズ　Twilio事業部エバンジェリスト<br /><br />2001年より大手通信事業者の法人サービスの教育に携わり、企業における電話のしくみや重要性を研究。2016年よりTwilio事業部にジョインし、Twilioを使ったスマートコミュニケーションの普及活動を精力的に行っている。<br />2015 Hall of Doers<br />2019 Twilio Champions