カテゴリー内の他の記事

Twilioを使ってkintoneから直接電話をかけてみよう

作成日2019年04月22日 03:00
更新日2021年01月12日 04:23

（株式会社KDDIウェブコミュニケーションズ　Twilioエバンジェリスト高橋克己）

はじめに

みなさん、こんにちは。 KDDIウェブコミュニケーションズのTwilioエバンジェリスト高橋です。
ところでみなさん、Twilioってご存知でしょうか？

Twilioは、コミュニケーションAPIを提供するサンフランシスコ生まれのサービスで、プログラムから電話をかけたり、SMSを送信したりできます。
また、ブラウザを使って電話をかけたり受けたりすることもできます。
ご存知の通り、kintoneはブラウザで動作するため、Twilioを使うことで電話回線や電話機を一切使用せずに、kintoneだけで電話の発着信ができます。

本記事では、kintoneアプリの詳細画面上に電話をかけるためのボタンを設置し、
ボタンを押すとそのレコードの電話番号欄にかかれている先にTwilio経由で電話をかけるというものです。

準備するもの

パソコン（Chromeブラウザ、マイク、スピーカー）※Chromeブラウザ、マイク、スピーカーがないと動作しません
インターネット環境（Networkテストページでテストをして、エラーが出ないことを確認してください）
JavaScriptファイルを編集するためのエディタ
kintoneのアカウント
Twilioアカウント（トライアルアカウントでも可）

Twilioアカウントの準備

Twilioのアップグレード済みアカウントをすでにお持ちの方は、そのアカウントをそのままご利用いただけます。
アカウントをお持ちでない方は、Twilioサインアップページよりサインアップをしてください。
サインアップが完了すると、トライアルアカウントとして500円分のポイントが使えるようになります。
トライアルアカウントには、以下の制限があります。

電話番号は１つしか購入できません。
発信が可能なのはサインアップに認証した電話番号宛のみとなります。
着信時にトライアルアカウントである旨のガイダンスが流れます。

継続して利用したい場合は、クレジットカードを登録してポイントを追加し、アカウントをアップグレードしてください。
アップグレードされると、上記制限はなくなります。

作業手順

本記事の作業手順は以下のとおりです。

kintone側でアプリストアから「顧客リスト」アプリを作成する。
詳細画面に発信用ボタンを実装する。
Twilio側で電話番号を購入する。
発信用アプリケーション（Twilioアプリ）を作成する。
ケイパビリティトークンを生成するしくみを作る。
環境変数を設定する。
kintone側のJavaScriptをコーディングする。
kintoneアプリにJavaScript/CSSを実装する。
テストする

アプリストアから「顧客リスト」アプリを作成する

今回は、kintoneに予め用意されている「顧客リスト」をカスタマイズしていきますので、
ご自分のkintoneの環境に新しいアプリとして「顧客リスト」アプリを追加してください（サンプルデータも一緒にインストールします）。

customer_list_template

詳細画面に発信用ボタンを実装する

今回は、顧客リストアプリの詳細画面に電話発信ボタンを追加して、開いているレコードの電話番号に発信します。
そのため、詳細画面にボタン配置用のスペースフィールドを追加します。
フィールド名（要素ID）は「connectButtonSpace」とします。

スペースフィールドが作成できたら、アプリの変更を保存しておきましょう。

電話番号を購入する

Twilio経由で電話を架ける場合、発信者番号はTwilio上で購入した番号になります。
では早速、Twilioの電話番号を購入してみましょう。

Twilioの管理コンソールにログインする

ブラウザでTwilioのログイン画面を表示し、ご自分のIDとパスワードでログインをします。

電話番号を購入する

すでに050番号をお持ちの方は、そちらをご利用いただくことができますので、このセクションは飛ばしていただいて大丈夫です。

管理コンソールの左側にあるボタンアイコンを押すと、スライドメニューが表示されます。

スライドメニューの一覧から、電話番号もしくはPhone Numbersを選択します。

Phone Numbersメニューの中のBuy a Numberを選択します。
国のプルダウンから「Japan（+81）」を選択し、検索ボタンを押します。

一覧表示されたリストの中から、TYPEがローカルになっている（108円）の番号を一つ選び、購入ボタンを押します。
この番号を購入しますか？というダイアログが出たら、この番号を購入するを押します。
Congratulationのダイアログが表示されたら、購入完了です。閉じるボタンを押します。
Phone Numbersの中のManage Numbersを選択し、今購入した電話番号が表示されることを確認します。
購入した電話番号は後ほど使いますので、メモ帳などに控えておきます。

電話番号の表記方法について
Twilioは、世界100カ国と接続されていて、それぞれの国に直接電話をかけることができます。
そのため、発信・着信の電話番号は、全世界で利用可能な「E.164形式」と呼ばれる表記方法を使います。
E.164形式とは、先頭が+から始まる国番号と電話番号の組み合わせです。
例えば、日本は国番号が+81となっており、その後の電話番号を続けて記述します。
※電話番号の先頭の0は削除します。
「09012345678」は、E.164形式だと「+819012345678」となります。

発信用のアプリケーションを作成する

今回は、kintoneのJavaScript実行環境上で、TwilioのVoIPクライアントを動作させるため、TwilioのVoIPクライアントの仕組みを先に説明します。
ただし、ちょっと難しいので、この時点で完全に理解して頂く必要はありません。

Twilio側に、発信用Twilioアプリを作成しておきます。
ブラウザからTwilioに対してRestAPIを使ってトークン（ユーザーがTwilioの機能を利用することを許可するための有効期限付きの認証情報）の生成をします。
その際に、発信用Twilioアプリの情報を渡すことで、トークンにアプリがひも付きます。
ブラウザ側は生成されたトークンを使って、Deviceクラスのセットアップを行います。
セットアップされたDeviceクラスに対してConnectメソッドを利用することで発信が可能になります。
Connectメソッドを呼ぶ際に、発信先の電話番号を渡すことができます。
同様に、Deviceクラスに対してDisconnectメソッドを利用すると、通話中のコールを切断することができます。

＜参考＞Twilioアプリとは

Twilioでは、Twilioを操作する言語としてTwiML（トゥイムルと呼びます）が用意されており、
たとえば今回のようにブラウザからの発信依頼を外線に転送するためには、以下のようなTwiMLのDial動詞を利用します。
ここで重要なことは、kintoneから電話をかけるといいながら、内部的にはkintoneからTwilioに発信し、
Twilioが着信したコールを実際の相手方に転送しているということです。

この例では、ブラウザから発信が090XXXXXXXXに転送されます。その際の発信者番号として、
050XXXXXXXXが利用されます。Twilioは内部的にE.164形式で電話番号を記述することに注意してください。

Twilio Functionsを使って、動的にTwiMLを生成する

ここでは、kintoneから受け取った相手先電話番号を使って、動的にTwiMLを作成するFunctionを作っていきます。

Twilioの管理コンソールで、スライドメニューからRuntimeを選択します。
Your Runtime Domainのところに表示されている「xxxx-xxxxxx-xxxx.twil.io」をメモ帳にコピーしておきます（これがあなたのRuntimeドメインになります）。
RuntimeのFunctionsを選択します。
さらに管理を選択し、Create a new Functionもしくは、赤い＋アイコンを押して、新しいFunctionを作成します。
テンプレートを選択するダイアログが表示されるので、Blankを選択した後、Createボタンを押します。

FUNCTION NAME欄に「CallPhone」と入力します。
PATH欄に「/call-phone」と入力します。
CODE欄に予め書かれているコードをすべて削除し、以下のコードを貼り付けます。

Saveボタンを押して、設定を保存します。
Path欄の右側にあるコピーアイコンをクリックして、URLをコピーしメモ帳などに記録します。

このコードでは、Toというパラメータで相手先電話番号を受け取っています。
また、発信元電話番号として、context.FROM_NUMBERを指定していますが、これはこのあと設定する環境変数を参照しています。
このFunctionが正常に実行されると、先に示したようなTwiMLが動的に生成されます。

Twilioアプリを作成する

次に、今作成したFunctionをTwilioアプリにします。

管理コンソールのスライドメニューからPhone Numbersの中のツール > TwiML Appsを選択します。
新しい TwiML App を作成するボタンを押すか、赤い＋アイコンを押します。
わかりやすい名前に「CallPhone」と入力します。
REQUEST URLに、先程メモしておいたFunctionのURLを入力します。

保存ボタンを押します。
作成したTwiML APPを選択します。
プロパティの中のSID（APから始まる文字列）をメモ帳にコピーします。
※ケイパビリティトークンを生成する際に利用します。

ケイパビリティトークン生成のしくみを作る

ケイパビリティトークンは、kintoneからのリクエストを受けて、Twilio側のAPIで生成する文字列です。
トークンには有効期限があり、生成時に指定をしない場合は1時間となります（最大24時間のトークンを生成することが可能）。
トークンを利用することで、発信と着信のいずれか、もしくは両方をブラウザ（今回の場合はkintoneに）許可をすることができます。
今回はkintoneからの発信のみですので、発信用のトークンを作成する必要があります。トークンの生成に必要な情報は以下のとおりです。

TwilioのAccountSIDとAuthToken（管理コンソールから確認できます）
発信用TwilioアプリのSID（先程メモ帳に保存していただいています）
Identity（クライアントを識別するための文字列で、今回はkintoneのログインユーザIDを利用する予定です）

Twilio Functionsを使って、ケイパビリティトークンを生成する

Twilioの管理コンソールで、スライドメニューからRuntimeのFunctionsを選択します。
さらに管理を選択し、Create a new Functionもしくは、赤い＋アイコンを押して、新しいFunctionを作成します。
テンプレートを選択するダイアログが表示されるので、Blankを選択した後、Createボタンを押します。

FUNCTION NAME欄に「token」と入力します。
PATH欄に「/token」と入力します。
ACCESS CONTROLのチェックボックスもオフにします。

CODE欄に予め書かれているコードをすべて削除し、以下のコードを貼り付けます。

Saveボタンを押して、設定を保存します。しばらくするとデプロイが完了します。

この例では、呼び出し時にidentityというパラメータを受け取り、そこにkintoneのログインIDが入っていると仮定しています。
また、5行目はCORS（Cross Origin Resource Sharing）の指定になります。
このFunction自体、kintone内のJavaScriptから呼び出されるため、
通常であればブラウザのクロスサイト・スクリプティング防止機能が効いてしまい、kintoneからのアクセスが失敗してしまいます。
そこで、CORSを指定して、呼び出し元のkintoneアプリのURLを指定することでこの問題を回避しています。

環境変数を設定する

この時点で2つのFunctionが完成しています。
それぞれのFunctionは、環境変数によって値を取得するようになっているため、皆さんの環境に応じて環境変数を設定する必要があります。

Twilioの管理コンソールで、スライドメニューからRuntimeを選択します。
その中のFunctionsを選択し、さらに設定を選びます。
Enable ACCOUNT_SID and AUTH_TOKENのチェックを入れます。

Environmental Variablesの中の赤い+アイコンを3回押して、枠を3行作ります。
※すでに以下の環境変数が設定されている場合は、VALUE値だけを確認してください。
以下の内容を記載します。

KEY	VALUE
FROM_NUMBER	購入した050番号をE.164形式（+8150XXXXXXXX）で指定します
KINTONE_APP_URI	kintoneのURLに含まれるドメイン文字列(xxxxx.cybozu.com)を指定します
TWIMLAPPS_SID	先程メモ帳に控えておいたTwilioアプリのSID（APから始まる文字列）を指定します

Dependenciesの設定内にある、「Twilio」のVERSIONを「3.30.1」に変更します。

Saveボタンを押して、設定を保存します。

kintone側のJavaScriptをコーディングする

さて、ここからはkintone側の設定になります。
kintoneアプリから電話をかけるためには、TwilioのJavaScript SDKを使って、プログラムを作成していく必要があります。

お使いのエディタで、client.jsという名前のファイルを作成し、まずは以下の雛形を作成します。

kintoneでJavaScriptを利用する場合は、スコープ汚染を防ぐために上記のように即時関数を利用します。
また、エラーチェックを行うために厳格モード（use strict）も指定しておきましょう。

レコード詳細画面を開いた時のコーディング

今回は、顧客アプリの詳細画面を開いたときに、
その顧客に電話ができるようにしたいため、詳細画面をひらいたときに動作するコードを記述する必要があります。
kintoneでは、詳細画面を開いた時にapp.record.detail.showイベントが発火するので、これを補足するようにします。

この例では、eという変数を参照することで、各種情報にアクセスできます。
例えば、担当者名（フィールドコードが「担当者名」）にアクセスするには、e.record['担当者名'].valueと指定できます。

電話発信の手順

TwilioのJavaScript SDKでは、以下の方法で電話を発信します。

ケイパビリティトークンを取得します。
取得したトークンを使って、Deviceクラスを初期化します。
発信したいタイミングで、Deviceクラスのconnect()メソッドを呼び出します（このときに発信先電話番号を指定できます）。
こちらから切断したい場合は、Deviceクラスのdisconnect()メソッドを呼び出します。

トークンの取得

ケイパビリティトークンを取得するために、先程作成しておいたFunctionをfetchで呼び出してみましょう。
以下のようなコードになります。

twilioDomainは、ご自分のTwilio環境（Runtimeドメイン）に併せて変更してください。
kintone.getLoginUser()を使うと、現在kintoneにログインしているユーザ情報が取得できます。
今回はその中のidフィールド（自動採番される数値）を取得して、これをトークンの識別子として利用します。

トークンの呼び出しが成功すれば、最終的にdataオブジェクトにJSON形式で値が戻ります。

トークンを使ってDeviceクラスを初期化する

Deviceクラスの初期化は以下のようなコードになります。記述が必要なのは、トークンデータ（data）を受け取った後になります。

Deviceクラスの初期化にはトークンが必要です。
setup()メソッドでは、リージョン指定（日本はjp1）と、ブラウザを閉じたときの警告メッセージなどが指定できます。
setup()メソッドの詳細については、ドキュメントページを御覧ください。

Deviceクラスを使うと、以下のような各種イベントを取得することできます。

ready: Deviceクラスの初期化が成功し、利用可能になった場合に発火します。
error: なんからのエラーが発生したときに発火します。
connect: 呼び出し（connect()メソッドの呼び出し）が完了し、相手と接続したときに発火します。
disconnect: 相手との通話が切断したときに発火します。
offline: ケイパビリティトークンが切断されるなど、Deviceクラスが無効になった場合に発火します。

これらのイベントは以下のように記述することができます。

この例では、offlineイベントが発生したときに、再度トークンを取得してDeviceクラスの初期化をしています。
このようにしておくことで、トークンの有効期限（初期値は1時間）が切れてしまって発信できなくなることを防いでいます。

発信ボタンを作成する

電話をかける準備は整いましたので、次にkintoneアプリ上に発信ボタンを設置してみましょう。

今回は予め画面上に作成しておいたスペースフィールド（フィールドコード「connectButtonSpace」）にボタンを配置していきます。
コードを書く場所は詳細画面を表示した直後あたりがよいでしょう。

また、ボタンの表示には2018年5月に公開された、「kintone UI Component」を利用します。
これにより、kintoneライクなUIが簡単に実装できます。
「kintone UI Component」の詳しい説明については、ドキュメントページを御覧ください。

まずはUI Componentのbuttonを生成します。ボタンには「発信」という文字を表示するようにしています。
出来上がったボタンを事前に用意したスペースにエレメントを追加することで、ボタンがアプリ上に表示されます。
ただし、ケイパビリティトークンを取得するまでにボタンが押されないようにするために、この時点ではボタンを非表示にしておきます。

トークンの取得が成功し、Deviceの準備が整った時点で、上記のようにボタンを表示します。

ボタンが押されたときの動作を設定する

ボタンが押されたときの動作は、buttonActionという関数にして、コードの先頭部分に定義しておきます。

発信ボタンは、通話中には切断ボタンとしても使いたいので、
ボタンが押された時に、ボタンの表示を判定して「発信」と表示されているときは発信、それ以外は切断するようにしています。
発信するときは、Deviceクラスのconnect()メソッドを利用しますが、そのときにToパラメータを指定することで、Twilioアプリにパラメータが引き渡されます。

通話中になったときの処理

発信ボタンを押すことで、Twilio経由で相手方の電話に発信が行われます。
発信が正常に行われ相手が応答すると、Deviceクラスのconnectイベントが発火します。
今回は、このイベントが発火したときに、ボタンのキャプションを「切断」に変更したいと思います。
connectイベント内に記載するコードは次のようになります。

切断完了時の処理

同じく、通話が終了したときにボタンのキャプションを「発信」に戻したいと思います。
こちらは、diconnectイベント内に以下のコードを記載します。

以上で最低限のコーディングは終了です。 client.jsという名前をつけて保存しておきましょう。

完成したコードは以下となります（一部ご自分の環境に合わせて修正が必要です）。

kintoneアプリにJavaScript/CSSを実装する

kintoneアプリに今作成したJavaScriptファイルや、各種SDKなどを実装していきましょう。

顧客アプリの設定画面を開きます。
設定タブを開いて、その中のJavaScript / CSS でカスタマイズを選択します。

kintone UI ComponentのGitHubページから、kintone-ui-component.min.jsとkintone-ui-component.min.cssという2つのファイルをダウンロードします。
PC用のCSSファイルに、以下の順番でCSSを読み込むようにします。

PC用のJavaScriptファイルに、以下の順番でスクリプトを読み込むようにします。

順番	URL	説明
1	https://media.twiliocdn.com/sdk/js/client/v1.7/twilio.min.js	TwilioのJavaScript SDK
2	kintone-ui-component.min.js	ダウンロードしたUI ComponentのJavaScriptファイル
3	client.js	先程作成したJavaScriptファイルをアップロードします

PC用のCSSファイルに、以下のCSSを読み込むようにします。

順番	URL	説明
1	kintone-ui-component.min.css	ダウンロードしたUI ComponentのCSSファイル

画面上部の保存ボタンを押してから、アプリを更新ボタンを押します。

以上でセッティングすべて完了です。

テストする

顧客アプリを開いて、サンプルデータのいずれかの詳細画面に移動します。
TEL欄に、ご自分の電話番号を上書きします（090XXXXXXXXのようにハイフンはなしで指定してください）。
なお、トライアルアカウントでテストをする場合は、サインアップ時に認証した番号にしか発信できません。
レコードを保存したら、「発信」ボタンを押して電話がかかってくることを確認します。

デバッグ方法

kintoneのJavaScriptでなんからのエラーが出ている場合は、Chromeのコンソールログが役に立ちます。コンソールログは以下の手順で表示することができます。

Chromeブラウザの右上にある、縦に・が３つ並んだボタンを押します。
その他のツールの中にあるデベロッパーツールを選択します。

Consoleタブを開くとログが表示されます。

client.jsの中で、console.log()で記載したコメントは、この画面上に表示されます。

料金について

最後に、kintoneから電話をかけたときの料金（税込み）について説明します。

まず、kintoneからTwilioに発信をするところで0.25円/分が必要です。
その後、Twilioから外線に発信するところで、固定電話（03番号など）への発信が5.4円/分、携帯電話への発信が16.2円/分必要です。
ですので、たとえばkintoneから携帯電話に発信すると、16.45円/分がかかります。これに加えて、050番号の利用料として、108円/月が必要となります。

詳しくは、Twilioの料金ページをご確認ください。

まとめ

kintoneはJavaScriptが実行できるため、今回のようにTwilioのJavaScript SDKを使うことで、kintoneが電話機になって電話がかけられます。

kintoneとTwilioはとても相性が良いので、ぜひ色々とチャレンジしてみてください。

このTipsは、2019年4月版 kintoneで確認したものになります。

client.js (3 KB)

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

AKAZA Hisaki 2019年06月07日 11:26

わかりやすい記事ありがとうございます！

Twilioアプリをテストするときに、今までスマホのLaLa Callから発信していたんですが、

これでkintoneからTwilio使ってTwilio番号宛に発信することができたので、

PCだけで開発が完結して電話代も抑えることができましたw

一点気になったのが、Twilioがready状態になる前に

ボタンをクリックしちゃうと発信に失敗することです。

こんな風にreadyまでボタンを隠しておくと、より使いやすいかなーと思いました。

kintone.app.record.getSpaceElement('connectButtonSpace').appendChild(button.render());
button.hide();

// 中略

Twilio.Device.on('ready', device => {
  console.log('### Device ready.');
  button.show();
});

cybozu Development team 2019年06月10日 04:57

赤座久樹様

cybozu developer network事務局です。
貴重なご意見をいただき、ありがとうございます。
こちら、社内にフィードバックさせていただきます。

今後とも、cybozu developer networkをよろしくお願いいたします。

AKAZA Hisaki 2020年09月23日 02:14

こんにちはー。

1年ぶりに、こちらの手順に従って新アプリを作って試してみたところ、

「切断」ボタンを押したらすぐに「接続」が始まってしまい、

ウインドウを閉じないとまともに切断できない現象が起きてしまいました。

色々と調べてみたところ、kintone UI Componentに仕様変更があったようです。

昨年僕が試した時点では、このコミットのモジュールをDLしていました。

これだと、上記サンプルプログラムのまま普通に動きました。

https://github.com/kintone/kintone-ui-component/tree/2745910c27f5a47b4ad82db33f2f8f94d8b17c37/dist

今日時点の最新コミットはこちらですが、このモジュールをDLして使うと、

今報告した「切断後に即接続」現象が起きてしまいます。

https://github.com/kintone/kintone-ui-component/tree/ac8016f18394dfe15b3b8f987b569efb8032289c/dist

原因はこちらのようです。

冒頭でボタンにclickイベントを設定しているにも関わらず、

さらにTwilio.Device.on()のたびにボタンにclickイベントを設定しているので、

クリックするたびに「接続」「切断」イベントが積み重なって、

イベントが2つ、3つ、4つ、、、と重なって発火してしまうようでした。

      Twilio.Device.on('connect', conn => {
        console.log('### Device connected.');
        button.setText('切断');
        button.setType('submit');
        button.on('click', () => {
          buttonAction(customerNumber, button)
        });
      });

      Twilio.Device.on('disconnect', conn => {
        console.log('### Device disconnected.');
        button.setText('発信');
        button.setType('normal');
        button.on('click', () => {
          buttonAction(customerNumber, button)
        });
      });

Twilio.Device.on()内ではclickイベントを設定しないように修正すると

正しく動くようになりました。

      Twilio.Device.on('connect', conn => {
        console.log('### Device connected.');
        button.setText('切断');
        button.setType('submit');
      });

      Twilio.Device.on('disconnect', conn => {
        console.log('### Device disconnected.');
        button.setText('発信');
        button.setType('normal');
      });

サンプルコードをこのように修正していただくか、

記事内でUI Componentのバージョンを指定していただけると有り難いです。

よろしくお願いします。

AKAZA Hisakiにより編集されました 2020年09月23日 02:14

cybozu Development team 2020年09月25日 07:34

赤座様

お世話になっております。cybozu developer network 運営でございます。

記事へのフィードバックありがとうございます。
頂いた内容を元に、サンプルコードを修正致しました。

今後とも cybozu developer network をご活用いただけますと幸いです。

yoheimiyamoto 2021年02月18日 09:38

この記事の手順を確認したところ、トークン発行のTwilio Functionsには、特にACLなどの設定がされていないため、仮に、Twilio FunctionsのURLが第三者に知られた場合、トークン発行及び、なりすましの架電が行われるリスクはないでしょうか？

高橋克己 2021年02月18日 22:40

yoheimiyamotoさん、こんにちは。
KDDIウェブコミュニケーションズの高橋です。

コメントありがとうございます。ご指摘の通り、万が一トークン取得URLが外部に知られた場合は、第三者がトークンを取得することが可能です。このようなリスクを避けるためには以下の対策が有効です。

トークンURLを複雑にする
トークンの有効期限を短くする
FunctionsにAccess Control設定を行う

有効期限については記事内にも記載がありますが、デフォルトで1時間となっていますが、発信のみの運用であれば、発信直前にトークンを取得する仕組みにして、有効期限を短くすることも可能です。ただし、URLが漏洩した場合はあまり意味はないかもしれません。
3番めのAccessControlについては、以下の記事が参考になるかと思います。
https://qiita.com/mobilebiz/items/f8a8c795d5187e67166a

yoheimiyamoto 2021年02月19日 02:07

高橋さん

ご返信ありがとうございます。ご提案いただいた方法を検討してみますっ。

サインインしてコメントを残してください。