Migrate to Dialogflow API V2

Dialogflow has deprecated API V1 and will be shutting down API V1 on October 23th, 2019. In order to make sure your Action keeps working after October 23th, 2019, you need to migrate to Dialogflow’s API V2. Here’s how to migrate:

• If you do not use fulfillment for your Action, you can migrate to API V2 today in Dialogflow’s console.
• If you use v2.X of Actions on Google’s client library, you can migrate to Dialogflow API v2 today in Dialogflow’s console. Actions on Google’s v2 client library is compatible with Dialogflow v2.
• If you are using v1.X of Actions on Google’s client library, please migrate to v2 of Actions on Google client library (migration guide). Then, you can safely migrate to Dialogflow API V2 in Dialogflow’s console.
• If you are using fulfillment without Actions on Google’s client library, please see the JSON guide below for instructions on how to alter your webhook requests and responses to support Dialogflow’s API V2.

Fulfillment JSON requests and responses

The format of Dialogflow webhook requests and the expected responses to the request have changed between API V1 and API V2. Please note that when you change from API V1 to API V2 in Dialogflow’s console, the webhook request and expected response format will change as indicated below.

Note: v2 of Actions on Google’s Node.js client library handles webhook requests and responses for both Dialogflow API V1 and API V2. We highly recommend using Actions on Google’s client library if migrating from Dialogflow API V1 to API V2.

Webhook request

Dialogflow API V2 webhook requests change the name and location of several fields, including a user’s original query, the matched intent, parameters, and language. The location of Actions on Google-specific information in the request has changed, but the content of the Actions on Google payload does not change. You can see the general change in structure below:

// Dialogflow API V1 webhook request
{
  "result": {
    "resolvedQuery": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {..},
    "actionIncomplete": false,
    "contexts": [...],
    "metadata": {
      "intentName": "Name of Dialogflow Intent",
      ...
    },
    "score": 1,
    ...
  },
  "lang": "en-us",
  "originalRequest": {
    "source": "google",
    "version": "2",
    "data": {
      // Actions on Google-specific information here
    }
  },
  ...
}

You can see a full example of a Dialogflow API V1 webhook request here.

// Dialogflow API V2 webhook request
{
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {...},
    "allRequiredParamsPresent": true,
    "outputContexts": [...],
    "intent": {
      "displayName": "Name of Dialogflow Intent",
      ...
    },
    "intentDetectionConfidence": 1,
    "languageCode": "en-us",
    ...
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      // Actions on Google-specific information here
    }
  },
  ...
}

You can see a full example of a Dialogflow API V2 webhook request here.

See this Github repo for examples of API V1 and API V2 Dialogflow webhook requests that are sent when ending a conversation, welcoming the user, and more.

Webhook response

Changes for Actions on Google responses to webhook requests are minimal from Dialogflow API V1 to V2. In Dialogflow API V1, the response to Actions on Google would be in the data.google JSON object returned to Dialogflow; in V2, the same response to Actions on Google is now in the payload.google JSON object, as seen below:

// Dialogflow API V1 webhook response
{
  "data": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

You can see a full example of a Dialogflow API V1 webhook response here.

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

You can see a full example of a Dialogflow API V2 webhook response here.

See this Github repo for examples of API V1 and API V2 Dialogflow webhook responses to send rich responses, end a conversation, ask for permissions & sign-in, and more.

Next steps

If you use other integrations in addition to Actions on Google, please see Dialogflow’s migration guide.

If you have any questions, please post them on Stack Overflow or on our Google+ community.