Dialogflow webhook biçimi {:#dialogflow-webhook-format} (Dialogflow)

Bu bölümde, Actions on Google tarafından Dialogflow v2 üzerinden çağrıldığında JSON yükünün biçimi açıklanmaktadır.

İşlemler oluşturmak için Dialogflow'u kullanıyorsanız sipariş karşılama işleminiz, Actions on Google görüşme webhook biçimi yerine kendi standart web kancası biçimi üzerinden Dialogflow ile iletişim kurar. Dialogflow webhook biçimi, görüşme webhook'u biçimiyle ilgili bilgilerin yanı sıra bağlamlar ve parametrelerle ilgili bilgiler gibi Dialogflow'a özel ek veriler içerir.

Dialogflow webhook'ları için JSON mesajlarının daha fazla örneğini görmek isterseniz bu GitHub projesine bakabilirsiniz.

İstek içeriği

Dialogflow'dan gelen request mesajı, Dialogflow webhook biçiminde veri içerir. Bu nesne, aşağıda özetlendiği gibi Actions on Google'a özel bilgileri içerir:

  • originalDetectIntentRequest.source değeri "google"dır.
  • originalDetectIntentRequest.version, isteğin Actions on Google sürümünü gösterir.
  • originalDetectIntentRequest.payload, Asistan'dan JSON görüşü de dahil olmak üzere Actions on Google'a özel önemli bilgiler içerir.
  • Conversation.conversationToken alanı, Dialogflow webhook istekleri tarafından desteklenmiyor. Bunun yerine, karşılamanız görüşme süresince verilerin korunması için bir Dialogflow bağlamı kullanabilir.

Basit çağrı isteği örneği

Aşağıdaki snippet, Dialogflow webhook biçiminde bir çağrı isteği örneğini göstermektedir.

{
  "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}"
}

Basit görüşme isteği örneği

Aşağıdaki snippet'te, Dialogflow webhook biçiminde bir konuşma isteği örneği gösterilmektedir. Burada kullanıcı girişi bir metin dizesidir.

{
  "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}"
}

Yardımcı sonuç örneği

Aşağıdaki snippet, Dialogflow webhook biçiminde bir yardımcı sonuç örneği göstermektedir. Bu örnek, webhook'un Asistan'a kullanıcının onayını alması gerektiğini söylemesinden sonra kullanıcının yanıtını gösterir.

{
  "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}"
}

Yanıt gövdesi

Karşılama uç noktanızdan Asistan'a yapılan HTTP gönderilerinin başlığında yer alan Content-Type, application/json olmalıdır.

Sipariş karşılamanızın Dialogflow'a gönderdiği yanıt mesajı, Dialogflow webhook biçiminde olmalıdır.

Asistan ile iletişim kurarken yanıtınız genellikle "google" nesnesini kapsayan bir payload nesnesi içerir. "google" yük nesnesi, Actions on Google'a özel bilgileri içerir. En azından bir expectUserResponse alanı ve bir richResponse veya systemIntent alanı içermelidir.

"google" yük nesnesinin önemli alanları aşağıda özetlenmiştir:

Alan Açıklama
expectUserResponse Sipariş karşılamanızın kullanıcı yanıtı bekleyip beklemediğini belirtir. Sohbeti devam ettirmek için true değerini ve görüşmeyi sonlandırmak için false değerini ayarlayın.
userStorage Belirli bir kullanıcıya bağlı kalıcı verileri depolar. Toplam depolama alanı 10.000 bayttır.
richResponse Bu alan, Asistan'ın oluşturması için ses, metin, kart, öneri veya yapılandırılmış veri içerir. Actions on Google için zengin yanıtları kullanma hakkında daha fazla bilgi için Zengin yanıtlar bölümüne bakın
systemIntent Bu alanın yapısı ExpectedInput.possibleIntents ile aynıdır. Sipariş karşılamanız bir yardımcı amacı kullanıyorsa yanıtınız genellikle systemIntent içerir. systemIntent içindeki possibleIntents alanı bir ExpectedIntent nesnesi olarak ayarlanmalıdır (inputValueData alan adı data olarak değiştirilir).

ExpectedIntent nesnesinde şu değerleri belirtirsiniz:

  • intent: Yardımcı olarak, kullanıcının sağlamak istediğiniz bilgi türünü gösteren amaç adı ve
  • data: Asistan'ın yardımcıyı yürütmesi için gereken verileri açıklayan bir dize olan değer spesifikasyonu.

Örneğin, kullanıcının iznini istiyorsanız intent değerini actions.intent.PERMISSSION ve data değerini de bu tür alanlarla birlikte "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" olarak ayarlayın.

Aşağıdaki listede, Dialogflow webhook yanıtı için systemIntent ile ayarlayabileceğiniz yardımcılar için değer spesifikasyonu dizeleri özetlenmektedir. Actions on Google'ın diyalog kontrolüyle ilgili niyetlerinin tam listesi için Niyetler referansına bakın.

Amaç Adı Dialogflow Etkinlik Adı Değer Spesifikasyonu Açıklama
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Kullanıcıdan onay alma (ör. "Evet" veya "Hayır" yanıtını verme).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Kullanıcıdan tarih ve saat girişi alır.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Kullanıcıdan teslimat adresi girişi alır.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Bir Android uygulamasına derin bağlantı akışı isteğinde bulunur.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Bir öğeyi listeden veya bant kullanıcı arayüzünden alır.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Tam ad, yaklaşık konum veya tam konum dahil olmak üzere kullanıcının bilgilerini alır.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Bir kullanıcının hesabını bağlamak için hesap bağlama akışı istenir.

Basit yanıt örneği

Aşağıdaki snippet, Dialogflow webhook biçiminde basit bir yanıt örneği göstermektedir.

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

Yardımcı örnek

Aşağıdaki snippet, Dialogflow webhook biçiminde yardımcı amacı kullanma örneğini göstermektedir. Bu örnekte webhook'unuz, Asistan'a iki seçenek arasında kullanıcı seçimi almasını belirtmek için actions.intent.OPTIONS yardımcı amacını kullanır.

{
  "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"
              }
            ]
          }
        }
      }
    }
  }
}

Önceki örnekte verilen mesajı aldığınızda Asistan, konuşmayı geçici olarak devralır ve kullanıcıdan belirtilen seçeneklere göre bir seçim yapmasını ister. Asistan, gerekli tüm kullanıcı girişlerini toplarken bu yardımcı sonucu bir Dialogflow webhook isteğindeki karşılamanıza geri gönderir.

Aşağıdaki snippet'te, kullanıcı seçimine sahip yardımcı sonuç örneği gösterilmektedir.

{
  "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}"
}

Görüşmeyi sonlandırma örneği

Aşağıdaki snippet, Dialogflow webhook biçiminde bir görüşmeyi sonlandırmak için basit bir yanıt örneğini göstermektedir. Yanıt mesajındaki false öğesinin expectUserResponse değeri, Asistan'a başka bir kullanıcı girişinin beklenmediğini ve mevcut görüşmeyi sonlandırması gerektiğini bildirir.

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

Kullanıcılar Asistan ile görüşmeyi sonlandırmak için standart bir ifade çağırdığında varsayılan davranışı nasıl geçersiz kılacağınızı öğrenmek istiyorsanız görüşme çıkışları rehberine bakın.