外部データ参照

2020-11-11
2023-11-07

概要

SPALOアシスタントなどのチャットアプリで回答タイプ「外部データ参照」が呼ばれると、設定されたWebhook-URL宛てに呼び出された項目名やこれまで会話で収集した情報が通知されます。

リクエスト

リクエストは下記の形式で送られます。

  • HTTP Method：POST
  • Content-Type：application/Json
  • 文字コード：UTF-8
  • タイムアウト：5秒

requestObject

パラメータ型内容
webhookKeystringWebhookのキー（固定値）。エンドポイント保護に利用します。
secretHashstringwebhook 毎の clientSecret の hash値（可変値）。エンドポイント保護に利用します。
eventstringsearch
eventTimestringイベント時刻
botNamestringボット名
item_namestringWebhook通知時の検索項目名
infoobject送信者情報（下記参照）
dataarrayセル連携ない回答タイプを含む入力済み全データ（下記参照）

info

キー型内容
userIdstringユーザーID
userNamestringユーザー名
emailstringメールアドレス

data

キー型内容
idstringセル番地
typestring回答タイプ（種類は以下参照）
titlestringシナリオ項目名
valuestring入力値（回答値）
latitudenumberGPS情報がある場合に付与
longitudenumberGPS情報がある場合に付与

回答タイプの種類

　回答タイプtype名
テキストtext
数字number
日付date
時間time
メールアドレスemail
ボタンbutton
確認ボタンconfirm
チェックボックスcheckbox
位置情報location
バーコードbarcode
画像アップロードimage
手書きcanvas

リクエストオブジェクト例

回答タイプ「外部データ参照」に、項目名「中間送信」が設定されている際、「中間送信」の項目が呼ばれた際に通知されるリクエストオブジェクトの例

{
  "webhookKey": "85126C79CBF9FE36BB9D05D0639C70C235C18D37",
  "secretHash": "$2a$10$87xh2Zrb9i0MFZPcPZRJ0uaER3C9Q6S.FrEWn6gsCvwblG43OMlE6",
  "event": "SEARCH",
  "eventTime": "2023-01-15 13:25:09",
  "item_name": "中間送信",
  "data": [
    {
      "id": "C6",
      "type": "date",
      "value": "2023年01月15日",
      "title": "作業日"
    },
    {
      "id": "C7",
      "type": "time",
      "value": "13時24分",
      "title": "開始時間"
    },
    {
      "id": "C8",
      "type": "number",
      "value": "23",
      "title": "参加人数"
    },
    {
      "id": "C12",
      "type": "address",
      "value": "アメリカ合衆国 カリフォルニア州 クパチーノ",
      "title": "現在地",
      "latitude": 37.3229978,
      "longitude": -122.0321823
    },
    {
      "id": "C21",
      "type": "image",
      "value": "gs://bungu/tmp/1839/502/original/20230115132455798.jpg",
      "title": "現場写真"
    },
    {
      "id": "C22",
      "type": "canvas",
      "value": "gs://bungu/tmp/1839/502/original/20230115132503338.png",
      "title": "署名"
    }
  ],
  "botName": "業務日報",
  "info": {
    "userId": 123,
    "userName": "鈴木一郎",
    "email": "suzuki@spalo.co.jp"
  }
}

レスポンス 200

正常系のレスポンスは、表示するデータ内容により、ボタン系と画像系の２種類をレイアウトできます。正常系のレスポンスには下記の形式でデータを返してください。

  • HTTPステータスコード：200
  • Content-Type：application/Json
  • 文字コード：UTF-8

responseObject Button

名前型備考
typestringcarousel
layoutstringbutton
actionsarray下記参照（最大データ件数：200）

actions

名前型最大文字数備考
labelstring50画面表示用
textstring50データ用
nextQuestionstring50項目名の質問にJump

レスポンス例

{  
  "type": "carousel",
  "layout": "button",
  "actions": [
     {
       "label": "営業部",
       "text": "sales"
     },
     {
       "label": "開発部",
       "text": "development"
       "nextQuestion": "項目4" <-- 「開発部」を選択した場合、次の質問は「項目4」へジャンプする
     }
   ]
}

responseObject Image

名前型備考
typestringcarousel
layoutstringimage
actionsarray下記参照（最大データ件数：10）

actions

名前型最大文字数備考
labelstring50画面表示用
textstring50データ用
uristring画像URI（画面表示用）

画像の制限

  • サイズ上限：1280 x 960
  • ファイルサイズ上限：1MB/毎
  • フォーマット：png, jpg, jpeg
  • URIプロトコル：https （httpは動作保証なし）

レスポンス例

{  
  "type": "carousel",
  "layout": "image",
  "actions": [
     {
       "label": "iPhone 12",
       "text": "iPhone12",
       "uri": "https://domain-example.jp/test/iphone12.png"
     },
     {
       "label": "iPhone 12 mini",
       "text": "iPhone12mini",
       "uri": "https://domain-example.jp/test/iphone12mini.png"
     }
   ]
}

レスポンス 400

異常系のレスポンスは、標準的なエラーのほか、独自のエラーメッセージを返すことができます。

メッセージと共に「戻って・スキップ」ボタンをチャットツールに表示します。

  • HTTPステータスコード：400
  • Content-Type：application/Json
  • 文字コード：UTF-8

responseObject

パラメータ型内容
typestringtest
textstring任意の文字列

標準エラー

return res.status(400).send();

カスタムエラー

return res.status(400).send({
  type: "text",
  text: "基幹システムを参照できませんでした。",
});
PAGE TOP