kintone integration for Twilio Flex

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

# はじめに

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

この記事は、[Twilio Advent Calendar 2022](https://qiita.com/advent-calendar/2022/twilio)の19日目の記事となります。

Twilio Flex は、クラウド型のコンタクトセンターソリューションですが、Flex 自体には CRM の機能がありません。
そこで、外部の CRM を連携させて利用することが多いのですが、今回はその中でもサイボウズの kintone を連携させる方法についてご紹介します。

## 実行イメージ

![FlexSide.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/0d7522ee-bcf9-1050-5555-a4a02f19417e.png)

Studio フロー内で、発信番号から kintone 上の顧客データを検索し、データが存在する場合は顧客名を表示させます。

さらに、TaskListItem コンポーネントの下に、`kintone`という文字のリンクが表示され、そこをクリックすると別タブで kintone の顧客アプリが開きます。

![kintoneSide.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/c3b667fe-fc9d-32d8-1156-960c9bafc80e.png)

顧客アプリ側に登録が無い電話番号からの着信の場合は、kintone 側は顧客アプリの新規登録画面が表示されます。  
このとき、<font color='red'>クリップボードに</font>発信番号がコピーされているので、電話番号欄への記入が簡単になります。

## Flex UI のバージョン

本プラグインは、Flex UI 2.0 beta-2 で作成してありますが、Flex UI 1.32 でも動作することは確認しています。

## プラグインのダウンロード

以下の GitHub からダウンロードが可能です。

https://github.com/mobilebiz/plugin-kintone-integration

適宜、`git clone`などでローカルにダウンロードしてください。

## ファイル構成

このプロジェクトは以下のようなファイル構成になっています。

```bash
.
├── README.md
├── build
│   ├── plugin-kintone-integration.js
│   ├── plugin-kintone-integration.js.LICENSE.txt
│   └── plugin-kintone-integration.js.map
├── functions
│   ├── assets
│   │   └── logo_kintone_mark_rgb.png
│   ├── functions
│   │   └── get-customer.js
│   ├── node_modules
│   ├── package-lock.json
│   ├── package.json
│   └── readmes
│       └── blank.md
├── jest.config.js
├── node_modules
├── package-lock.json
├── package.json
├── public
│   ├── appConfig.example.js
│   └── appConfig.js
├── src
│   ├── KintoneIntegrationPlugin.tsx
│   ├── components
│   │   └── CustomTaskItem
│   │       └── CustomTaskItem.tsx
│   └── index.ts
├── tsconfig.json
├── webpack.config.js
└── webpack.dev.js
```

functions フォルダには、Twilio Serverless の環境があり、Twilio Functions を使って、kintone から顧客情報を取得する`get-customer.js`が格納されています。  
Flex Plugin は、`src`フォルダの中に格納されています。

## 準備

kintone の準備に加えて、serverless 環境とプラグイン環境でそれぞれ準備が必要です。

### kintone

kintone 側では、顧客情報（電話番号と顧客名）が格納されているアプリを用意する必要があります。  
そのアプリの読み取り権限が付与されたAPIトークンも生成しておいてください。
今回は、サイボウズ様が提供している「[営業支援パック](https://kintone-sol.cybozu.co.jp/apps/030-sfa-pack.html)」を使って、その中の「顧客管理」で実現していますが、もちろんオリジナルの顧客管理アプリでも大丈夫です。

### serverless 環境

`functions/.env.sample`をコピーします。

```bash
cp functions/.env.sample functions/.env
```

コピーした`.env`ファイルを編集して、以下の変数を指定してください。

| Key                        | value                                                                  |
| :------------------------- | :--------------------------------------------------------------------- |
| KINTONE_SUB_DOMAIN         | kintone のサブドメイン名（<https://xxxxx.cybozu.com> の xxxxx の部分） |
| KINTONE_CUSTOMER_API_TOKEN | 顧客情報アプリで生成したAPIトークン                                       |
| KINTONE_CUSTOMER_APP_ID    | 顧客情報アプリの ID（<https://xxxxx.cybozu.com/k/NN/> の NN の部分）   |
| KINTONE_NUMBER_FIELD_CODE  | アプリの電話番号フィールドのフィールドコード（例:TEL）                 |
| KINTONE_NAME_FIELD_CODE    | アプリの顧客名フィールドのフィールドコード（例:顧客名）                |

### プラグイン環境

`.env.sample`をコピーします。

```bash
cp .env.sample .env
```

コピーした`.env`ファイルを編集して、以下の変数を指定してください。

| Key                              | value                                                                |
| :------------------------------- | :------------------------------------------------------------------- |
| FLEX_APP_KINTONE_SUB_DOMAIN      | kintone のサブドメイン名（<https://xxxxx.cybozu.com> の xxxxx の部分） |
| FLEX_APP_KINTONE_CUSTOMER_APP_ID | 顧客情報アプリの ID（<https://xxxxx.cybozu.com/k/NN/> の NN の部分） |

## デプロイ

デプロイも Serverless 環境とプラグイン環境でそれぞれ行う必要があります。

### serverless 環境のデプロイ

```bash
cd functions
npm install
npm run deploy
```

デプロイが成功したら、プラグイン環境に戻ります。

```bash
cd ..
```

### プラグイン環境のデプロイ

```bash
npm install
npm run deploy
```

プラグインについては、デプロイをした後でリリース作業も必要です。デプロイの最後に表示されたコマンドを実行するか、Flex 画面上からプラグインのリリース作業を行ってください。

## Studio Flow の設定

ここまでの設定が完了したら、最後に Studio フローを使って、kintone で取得したデータを Flex に渡していきます。  
作成が必要なウィジェットは 2 つです。

### RUN FUNCTION ウィジェット

`getCustomer`という名前で RUN FUNCTION ウィジェットを作成してください。

![runFunction.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/c2f1b17f-99bd-f30f-0b13-cb91a73312fa.png)

Function Parameters に、以下の Key/Value を指定してください。

| Key  | Value                 |
| :--- | :-------------------- |
| from | {{trigger.call.From}} |

:::note info
大文字小文字を間違えないようにしてください。
:::

### SEND FLEX ウィジェット

Flex に接続するウィジェットの Attributes に、以下のパラメータを入れてください。

| パラメータ名 | 値                                         |
| :----------- | :----------------------------------------- |
| name         | {{widgets.getKintone.parsed.customerName}} |
| recordId     | {{widgets.getKintone.parsed.id}}           |

:::note info
パラメータ名、値はそれぞれダブルコーテーションで囲むのを忘れないようにしてください。
:::

![sendToFlex.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/86046/5e5e6597-8acd-b637-99a3-7ccfec54b20e.png)

# まとめ

本来は、Twilio Flex の CRM パネル上に kintone データを表示できると良いのですが、kintone が一部の画面のみしか iFrame 対応をしていないために、別タブで開く方法にしました。
リンクをクリックする手間はありますが、比較的簡単に連携ができるので便利だと思います。
また kintone は、他の CRM サービスに比べて安価でカスタマイズも容易なため、低コストでコンタクトセンターを作りたいときなどにも良いかと思います。

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

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

Twilioに関するご相談などがございましたら、ぜひ毎週水曜日の午後に開催しております相談会をご利用ください。
[Twilio相談会（毎週水曜日）](https://cloudapi.kddi-web.com/contact/consultation?hsLang=ja-jp)

自己紹介|　
:--|:--
<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