قالب وب هوک Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

این بخش فرمت بار JSON را هنگامی که Actions on Google از طریق Dialogflow نسخه 2 اجرای شما را فراخوانی می کند، توضیح می دهد.

اگر از Dialogflow برای ایجاد Actions استفاده می‌کنید، اجرای شما به‌جای قالب webhook مکالمه Actions on Google از طریق قالب webhook استاندارد خود با Dialogflow ارتباط برقرار می‌کند. قالب Dialogflow webhook شامل تمام اطلاعات قالب webhook مکالمه به همراه داده های اضافی مربوط به Dialogflow است، مانند اطلاعات مربوط به زمینه ها و پارامترها.

برای مشاهده نمونه‌های بیشتری از پیام‌های JSON برای وب‌قلاب‌های Dialogflow، می‌توانید به این پروژه GitHub مراجعه کنید.

درخواست بدن

پیام درخواست از Dialogflow حاوی داده هایی در قالب وب هوک Dialogflow است. این شی شامل اطلاعات مربوط به Google Actions است که در زیر خلاصه شده است:

  • مقدار originalDetectIntentRequest.source "google" است.
  • نسخه originalDetectIntentRequest.version نشان دهنده نسخه Actions on Google برای درخواست است.
  • originalDetectIntentRequest.payload حاوی اقدامات کلیدی در مورد اطلاعات خاص Google است، از جمله درخواست مکالمه JSON از دستیار.
  • فیلد Conversation.conversationToken توسط درخواست‌های webhook Dialogflow پشتیبانی نمی‌شود. در عوض، انجام شما می‌تواند از یک زمینه Dialogflow برای تداوم داده‌ها در طول عمر مکالمه استفاده کند.

مثال درخواست فراخوان ساده

قطعه زیر نمونه ای از درخواست فراخوان را در قالب Dialogflow webhook نشان می دهد. 

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

نمونه درخواست مکالمه ساده

قطعه زیر نمونه ای از درخواست مکالمه را در قالب Dialogflow webhook نشان می دهد، که در آن ورودی کاربر یک رشته متن است. 

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

مثال نتیجه کمکی

قطعه زیر نمونه ای از یک نتیجه کمکی را در قالب وب هوک Dialogflow نشان می دهد. این مثال پاسخ کاربر را پس از اینکه webhook به دستیار نشان می‌دهد که باید تأیید کاربر را دریافت کند، نشان می‌دهد. 

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

بدن پاسخگو

Content-Type در هدر پست‌های HTTP از نقطه پایانی شما تا دستیار باید application/json باشد.

پیام پاسخی که انجام شما به Dialogflow ارسال می‌کند باید در قالب Dialogflow webhook باشد.

هنگام برقراری ارتباط با «دستیار»، پاسخ شما معمولاً حاوی یک شیء payload است که یک شی « google » را محصور می کند. شیء payload " google " شامل اطلاعات مربوط به Google Actions است. باید حداقل شامل یک فیلد expectUserResponse و یک فیلد richResponse یا systemIntent باشد.

فیلدهای کلیدی برای شی payload " google " در زیر خلاصه شده است:

میدان توضیحات
expectUserResponse نشان می دهد که آیا تحقق شما انتظار پاسخ کاربر را دارد یا خیر. زمانی که مکالمه ادامه داشته باشد مقدار true و برای پایان مکالمه مقدار false را تنظیم کنید.
userStorage داده های دائمی مرتبط با یک کاربر خاص را ذخیره می کند. حجم کل ذخیره سازی 10000 بایت است.
richResponse این فیلد حاوی صدا، نوشتار، کارت‌ها، پیشنهادها یا داده‌های ساختاری است که دستیار باید ارائه کند. برای کسب اطلاعات بیشتر در مورد استفاده از پاسخ‌های غنی برای Actions on Google، به پاسخ‌های غنی مراجعه کنید
systemIntent این فیلد همان ساختار ExpectedInput.possibleIntents را دارد. پاسخ شما معمولاً حاوی یک systemIntent است اگر تحقق شما از یک هدف کمکی استفاده می کند. فیلد possibleIntents در systemIntent باید روی یک شی ExpectedIntent تنظیم شود و نام فیلد inputValueData به data تغییر کند.

در شیء ExpectedIntent ، این مقادیر را مشخص می کنید:

  • intent : یک نام هدف برای کمک کننده که نشان دهنده نوع اطلاعاتی است که می خواهید کاربر ارائه دهد، و
  • data : یک مشخصه مقدار، که رشته‌ای است که داده‌های مورد نیاز دستیار را برای اجرای Helper توصیف می‌کند.

برای مثال، اگر از کاربر اجازه می‌خواهید، intent را روی actions.intent.PERMISSSION و data روی مشخصات مقدار روی "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" همراه با فیلدهای مربوط به آن نوع

فهرست زیر رشته‌های مشخصات مقدار را برای کمک‌کنندگانی که می‌توانید در یک systemIntent برای یک پاسخ webhook Dialogflow تنظیم کنید، خلاصه می‌کند. برای فهرست کاملی از اهداف Actions on Google برای کنترل مکالمه، به مرجع Intents مراجعه کنید.

نام قصد نام رویداد Dialogflow مشخصات ارزش توضیحات
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" تأییدیه ای از کاربر دریافت می کند (مثلاً پاسخ به سؤال بله یا خیر).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" ورودی تاریخ و زمان را از کاربر دریافت می کند.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" یک ورودی آدرس تحویل را از کاربر دریافت می کند.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" یک جریان پیوند عمیق به یک برنامه Android را درخواست می کند.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" مورد انتخاب شده را از فهرست یا رابط کاربری چرخ فلک دریافت می کند.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" اطلاعات کاربر از جمله نام کامل، مکان درشت یا مکان دقیق را به دست می آورد.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" یک جریان پیوند حساب را برای پیوند دادن حساب کاربری درخواست می کند.

نمونه پاسخ ساده

قطعه زیر نمونه ای از پاسخ ساده در قالب Dialogflow webhook را نشان می دهد. 

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

مثال کمکی

قطعه زیر نمونه ای از استفاده از یک هدف کمکی در قالب Dialogflow webhook را نشان می دهد. در این مثال، وب‌هوک شما از قصد کمکی actions.intent.OPTIONS استفاده می‌کند تا به دستیار دستور دهد تا یک انتخاب کاربر بین دو گزینه به دست آورد.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

با دریافت پیام از مثال قبلی، دستیار به طور موقت مکالمه را در اختیار می گیرد و از کاربر می خواهد که بر اساس گزینه های داده شده انتخاب کند. با جمع‌آوری تمام ورودی‌های مورد نیاز کاربر، «دستیار» این نتیجه کمکی را در یک درخواست webhook Dialogflow به انجام شما برمی‌گرداند.

قطعه زیر نمونه ای از نتیجه کمکی را با انتخاب کاربر نشان می دهد. 

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

مثال پایان مکالمه

قطعه زیر نمونه ای از یک پاسخ ساده برای پایان دادن به یک جلسه مکالمه در قالب Dialogflow webhook را نشان می دهد. مقدار expectUserResponse false در پیام پاسخ به دستیار نشان می دهد که هیچ ورودی دیگری از کاربر انتظار نمی رود و باید مکالمه فعلی را پایان دهد.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

برای یادگیری نحوه نادیده گرفتن رفتار پیش‌فرض هنگامی که کاربران یک عبارت استاندارد را برای پایان دادن به مکالمه با دستیار فراخوانی می‌کنند، به راهنمای خروج از مکالمه مراجعه کنید.