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

Bu bölümde, Actions on Google'ın Dialogflow v2 aracılığıyla karşılamanızı çağırdığı durumlarda JSON yükünün biçimi açıklanmaktadır.

Actions on Actions oluşturmak için Dialogflow'u kullanıyorsanız istek karşılama mantığınız, Actions on Google sohbet webhook'u biçimi yerine kendi standart webhook biçimi üzerinden Dialogflow ile iletişim kurar. Dialogflow webhook biçimi, görüşme webhook'u biçimine ilişkin tüm bilgilerin yanı sıra bağlamlar ve parametreler hakkındaki bilgiler gibi Dialogflow'a özgü ek verileri içerir.

Dialogflow webhook'larıyla ilgili JSON mesajlarıyla ilgili daha fazla örnek görmek için bu GitHub projesine bakabilirsiniz.

İstek içeriği

Dialogflowflow'dan gelen request mesajı, Dialogflow webhook biçiminde veriler içerir. Bu nesne, aşağıda özetlendiği gibi Actions on Google'a özgü 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 gelen istek JSON'si de dahil olmak üzere Actions on Google'a özel önemli bilgileri içerir.
  • Conversation.conversationToken alanı, Dialogflow webhook istekleri tarafından desteklenmiyor. Bunun yerine, karşılamanız gereken verileri görüşme ömrü boyunca korumak için bir Dialogflow bağımı kullanabilirsiniz.

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

Aşağıdaki snippet'te Dialogflow webhook biçiminde bir çağrı isteği örneği gösterilmektedir.

{
  "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 sohbet isteği örneği

Aşağıdaki snippet'te Dialogflow webhook biçiminde bir sohbet isteği örneği gösterilmektedir. Bu örnekte, kullanıcı girişi 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çimindeki bir yardımcı sonuç örneğini gösterir. Bu örnekte, webhook, Asistan'a kullanıcının onayını alması gerektiğini bildirdikten sonra kullanıcının verdiği yanıt gösterilmektedir.

{
  "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 giden HTTP yayınlarının başlığındaki Content-Type, application/json olmalıdır.

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

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

"google" yük nesnesi için önemli alanlar aşağıda özetlenmiştir:

Alan Açıklama
expectUserResponse Sipariş karşılamanızın bir kullanıcıdan yanıt bekleyip beklemediğini belirtir. Görüşmenin devam edeceği zaman için değeri true, görüşmeyi sonlandırmak için ise false olarak ayarlayın.
userStorage Belirli bir kullanıcıya bağlı kalıcı verileri depolar. Toplam depolama alanı miktarı 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 edinmek isterseniz Zengin yanıtlar konusuna bakın.
systemIntent Bu alan, ExpectedInput.possibleIntents ile aynı yapıya sahiptir. Sipariş karşılama işleminiz yardımcı amaç kullanıyorsa yanıtınız genellikle bir systemIntent içerir. systemIntent öğesindeki possibleIntents alanı, inputValueData alan adı data olarak değiştirilmek üzere ExpectedIntent nesnesine ayarlanmalıdır.

ExpectedIntent nesnesinin içinde şu değerleri belirtirsiniz:

  • niyet: Yardımcı için, kullanıcının sağlamasını istediğiniz bilgi türünü belirten bir amaç adı ve
  • data: Asistan'ın yardımcıyı yürütmesi için gerekli olan verileri açıklayan bir dize olan değer spesifikasyonu.

Örneğin, kullanıcının iznini istiyorsanız intent öğesini actions.intent.PERMISSSION olarak, data öğesini de bu türe ait alanlarla birlikte değer spesifikasyonunu "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" olarak ayarlayın.

Aşağıdaki listede, Dialogflow webhook yanıtı için systemIntent içinde ayarlayabileceğiniz yardımcılara yönelik değer spesifikasyonu dizeleri özetlenmektedir. Konuşma kontrolüyle ilgili Actions on Google amaçlarının tam listesi için Intents 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 alır (örneğin, evet-hayır sorusuna yanıt).
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ışı ister.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Seçilen öğeyi bir listeden veya bant kullanıcı arayüzünden elde eder.
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 elde eder.
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ışı ister.

Basit yanıt örneği

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

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

Yardımcı örneği

Aşağıdaki snippet'te Dialogflow webhook biçiminde yardımcı intent kullanmaya dair bir örnek gösterilmektedir. Bu örnekte, webhook'unuz actions.intent.OPTIONS yardımcı niyetini kullanarak Asistan'a iki seçenek arasından bir kullanıcı seçimi alma talimatı verir.

{
  "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ığında Asistan geçici olarak sohbeti devralır ve kullanıcıdan sunulan seçeneklere göre bir seçim yapmasını ister. Asistan, gerekli tüm kullanıcı girişlerini topladıktan sonra bu yardımcı sonucu Dialogflow webhook isteğindeki karşılamanıza gönderir.

Aşağıdaki snippet'te kullanıcı seçimiyle birlikte yardımcı sonucun bir ö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'te, Dialogflow webhook biçiminde bir görüşme oturumunu sonlandırmaya yönelik basit bir yanıt örneği gösterilmektedir. Yanıt mesajındaki expectUserResponse false değeri, Asistan'a başka kullanıcı girişi beklenmediğini ve mevcut görüşmeyi sonlandırması gerektiğini söyler.

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

Kullanıcılar Asistan'la 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 için görüşme çıkışları kılavuzuna bakın.