トライアル登録 ログイン

Notification APIへ公開

本記事では、Notification APIを利用するチャットボットの公開手順と簡単な利用手順について説明します。

なお、Notification APIはNotification APIオプションプランに加入することでご利用可能です。
オプションプランの詳細やお申し込み方法などについては、弊社営業担当、もしくは DialogPlay問合せ窓口 までお問い合わせください。

Notification APIの利用方法は、大きく以下の流れとなります。

1. アプリケーションの公開
2. チャットルーム一覧の取得
3. チャットルームの検索
4. チャットルームへ発言

以下のトピックで、各詳細について説明します。

1. アプリケーションの公開

DialogPlay設定画面上でチャットボットの作成を行い、アプリケーションを公開します。

項目 設定値
チャットボット公開先 任意
Notification API機能 チャットユーザーへ直接メッセージを送信するためのAPIを有効化する（チェックを入れる）

公開後に表示される『APIキー』を今後の認証で使用します。

2. チャットルーム一覧の取得

GET /channelsを使用してチャットルーム一覧を取得します。

Method: GET
Path:https://notification-api.dialogplay.jp/channels
Request headers:

{
  "x-api-key": "前項で取得したAPIキー"
}

Query parameter:
filter: filter=key:valueという形式で指定します。(※1)
limit: 指定した件数までのチャンネルを返します。(※2)

※1: フィルターに指定された値は完全一致で確認されます。
複数のフィルターを設定したい場合は filter=key1:value1&filter=key2:value2のように filterを複数回指定します。
platform_attributesのような深い階層でフィルターしたい場合はfilter=client.platform_attributes.office365.tenant_id:valueのように階層を.区切りで指定します。
※2: 件数を超過した場合は、直近で発言が行われたチャンネルを優先します。

Response body:

[
  {
    "uuid": "チャットルームのUUID",
    "accessed_at": "チャットルームにアクセスした最新の日時(発言など)",
    "client": {
      "uid": "clientのuid",
      "platform_attributes": {
        "line": {
          "external_service_user_id": "アカウント連携ID"
        },
        "office365": {
          "tenant_id": "連携中Office365アカウントのテナントID",
          "user_id": "連携中Office365アカウントのユーザーID",
        },
        "salesforce": {
          "user_id": "連携中SalesforceアカウントのユーザーID",
          "organization_id": "連携中Salesforceアカウントの組織ID"
        }
      }
    }
  }
]

3. チャットルームの検索

POST /channels/searchを使用してチャットルームの検索をします。

Method: POST
Path: https://notification-api.dialogplay.jp/channels/search
Request headers:

{
  "x-api-key": "前項で取得したAPIキー" 
}

Request body:

{
  "filter": {
    "フィルターしたいキー1": "フィルターしたい値(完全一致)",
    "フィルターしたいキー2": {
      "exists(※3)": フィルターしたいキーが存在しているかどうか(true: 存在している、false: 存在していない),
      "lt(※3)": "フィルターしたい値(小なり)",
      "lte(※3)": "フィルターしたい値(以下)",
      "gt(※3)": "フィルターしたい値(大なり)",
      "gte(※3)": "フィルターしたい値(以上)",
      "eq(※3)": "フィルターしたい値(完全一致)",
      "ne(※3)": "フィルターしたい値(不一致)"
    }
  },
  "limit": 指定した件数までのチャットルームを返します。(※4)
}

※3: フィルター用のキーexists,lt,lte,gt,gte,eq,neは任意項目です。
※4: チャットルームは最大100,000件まで取得することができます。

Response body:

[
  {
    "uuid": "チャットルームのUUID",
    "accessed_at": "チャットルームにアクセスした最新の日時(発言など)",
    "client": {
      "uid": "clientのuid",
      "platform_attributes": {
        "line": {
          "external_service_user_id": "アカウント連携ID"
        },
        "office365": {
          "tenant_id": "連携中Office365アカウントのテナントID",
          "user_id": "連携中Office365アカウントのユーザーID",
        },
        "salesforce": {
          "user_id": "連携中SalesforceアカウントのユーザーID",
          "organization_id": "連携中Salesforceアカウントの組織ID"
        }
      }
    }
  }
]

メッセージの送信を行う際はResponse bodyに含まれるuuidを使用します。

4. チャットルームへ発言

POST /channels/{uuid}/messagesを使用してチャットルームへ発言することができます。
この機能を使用して発言する場合、チャットルームにはボット発言として表示されます。

Method: POST
Path:https://notification-api.dialogplay.jp/channels/{uuid}/messages
Request headers:

{
  "Content-Type": "application/json",
  "x-api-key": "前項で取得したAPIキー"
}

Request body:

[
  {
    "type": "text",
    "content": {
      "text": "メッセージ1"
    }
  },
  {
    "type": "text",
    "content": {
      "text": "メッセージ2"
    }
  },
  {
    "type": "text",
    "content": {
      "text": "メッセージ3"
    }
  },
  {
    "type": "text",
    "content": {
      "text": "メッセージ4"
    }
  },
  {
    "type": "event",
    "content": {
      "type": "run_scenario",
      "scenario_name": "メッセージ5",
      "keep_current_scenario": true
    }
  }
]

メッセージは最大5件まで同時に送信することができます。
メッセージのフォーマットは下記を参照してください。

メッセージ:

# テキストメッセージの場合
{
  "type": "text",
  "content": {
    "text": "チャットルームへ発言する文言"
  }
}

# シナリオ実行メッセージの場合(※5)
{
  "type": "event",
  "content": {
    "type": "run_scenario",
    "scenario_name": "実行したいシナリオの名称",
    "keep_current_scenario": 実行中のシナリオに対する動作(※6)
  }
}
※5: シナリオ実行メッセージはRequestBody(メッセージ配列)の末尾にしか指定できません。
※6: trueまたはfalseを指定する。それぞれの動作は以下のとおりである。(デフォルトはfalse)
true: 指定されたシナリオの実行後に元のシナリオを再開する
false: 実行中のシナリオを終了したうえで指定されたシナリオを実行する

システム変数「@channelUUID」を用いた利用方法

システム変数として利用できる「@channelUUID」には、ユーザーが利用するチャットルームのUUIDが格納されています。
この「@channelUUID」を外部システム連携内で使用することで、社内システムなどの連携先にUUIDを渡すことができます。
連携先はそのUUID値を使用して、POST /channels/UUIDの値/messagesを実行でき、かつUUID値を用いて特定のチャットルームと社内システムとを紐づけて管理することが可能となります。

channelUUIDの値は、GET /channelsやPOST /channels/searchを利用して取得することも可能ですが、「@channelUUID」を利用して外部システム連携時に渡しておくことで、返信するたびに毎回先述のAPIで検索／取得する必要がなくなります。
また、連携側でメッセージ送信のAPIを実行する際の実装が容易となります。

例：LINEチャットボット上で問い合わせを受け付けて、問合せ内容をSalesforceやZendeskなどに連携し、その回答結果をユーザーにLINE上で返答する。

  1. 外部システム連携を利用して問合せ内容をSalesforceなどに連携する際に、「@channelUUID」を用いてチャネルUUIDをパラメータとして渡しておきます。
    notificationAPI-5-1.png
  2. 回答結果をユーザに返答する際に、手順1で取得したチャネルUUIDを指定することでNortification APIを実行することができます。
    notificationAPI-5-2.png