Migrate from API V1 to API V2

Dialogflow's V2 API is now generally available. V2 adds new features like audio requests, a new enterprise edition, and a more efficient way to call Dialogflow APIs (gRPC). This page is an overview of what is required to switch from V1 to V2.

What's new in V2?

Dialogflow's V2 API has added some new features not available in Dialogflow's previous version:

  • Audio Request Support You can now send Dialogflow recorded or streaming audio to allow your users to talk to your agent directly
  • Agent Management APIs These new APIs allow you to import, export, and restore your Dialogflow agents with API calls
  • Enterprise Edition Dialogflow's enterprise edition offers features like a service level agreement, eligibility for Google Cloud support, and Google Cloud's terms of service

Quotas and limits

All quotas below are per agent.

Feature API V1 API V2*
Text requests per minute** 180 180
Audio requests per minute** N/A 100
Audio requests per day N/A 1,000
Audio requests per month N/A 15,000
Maximum audio length per request N/A 60 seconds
All other requests per minute (editing intents, etc.) 60 60

* For Standard agents. See more on Enterprise quota comparisons.

** See the Standard and Enterprise quota page for more information.

How do I switch?

Before you switch your Dialogflow agent's API version from V1 to V2, you must first ensure your API calls and fulfillment are compatible with Dialogflow's V2 API. If you are unsure if you're utilizing Dialogflow's fulfillment or APIs, see this section. If you are using Dialogflow's fulfillment webhook, inline editor, or any Dialogflow APIs, you'll need to update your code, endpoints, and/or fulfillment to be compatible with V2. The remainder of this section outlines the three areas you may need to change before you migrate: the console, fulfillment, and APIs. The next section (Migration Best Practices) provides direction on how to migrate your agent in various scenarios.

Console

If you've only used the console on http://dialogflow.com, and don't utilize fulfillment or Dialogflow's APIs, you don't need to make any changes. Existing agents that don't utilize any APIs or have fulfillment won't be affected by moving to V2.

Switch your agent from V1 to V2

To switch your agent from V1 to V2, go to your agent's settings and scroll down to the API Version section. Select the V2 API radio button, acknowledge the pop-up, and click Save:

Switch API Version

Fulfillment

If you use Dialogflow fulfillment, you'll need to make sure you respond correctly to Dialogflow's webhook requests when migrating from API V1 to API V2. Both the webhook requests you receive from Dialogflow and the proper responses to those webhook requests will be different for Dialogflow V1 and V2.

Dialogflow's fulfillment library and the Action on Google V2 client library for Node.js support both Dialogflow V1 and V2 webhook requests and responses. After migrating to either library, your fulfillment can seamlessly migrate from V1 to V2 because both libraries support Dialogflow V1 and V2 webhook requests & responses.

For detailed information on how to migrate your fulfillment from V1 to V2, please see the V1 to V2 fulfillment migration page.

Dialogflow APIs

Dialogflow API endpoints, methods, and authentication have changed from V1 to V2 for all Dialogflow APIs. Dialogflow's base API URL, all method names, and all request and response JSON payloads have been changed from V1 to V2. The V2 API uses OAuth authentication instead of client/developer tokens used in the V1 API. For detailed information on how to migrate your API calls from V1 to V2, please see the V1 to V2 API migration page.

gRPC

Dialogflow's V2 API introduces a new gRPC API, which allows you to call Dialogflow's HTTP REST APIs more efficiently. gRPC allows for streaming requests and uses HTTP/2 and efficient binary encoding for transportation, which allows for rapid request construction and response parsing. gRPC requires client libraries to make requests and receive responses. For more information, please see Dialogflow's SDK page.


Migration best practices for production agents

This section describes techniques to migrate your Dialogflow agent if your agent is actively serving your users in production. If you are just testing Dialogflow and aren't serving users, you can switch from API V1 to V2 now, but be aware that fulfillment and API calls may stop working.

To know how to best migrate your production Dialogflow agent from V1 to V2, you first need to know what Dialogflow features your agent is utilizing. The most important features for migration purposes are integrations, fulfillment, and Dialogflow APIs. Please take a moment to check if your Dialogflow agent uses integrations, fulfillment, and/or APIs to see which section below applies to your agent.

Migrate fulfillment or APIs with integrations

If your Dialogflow agent uses integrations as well as Dialogflow APIs and/or fulfillment, the following procedure is the recommended way to migrate your production agent from V1 to V2:

  1. Create a test version of your production agent
  2. Switch your test agent to use API V2
  3. Set up the same integrations active on your production agent on your test agent
  4. Update your code to make your fulfillment and API calls compatible with both V1 and V2 (or use the Node.js Dialogflow fulfillment library)
  5. Test your test agent on all integrations and on API V1 and V2 (switching between API V1 and V2 on your test agent as necessary for testing), then validate
  6. Update your fulfillment and API calls backend to fulfill/call your production agent
  7. Switch your production agent from V1 to V2

Migrate fulfillment or APIs with no integrations

If your Dialogflow agent does not use integrations but uses Dialogflow APIs and/or fulfillment, the following procedure is the best way to migrate your production agent from V1 to V2:

  1. Create a V2 version of your production agent
    1. Export your existing V1 production agent
    2. Create a new agent
    3. Restore your product agent ZIP file to the new agent
  2. Switch your new agent to V2
  3. Create fulfillment and a backend that makes Dialogflow API calls work with your V2 agent
  4. Test fulfillment on your new V2 agent and verify that the behavior matches your V1 agent
  5. Switch your production systems to point from from your old V1 agent to your new V2 agent

Migrate integrations only

If you only use Dialogflow integrations and do not utilize fulfillment or Dialogflow's APIs, you can safely switch from V1 to V2 in Dialogflow's console.


Check if your agent is using fulfillment or APIs

Does my agent use fulfillment?

Open your agent's fulfillment page and see if either of the switches next to Webhook or Inline Editor are set to enabled. If the page looks like the screenshot below, your agent does not use fulfillment. If either the Webhook or Inline Editor switches are enabled, your Dialogflow agent uses fulfillment.

Check to see if fulfillment is enabled

Does my agent use Dialogflow APIs?

If you make any HTTP calls with your agent's client or developer token to URLs starting with https://api.dialogflow.com/V1/, you are using Dialogflow APIs. Valid HTTP APIs call to any of the following APIs mean you are using Dialogflow's V1 APIs:

Check if your agent is using integrations

Open your agent's integrations page and see if either of the switches are set to enabled. If the page looks like the screenshot below, and all the other integration switches are disabled, your agent does not use integrations. If any of the integration switches are set to enabled, your Dialogflow agent uses fulfillment.

Check to see if any integration is enabled

The Google Assistant integration is enabled on all Dialogflow projects. If you are unsure if your agent uses the Google Assistant integration, click on Integration Settings on the Google Assistant integration and then Manage Assistant app. This will open up the Actions on Google console. If your Actions' most recent deployment state is Under Review or Published, your Dialogflow agent is actively using the Google Assistant integration.