Pigeon (ベータ版) チュートリアル

はじめに

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

ここでは、Kc Pigeon (ベータ版) における架電内容の設定と、架電の実行をAPI経由で行う方法をご紹介します。

※ Kc Pigeonは現在ベータ版での公開であり、次期バージョンではAPIのURLやデータの構造、架電の挙動などが変更される可能性があります。
※ 本チュートリアルを実施するには初期設定が必要となりますので、ご利用希望の場合はお問い合わせフォームよりその旨ご連絡ください。

Kompira cloud お問い合わせフォーム
https://www.fixpoint.co.jp/cloudcontact/

APIトークンの作成

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

ブラウザからKompira cloudにアクセスし、画面右上の全体設定 > APIトークンから、APIトークンの作成をすることができます。

f:id:kompiracloud:20190206150550p:plain:w600

f:id:kompiracloud:20190206150639p:plain:w600

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

組織情報の確認

Kc Pigeonでは、電話連絡先や架電履歴など、全ての情報は組織という単位の下に作成されます。

組織の一覧取得 : [GET] /api/apps/pigeon/organizations

まずはcurlコマンドを使って以下のようにAPIを実行し、組織の情報を確認しましょう。

$ curl -X GET -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations

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

$ curl -X GET -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations | jq .
{
  "offset": 0,
  "limit": 30,
  "total": 1,
  "items": [
    {
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "テスト組織",
      "ivrConfigId": "6ff6628d-4b68-4fa1-a0bd-66e72c20cb33",
      "createdAt": "2019-01-30T07:09:03Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedAt": "2019-01-30T07:09:03Z",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    }
  ]
}

初期状態では、1つの組織が作成された状態となっています。 このうち、 organizationId の値を保存しておいてください。

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

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

連絡先の作成 : [POST] /api/apps/pigeon/organizations/{organizationId}/contacts

まず、田中さん、山田さん、斉藤さんの名前と電話番号情報をそれぞれ作成します。 {organizationId} の部分には、組織情報を取得した時に保存しておいた organizationId の値を入れてください。 POST時のJSONデータは以下のような形式で指定をします。

{
  "displayName": "田中一郎", 
  "phoneNumber": "01234567890"
}

以下は、具体的にcurlコマンドで指定する例です。

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/contacts -d '{"displayName": "田中一郎", "phoneNumber": "01234567890"}'
$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/contacts -d '{"displayName": "山田隆", "phoneNumber": "00011112222"}'
$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/contacts -d '{"displayName": "斉藤正", "phoneNumber": "00088885555"}'

作成した連絡先の一覧は、 以下のように取得することができます。

連絡先の一覧取得 : [GET] /api/apps/pigeon/organizations/{organizationId}/contacts

$ curl -X GET -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/contacts | jq .
{
  "offset": 0,
  "limit": 30,
  "total": 3,
  "items": [
    {
      "contactId": "460c31ee-c08e-4d1c-8e5c-fef14f175bde",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "斉藤正",
      "phoneNumber": "00088885555",
      "createdAt": "2019-01-30T07:34:06Z",
      "updatedAt": "2019-01-30T07:34:06Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    },
    {
      "contactId": "74af07c4-0d3a-4403-928d-74fa9f1a003c",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "山田隆",
      "phoneNumber": "00011112222",
      "createdAt": "2019-01-30T07:33:27Z",
      "updatedAt": "2019-01-30T07:33:27Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    },
    {
      "contactId": "e7428b21-da0e-4425-8cf7-1f65e7d95e07",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "田中一郎",
      "phoneNumber": "01234567890",
      "createdAt": "2019-01-30T07:32:31Z",
      "updatedAt": "2019-01-30T07:32:31Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    }
  ]
}

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

コールフローの作成 : [POST] /api/apps/pigeon/organizations/{organizationId}/callflows

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

{
  "displayName": "チーム1",
  "escalations": [
    {"contactId": "e7428b21-da0e-4425-8cf7-1f65e7d95e07"},
    {"contactId": "74af07c4-0d3a-4403-928d-74fa9f1a003c"},
    {"contactId": "460c31ee-c08e-4d1c-8e5c-fef14f175bde"}
  ]
}

以下の例では、 escalations キーに対して田中さんのcontactId、山田さんのcontactId、斉藤さんのcontactIdを指定しています。

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/callflows \
-d '{"displayName": "チーム1", "escalations": [{"contactId": "e7428b21-da0e-4425-8cf7-1f65e7d95e07"}, {"contactId": "74af07c4-0d3a-4403-928d-74fa9f1a003c"},  {"contactId": "460c31ee-c08e-4d1c-8e5c-fef14f175bde"}]}' | jq .

{
  "callflowId": "bf72caa6-34fa-4032-aaa1-cf6136c9a9a5",
  "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
  "displayName": "チーム1",
  "escalations": [
    {
      "contactId": "e7428b21-da0e-4425-8cf7-1f65e7d95e07",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "田中一郎",
      "phoneNumber": "01234567890",
      "createdAt": "2019-01-30T07:32:31Z",
      "updatedAt": "2019-01-30T07:32:31Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    },
    {
      "contactId": "74af07c4-0d3a-4403-928d-74fa9f1a003c",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "山田隆",
      "phoneNumber": "00011112222",
      "createdAt": "2019-01-30T07:33:27Z",
      "updatedAt": "2019-01-30T07:33:27Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    },
    {
      "contactId": "460c31ee-c08e-4d1c-8e5c-fef14f175bde",
      "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
      "displayName": "斉藤正",
      "phoneNumber": "00088885555",
      "createdAt": "2019-01-30T07:34:06Z",
      "updatedAt": "2019-01-30T07:34:06Z",
      "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
      "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
    }
  ],
  "createdAt": "2019-01-30T08:25:52Z",
  "updatedAt": "2019-01-30T08:25:52Z",
  "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
  "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
}

作成すると、 callflowId が生成されるので、これを保存しておきます。

ガイダンス情報の作成

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

ガイダンスの登録をする場合、「電話を受信したらはじめに流れる音声の文章」と、その後「1~9を押した時に流れる音声の文章」をそれぞれ登録します。 今回は、あるサーバに障害が発生したとき、それを運用担当者に知らせるようなガイダンスを作成してみましょう。

タイミング 動作
電話受信時 サーバ{{server}}にてインシデント{{incident}}が発生しました。対応される場合は1を、次の担当者に連絡する場合は2を押してください。
1が選択された時 1が押されました。対応をよろしくお願いいたします。
2が選択された時 2が押されました。次の担当者に連絡します。

ガイダンスの作成 : [POST] /api/apps/pigeon/organizations/{organizationId}/guidances

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

{
  "displayName": "サーバの障害通知",
  "messageTemplate": "サーバー{{server}}にてインシデント{{incident}}が発生しました。対応される場合は1を、次の担当者に連絡する場合は2を押してください。",
  "replies": {
    "1": {
      "messageTemplate": "1が押されました。対応をよろしくお願いいたします。",
      "behavior": "terminate"
    },
    "2": {
      "messageTemplate": "2が押されました。次の担当者に連絡します。",
      "behavior": "continue"
    }
  }
}

behavior というキーは、1~9が押されたときにどのような動作をするかを指定する値です。

terminate と指定すれば架電はそこで終了となり、 continue と指定すればコールフローの次の人に架電が行われます。

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/callflows \
-d '{"displayName": "サーバの障害通知", "messageTemplate": "サーバ{{server}}にてインシデント{{incident}}が発生しました。対応される場合は1を、次の担当者に連絡する場合は2を押してください。", "replies": { "1": { "messageTemplate": "1が押されました。対応をよろしくお願いいたします。", "behavior": "terminate" },  "2": { "messageTemplate": "2が押されました。次の担当者に連絡します。", "behavior": "continue" }}} | jq .

{
  "guidanceId": "b1510cf0-3b10-4833-8733-049d7b409dc3",
  "organizationId": "e83d4da9-b999-4dbe-bb1f-224b5ee80cda",
  "displayName": "サーバの障害通知",
  "messageTemplate": "サーバー{{server}}にてインシデント{{incident}}が発生しました。対応される場合は1を、次の担当者に連絡する場合は2を押してください。",
  "replies": {
    "1": {
      "messageTemplate": "1が押されました。対応をよろしくお願いいたします。",
      "behavior": "terminate"
    },
    "2": {
      "messageTemplate": "2が押されました。次の担当者に連絡します。",
      "behavior": "continue"
    }
  },
  "createdAt": "2019-01-30T09:08:30Z",
  "updatedAt": "2019-01-30T10:02:16Z",
  "createdBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc",
  "updatedBy": "fb99fb56-556b-4bc1-b627-e0e58b2265dc"
}

作成すると、guidanceId が生成されるので、これを保存しておきます。

コールフローに架電をする

では、いよいよ自動音声による電話をかけてみましょう。 電話の架電は、これまでに作成したコールフローとガイダンスを1つずつ指定することで行います。 「コールフロー」で定義したメンバーに、「ガイダンス」で定義した内容で電話をする、ということです。

連絡処理の実施 : [POST] /api/apps/pigeon/organizations/{organizationId}/processes

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

{
  "callflowId": "bf72caa6-34fa-4032-aaa1-cf6136c9a9a5",
  "guidanceId": "b1510cf0-3b10-4833-8733-049d7b409dc3",
  "parameters": {
    "server": "テスト用サーバー",
    "incident": "軽度の障害"
  }
}

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

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/organizations/e83d4da9-b999-4dbe-bb1f-224b5ee80cda/processes \
-d '{"callflowId": "bf72caa6-34fa-4032-aaa1-cf6136c9a9a5", "guidanceId": "b1510cf0-3b10-4833-8733-049d7b409dc3", "parameters": {"server": "テスト用サーバー", "incident": "軽度の障害"}}'

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

  • 田中さんに自動電話架電
  • 山田さんに自動電話架電
  • 斎藤さんに自動電話架電

この中で、誰かが「1」を押すと、架電はその時点で終了となり、次の人への架電は行われません。 「2」が押されたり、電話に出なかったりした場合は次の人への架電を行います。

まとめ

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

API一覧は、APIドキュメントPigeon カテゴリから確認することができます。