Webhookブロックのレスポンス

Webhookブロックのレスポンス

Webhookを通じて外部アプリ／システムに対して処理に関する指示（リクエスト）を送信すると、該当の外部アプリ／システムから応答（レスポンス）を受け取ります。Webhookブロックのレスポンスを設定することで、外部アプリ／システムから受け取ったレスポンスの値に対して、保存、抽出、関連付けなどの操作を行うことができます。

以下では、Webhookブロックのレスポンスの概要やメリットについて説明します。

参考情報：自動ガイドボットのWebhookブロックの概要 

レスポンスとは   

Zoho Desk、Zoho CRM、会計サービス、データベースなどの外部アプリ／システムにWebhookを通じて処理に関する指示（リクエスト）を送信すると、該当の外部アプリ／システムからリクエストに対する応答が行われます。この応答はレスポンスと呼ばれます。レスポンスには、リクエストに対する出力結果が含まれています。
例
例
たとえば、自動ガイドボットを通じてZoho CRMに保存されている顧客の情報を取得したいとします。この場合におけるZoho CRMのレスポンスの例は、以下のとおりです。

 { 
   "user": { 
     "name": "Jane Doe", 
     "email": "jane.doe@example.com", 
     "subscription_status": "Active" 
   } 
 } 

Webhookブロックのレスポンスのセクションを設定することで、取得した上記のレスポンスの情報を会話フロー内で使用することが可能です。
 

レスポンスの要素   

Webhookブロックのレスポンスには、以下の2種類の要素があります。
ステータスコード
レスポンスの値
ステータスコード
送信したリクエストの実行結果に関する、外部アプリ／システムのサーバーから出力された番号を表します。この番号をもとに、リクエストの実行結果を確認できます。
 
例
  1. 200：リクエストが処理されたことを表します。
  2. 404：リクエストの対象となるデータが見つからなかったことを表します。
  3. 500：外部アプリ／システムのサーバーでエラーが発生し、処理が行われなかったことを表します。
自動ガイドボットでは、これらのステータスコードを変数内に保存し、会話フローで使用することが可能です。

例
  1. ステータスコードが「200」の場合、リクエストの成功に関するメッセージと、レスポンスの値を表示します。
  2. ステータスコードが「404」の場合、「データが見つかりません」と表示します。
  3. ステータスコードが「500」の場合、もう一度操作を試すように促すメッセージを表示します。
レスポンスの値
名前、日付、ステータス、注文の詳細など、リクエストの対象となるデータを表します。レスポンスはさまざまな形式で送信されます。
値（単一）：

例： "userName": "John"
 

値（リスト）

例： "orders": ["#123", "#124", "#125"]
 

オブジェクト（構造データ）

例

 "user": { 
   "name": "John", 
   "email": "john@example.com" 
 } 

 

オブジェクトの配列（複数のデータ）

例
 
"tickets": [ 
   { "id": "101", "subject": "Login Issue" }, 
   { "id": "102", "subject": "Billing Error" } 
 ]

これらの値は、会話フロー内の変数に関連付けることができます。

関連付けることで、以下の処理を行うことが可能です。
  1. 値をユーザーに表示する
  2. 値を条件として使用する
  3. フォーマッターのブロックを使用して、値をまとめる／整える
 



レスポンスのメリット   

レスポンスの設定を行うメリットは、以下のとおりです。
  1. サブスクリプションのステータス、注文履歴、未完了の問い合わせなどのデータをリアルタイム表示できます
  2. ステータスコードをもとに、リクエストの実行結果を管理できます
  3. データを手動で更新せずに、システムのデータを直接表示できます
  4. 受け取ったレスポンスをもとに、会話フロー内で値の形式を整えることができます
レスポンスの値の関連付けの処理は、バックグラウンド側で行われます。この設定は、ユーザーには表示されません。レスポンスとして受け取った値の処理方法を、ボットに対して指示します。 
使用例
自動ガイドボットを通じて、ユーザーのサブスクリプションのステータスを確認したいとします。

手順1：Webhookを設定し、外部アプリ／システムからサブスクリプションのステータスのデータを取得します。

手順2：以下のレスポンスを受け取ります。
 
{ 
   "user": { 
     "name": "Talaash", 
     "subscription": "Inactive" 
   } 
 } 

手順3：自動ガイドボットのレスポンスのセクションで、以下の手順を実行します。 
  1. ステータスコードを変数「response_code」に関連付けます。
  2. レスポンスの値「user.name」を変数「user_name」に関連付けます。
  3. レスポンスの値「user.subscription」を変数「subscription_status」に関連付けます。

手順4：自動ガイドボットの条件で変数を使用します。
  1. 変数「subscription_status」によってステータスが無効と判明した場合、ユーザーにサブスクリプションを更新するように促します。
  2. ステータスが有効と判明した場合、サブスクリプションの期限を表示します。
  3. 上記のように設定することで、チャットの利用者の状況に応じてボットの回答を出力することが可能です。
この会話フロー内でフォーマッターのブロックを使用する場合、フォーマッターの出力値に応じて関連付けの設定を行う必要があります。フォーマッターに関する詳細については、こちらをご参照ください。

JSON Pointerを使用したレスポンスの関連付け

複雑な階層を持つ値がレスポンスに含まれている場合、JSON Pointerを使用することで、階層内の特定の値を抽出できます。この処理は、RFC 6901（https://www.rfc-editor.org/rfc/rfc6901.html）で定義されている仕様をもとに、Webhookブロック内で行われます。

JSON Pointerとは

JSONのレスポンス内の特定の値を示すための文字列です。「/」から始まります。また、階層を区切るためにも「/」が使用されます。

JSONのレスポンスの例
JSONのレスポンスの例
```json
{ 
   "user": { 
     "name": "John Doe", 
     "email": "john@example.com", 
     "subscription": { 
       "status": "Active" 
     } 
   } 

Pointerのパス：
  1. /user/name→ John Doe
  2. /user/subscription/status→ Active

レスポンスの値の関連付け
  1. レスポンスの変数において、JSON Pointerを使用します。例：/user/subscription/status
  2. 変数名を設定します。例：subscription_status
自動ガイドボットでは、JSON Pointerで{{...}}の構文は使用しないでください。平文のJSON Pointerのパスを使用してください（例：/user/name）。 

使用に関するヒント

レスポンスの値は、そのままだとわかりにくい場合があります。たとえば、日付の値が「2025-06-01T09:00:00Z」と表示されたり、コードの値が「subs_001_A」と表示されたりすることがあります。このような場合に、フォーマッターのブロックが役立ちます。フォーマッターのブロックを使用することで、レスポンスで取得した値の形式を整えることができます。

例
  1. レスポンスで取得した日付の値：2025-06-02T10:45:00Z
  2. フォーマッターによって形式を整えた後の値：1 June 2025, 9:00 AM

参考情報：自動ガイドボットのWebhookブロックの概要