Kompira Enterprise関連

Kompira Enterprise から Twilio で電話をかける

2017.08.01

Twilio とは電話や SMS の受発信を Web API を通じて利用できるサービスです。電話以外にも二要素認証の Authy やアプリケーションの同期を行う Sync などがあります。

今回は Twilio の電話をかける機能を利用して、Kompira Enterprise のジョブフローから指定した電話番号に対して自動音声通知をするジョブフローを作成します。

動作確認環境

ソフトウェア	バージョン
Kompira Enterprise	1.5.5.post11
OS	CentOS 7.8.2003

または

ソフトウェア	バージョン
Kompira Enterprise	1.6.2.post4
OS	CentOS 7.8.2003

Twilio の準備

Twilio を利用するためには、最初にアカウントの設定が必要です。今回は無料のトライアル版アカウントを作成します。

日本では KDDI ウェブコミュニケーションズ (KWC) 社が代理店を行っており、以下のサイトから Twilio のアカウント登録ができます。手順に従って登録してください。

https://cloudapi.kddi-web.com/signup

※ US の twilio.com の方からもアカウントを作成することができますが、日本とは別に管理されており、提供されているサービスに差があります。日本国内の電話番号にかける場合にはKWC 社のサイトからアカウントを取得してください。

※ 日本の050番の電話番号では SMS の送受信はできません。

API 認証情報の取得

アカウントを作成したら以下のように、コンソール画面の「Dashboard」から「アカウント SID」と「AUTHTOKEN」の2つの値を確認して、記録しておいてください。API を呼び出す際の認証に利用します。AUTHTOKEN は「Show」をクリックして表示させてください。

電話番号の取得

続いて通知するための電話番号を取得します。先ほどのアカウント情報の上にある「Get a Trial Number」をクリックしてください。

以下のように赤枠部分に電話番号が表示されるので、記録したら右下の「この番号を選択」をクリックしてください。

TwiML Bins の設定

TwiML は Twilio の電話の機能を設定する XML ファイルです。TwiML は Twilio 社のサーバーからアクセスできるインターネット上の Web サーバーなどに配置する必要があります。ここでは Twilio の簡易的な運用を行うための TwiML Bins の機能を利用します。

コンソール上側の検索窓に「create twiml」と入力して出てくる検索結果から、「Create TwiML Bin」をクリックしてください。

TwiML の内容を記載していきます。「FRIENDLY NAME」は TwiML の内容を識別する名前です。任意につけてください。
「TWIML」欄には、例えば以下のように記載します。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say language="ja-jp">サーバーが停止しました。急いで対応してください。</Say>
</Response>

保存したら、以下のように「Properties」に「URL」が表示されるため記録しておいてください。

ここまでで、Twilio 側の設定は完了です。

Kompira Enterprise のジョブフローの作成

続いて、Kompira Enterprise 側の設定を行います。ここでは Kompira Enterprise の組み込みジョブである「urlopen」を用いて、Twilio の API を呼び出します。

|To = "+81312345678"|
|From = "+1111122222"|
|AccountSID = "**********************************"|
|AuthToken = "********************************" |
|Timeout = 600|
|TwiMLurl = "https://handler.twilio.com/twiml/****************"|

[ 
    url = "https://api.twilio.com/2010-04-01/Accounts/${AccountSID}/Calls.json",
    dat = {
        "Url": TwiMLurl,
        "To": To,
        "From": From,
        "Timeout": Timeout
    }
] -> 

urlopen( 
    url=url,
    user=AccountSID,
    password=AuthToken,
    data=dat,
    quiet=true
) -> 

[result = json_parse($RESULT.content)] ->
 print("%{to} に電話をかけました。" % result)

「To」には電話をかける相手の番号を国番号から指定します。また電話番号先頭の0を取ります。

上の例は、日本の国番号「+81」で、「03-1234-5678」にかけることを想定しています。「+810312345678」ではないことに注意してください。
「From」には Twilio で取得した電話番号を記入します。
「AcountSID」、「AuthToken」は、それぞれ Twilio のコンソールに表示されていた文字列を記載してください。
「Timeout」は相手が電話をとるまでに呼び続ける秒数です。最大600秒まで設定できますが、受ける側が一定時間後に留守番電話設定にする場合などは、これより早く処理が終了される可能性があります。
「TwiMLurl」は、Twilio のサーバーが TwiML を取得するための URL です。今回の例では先に設定した TwiML Bins の URL を記入します。

urlopen の戻り値は辞書形式になり、レスポンスの内容を content に格納しています。この内容は、 Twilio 側の呼び出しのキューにリクエストが入れられるところまでです。したがって content には電話をかけた結果の情報はないことに注意してください。

このジョブフローを実行して、指定した電話番号に電話がかかってくれば成功です。

通話内容のカスタマイズ

ここまでで固定メッセージで相手の電話を呼び出すジョブフローができました。

次に、通知のメッセージを呼び出し時にカスタマイズしたい場合の設定を行います。
たとえばサーバー名を追加したい場合は、 TwiML Bins のテンプレートの機能を利用します。
登録されている TwiML を以下のように変更してください。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say language="ja-jp">サーバー {{Machine}} が停止しました。急いで対応してください。</Say>
</Response>

続いて、ジョブフローを以下のように変更します。

| To = "+81312345678" |
| From = "+1111122222" |
| AccountSID = "*********************************" |
| AuthToken = "********************************" |
| Timeout = 600 |
| TwiMLurl = "https://handler.twilio.com/twiml/****************" |
| Machine = "%E4%B8%80%E5%8F%B7%E6%A9%9F" | 
# 「一号機」を UTF-8 で url エンコード

[
    url = "https://api.twilio.com/2010-04-01/Accounts/${AccountSID}/Calls.json",
    dat = {
        "Url": "${TwiMLurl}?Machine=${Machine}",
        "To": To,
        "From": From,
        "Timeout": Timeout
    }
] ->

urlopen(
    url=url,
    user=AccountSID,
    password=AuthToken,
    data=dat,
    quiet=true
) ->

[result = json_parse($RESULT.content)] ->
print("%{to} に電話をかけました。" % result)

TwiML Bin を呼び出す URL に「?Machine=${Machine}」を追記しています。これによってテンプレートの {{Machine}} に変数 Machine の値が代入されて再生されます。

上記の例では「サーバー一号機が停止しました。…」と再生されます。複数のパラメータを埋め込むことも可能です。

今回の例では、指定した音声が電話口で読み上げられるシンプルな使い方をご紹介しました。
TwiML の記法を使うことで、電話を受けた人が押した電話のボタンの値を記録したり、それによって次に再生される内容を分岐することなども可能です。詳細は TwiML のドキュメントを参照してください。

本記事では TwiML を返す機能として TwiML Bins を使用しましたが、もちろん任意の Web サーバーやクラウドストレージを利用することも可能です。特に動的にメッセージの内容を変更したい場合には、 TwiML を返す Web アプリケーションを作成してください。