Pigeon チュートリアル

はじめに

Pigeonは複数人のチームに対して、誰かから応答があるまで電話連絡を順番に行うサービスです。連絡の内容は自動音声によって再生され、電話をうけた人は1～9の数字を押すことで応答内容を決めることができます。

ここでは、Pigeon における連絡内容の設定と、連絡の実行をAPI経由で行う方法をご紹介します。

連絡内容の設定

連絡内容の設定は、Kompira cloud Web画面右側の「Pigeon」メニューより行うことができます。

連絡先とコールフローの作成

まずは、電話での連絡先情報を作成しましょう。 今回は、田中さん、山田さん、斎藤さんの3人に対して順番に電話がかかるようにデータを作成してみます。Pigeonでは、このように複数人が連なった一連の連絡先を「コールフロー」と呼びます。

連絡先の作成

まず、田中さん、山田さん、斉藤さんの名前と電話番号情報をそれぞれ作成します。
以下は田中さんの電話番号情報を登録している様子です。

同じように山田さん、斎藤さんの情報を登録すると、連絡先一覧表示画面では以下のような状態となります。

続いて、田中さん、山田さん、斉藤さんが登録されたコールフローを作成しましょう。

コールフローの作成

「連絡先」にて、先ほど追加した連絡先を元にどういった順番で電話連絡をするかを決めることができます。
また、誰も応答しない場合には連絡の再試行を行いますが、最終的に連絡を何回まで行うかは「最大ループ回数」にて設定します。
（例えば「1」の場合は再試行を行わず、1回で連絡を終了します）

今回の例では、以下の順序で電話がかかることになります。

電話開始 -----+-----> 田中さん ---> 山田さん ---> 斉藤さん -->+-------------> 電話終了
             ↑                                             |
             |                                             |
             |                                             ↓  (3周していなければ戻る)
             +---------------------------------------------+

ガイダンス情報の作成

連絡前の最後の準備として、電話を受けた際に自動音声で流れる文章を作成しましょう。Pigeonではこれを「ガイダンス」と呼びます。

ガイダンスの登録をする場合、「電話を受信したらはじめに流れる音声の文章」と、その後「1～9を押した時に流れる音声の文章」をそれぞれ登録します。
まず、ガイダンス情報の登録画面を見てみましょう。

ガイダンスでは、自動音声の他に、電話機の番号（応答ボタン）を押したときの振る舞い（応答タイプ）を指定することができます。

応答タイプには以下の3種類があります。
（最低でも1つは「終了」が割り当てられた応答ボタンを設定する必要があります。）

応答タイプ 意味
終了 一連の連絡を終了させます。次の連絡先への電話連絡は行われません。
継続 コールフローの次の連絡先へ電話連絡を行います。
離脱 コールフローの次の連絡先へ電話連絡を行います。
また、次回以降のループで自分への電話連絡が行われないようになります。

電話に出なかったり、番号を押さずに電話を切った場合は「継続」と同様、次の連絡先へ電話連絡を行います。

試しに、あるサーバに障害が発生したとき、それを運用担当者に知らせるようなガイダンスを作成してみましょう。

タイミング 動作 メッセージ
電話受信時 {{server}}にて{{incident}}が発生しました。
対応される場合は1を、次の担当者に連絡する場合は2を、
次回以降この電話への連絡をスキップする場合は3を押してください。
1が選択された時 終了 1が押されました。対応をよろしくお願いいたします。
2が選択された時 継続 2が押されました。次の担当者に連絡します。
3が選択された時 離脱 3が押されました。次回以降、この電話への連絡をスキップします。

この内容で障害連絡を受けた担当者は、1を押すことで自分が対応を行う（以降の連絡が不要である）ことをPigeonに知らせ、連絡を止めることができます。 また、何らかの事情で対応が難しい場合は、2または3を押すことで次の担当者に回すことができます。

なお、「電話受信時」のメッセージに含まれる {{server}} {{incident}} といったキーワードは、連絡を実施する際に具体的な単語に置き換えて連絡をすることが出来ます。
具体的な使い方に関しては後述する「コールフローを用いて連絡をする」の内容をご覧ください。

連絡の実行

それでは、ここまでに入力したデータを使って連絡を行ってみます。連絡はAPI経由で実行します。

APIトークンの発行

Kompira cloudのAPIを使用するために、まずはAPIトークンの発行を行いましょう。

発行を行うにはブラウザからKompira cloudにアクセスし、画面右上から「設定」を開きます。

次に設定メニューより「API token」を開き、APIトークンの発行を行います。

作成されたAPIトークン文字列をコピーし、保存しておきます。

コールフロー・ガイダンスのIDを確認する

連絡を行う際に、先の手順で登録したコールフロー・ガイダンスに対して自動的に振られるIDを使用します。 IDはコールフロー・ガイダンスの個別画面より下記のように確認できます。

コールフローIDの確認方法
ガイダンスIDの確認方法

コールフローを用いて連絡をする

Pigeonでは「コールフロー」に登録された連絡先に対して、登録された順番で電話連絡を行います。 また、読み上げ文面には「ガイダンス」に登録された内容を用います。
そのため、連絡をするには「コールフロー」「ガイダンス」を1つずつ指定します。

それでは実際に自動音声による連絡を行なってみましょう。

連絡の実施 : [POST] /api/apps/pigeon/chain/invoke

POST時のJSONデータは以下のような形式で指定をします。

{
  "params": {
    "callflowId": "049de6fc-c1a7-4963-af43-616cce2492c6",
    "guidanceId": "570e6f71-5459-43fe-a745-aa7d115ce20d",
    "parameters": {
      "server": "テスト用サーバー",
      "incident": "軽度の障害"
    }
  }
}

params.parameters に指定された値は、ガイダンスで {{key}} という形式で書かれた部分に埋め込まれます。
例えば「{{server}}で{{incident}}が発生しました」というメッセージをガイダンスに登録した場合、上記のJSONデータで連絡を実行すると「テスト用サーバーで軽度の障害が発生しました」という内容が実際に読み上げられます。

以下はcurlコマンドを使ったAPI実行の例です。

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/chain/invoke \
-d '{"params":{"callflowId":"049de6fc-c1a7-4963-af43-616cce2492c6","guidanceId":"570e6f71-5459-43fe-a745-aa7d115ce20d","parameters":{"server":"テスト用サーバー","incident":"軽度の障害"}}}'

ここで、 aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789 となっている部分は、「APIトークンの発行」に記載の手順で発行したAPIトークンを設定してください。
また、 https://yourspace.cloud.kompira.jp の部分は実際にお使いいただいているKompira
cloudのスペースURLを設定してください。

APIを実行すると、以下の順で処理が進みます。

  • 田中さんに電話連絡
  • 山田さんに電話連絡
  • 斎藤さんに電話連絡
  • (田中さんに戻る)

この中で、誰かが「1」を押した時点で連絡は終了となり、以降の電話連絡は行われません。
「2」が押される、番号を押さずに電話が切られる、電話に出ない、等の場合は次の人への電話連絡を行います。

まとめ

簡単ではありますが、Pigeonによる連絡の方法をご紹介しました。

なお、連絡の実施だけでなく、連絡先・コールフロー・ガイダンスの登録・取得を含む全ての操作はWebAPIからも実施可能です。 API一覧は、APIドキュメントのPigeon カテゴリから確認することができますので、詳しくはそちらをご参照ください。

TOP