Pigeonの新しい連絡APIの機能と使いかたについて

Pigeonの連絡に使用するAPIについて、新しいAPIをリリースしました。

  • 連絡実行API
      旧：POST /api/tasks
新：POST /api/apps/chain/invoke
  • 連絡中断API
      旧：POST /api/tasks/{taskId}/abort
新：POST /api/apps/chain/abort

新しいAPIはこれまでより高機能かつ使いやすいものとなっており、本記事ではこのAPIの使用方法についてご説明いたします。 （コマンド例にて使用するデータは Pigeon チュートリアル のものに準じます）

連絡の実行：POST /api/apps/pigeon/chain/invoke

定義済みのコールフロー・ガイダンスを用いて連絡を実行する

事前定義したコールフロー・ガイダンスを用いて連絡を行うには、それぞれのID値を用いて例えば下記のデータをリクエストボディに指定してPOSTリクエストを行います。

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

curlコマンドでのリクエスト例を下記に示します。

$ 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":"軽度の障害"}}}'

リクエストを行うと、例えば下記のように「リクエストに使用したパラメータ」「連絡結果ID（成功時のみ）」「連絡の成否（requested であれば成功）」を含むレスポンスを返します。

{
  "params": {
    "callflowId": "049de6fc-c1a7-4963-af43-616cce2492c6",
    "guidanceId": "570e6f71-5459-43fe-a745-aa7d115ce20d",
    "parameters": {
      "server": "テスト用サーバー",
      "incident": "軽度の障害"
    }
  },
  "resultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "requested"
}

レスポンス中に含まれる連絡結果IDを用いて、後述する「連絡の中止」や、
既存のAPI GET /api/apps/pigeon/results/{resultId} を通した連絡結果情報の取得を行うことができます。

コールフロー・ガイダンスの内容をその場で指定して連絡を実行する（新機能）

リクエスト時に callflowId guidanceId の代わりに、使用するデータの内容を callflow guidance として指定して連絡することができます。

{
  "params": {
    "callflow": {
      "loopLimit": 3,
      "contacts": [
        {
          "displayName": "田中さん",
          "phones": [ { "phoneNumber": "0999001122" } ]
        },
        {
          "displayName": "山田さん",
          "phones": [ { "phoneNumber": "0999334455" } ]
        },
        {
          "displayName": "斎藤さん",
          "phones": [ { "phoneNumber": "0999778899" } ]
        }
      ]
    },
    "guidance": {
      "messageTemplate": "テスト用サーバーにて軽微な障害が発生しました。 対応される場合は1を、次の担当者に連絡する場合は2を、以降この電話への連絡をスキップする場合は3を押してください。",
      "reactions": {
        "1": {
          "behavior": "terminate",
          "messageTemplate": "1が押されました。対応をよろしくお願いいたします。"
        },
        "2": {
          "behavior": "continue",
          "messageTemplate": "2が押されました。次の担当者に連絡します。"
        },
        "3": {
          "behavior": "leave",
          "messageTemplate": "3が押されました。以降この電話への連絡をスキップします。"
        }
      }
    }
  }
}

上記の例ではコールフロー・ガイダンスの内容を双方とも直接指定していますが、片方はID指定にて事前登録済みのデータを使用し、もう片方は内容をその場で指定するといった形でのリクエストも可能です。

本機能により、例えば電話番号を含む名簿データを自前で管理しているシステムとの連携時に、呼び出し側でコールフローのデータ内容を生成する形をとることでPigeonへ電話番号を二重登録することを防ぐ、といった使い方が可能となります。

連絡の中止：POST /api/apps/pigeon/chain/abort

連絡の中止を行うには、連絡結果IDを用いて例えば下記のリクエストボディにてPOSTリクエストを行います。

{
  "resultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

curlコマンドでのリクエスト例を下記に示します。

$ curl -X POST -H "X-Authorization: Token aAbBcCdDeEfFgGhHiIjJkKlLmMnNoO0123456789" \
https://yourspace.cloud.kompira.jp/api/apps/pigeon/chain/abort \
-d '{"resultId":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

旧APIの今後の取り扱いについて

今後は新しいAPIを使用することを推奨し、旧APIは 非推奨 となります。
ただし、旧APIの既存機能については今後も引き続きご利用いただけますので、既にご活用いただいているものをただちに置き換えていただく必要はございません。

なお今後連絡APIへの機能追加を行う場合、その対象は原則として新APIのみになりますのでご承知おきください。

TOP