Migrate API calls from V1 to V2

This page details how to migrate your API calls from V1 to V2. 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 & response payloads have been changed from V1 to V2. The V2 API uses OAuth authentication instead of client/developer tokens used in the V1 API. V2 also introduces a new way to access Dialogflow's APIs: gRPC.

SDKs migration and gRPC

If you are using a V1 Dialogflow SDK, please see the SDK migration reference for the equivalent V2 SDK. V2 SDKs are available in Node.js, Python, Java, Go, Ruby, C#, and PHP. For more information, please see Dialogflow's SDK page.

Dialogflow's V2 SDKs use gRPC, which allows you to call Dialogflow's APIs more efficiently. If you make a large number of API requests to Dialogflow, your application's performance may benefit from switching from REST APIs calls to a gRPC SDK. See the SDK page for Dialogflow gRPC SDKs and gRPC.io for more information on gRPC.

REST API migration

All of Dialogflow's V1 endpoints have V2 equivalents, which are listed below. All V2 API endpoints use OAuth for authentication instead of client and developer tokens used by V1 API endpoints (see the authentication section for more).

Authentication

V1 uses client and developer tokens to access the API. V2 uses OAuth to create short-lived (1 hour) tokens from long-lived (1 year) refresh tokens. It is highly recommended that you use a tool (like the gcloud CLI) or a library (like Dialogflow's SDKs) to handle authentication.

Please see the V2 authentication setup page for instructions on how to setup OAuth and make authorized requests. If you're using a Dialogflow SDK, please see the SDK's documentation for how to set up authentication.

New V2 APIs

Agent management APIs

  • Export - Export your agent to a ZIP file (index.js and package.json not included)
  • Import - Import a ZIP file into your agent, adding any intents and entities to your agent
  • Restore - Restore a ZIP file to your agent, overwriting existing intents and entities with intents and entities from the ZIP file

Detect Intent Audio Requests

The Detect Intent (detectIntent) API replaces the /query API and adds support for audio requests. You can now send recorded and streaming audio to Dialogflow, which will be converted to text using Google's Cloud Speech API. The text will then be sent as a query to your Dialogflow agent, and you'll receive your agent's response.


REST API migration reference

This section shows how to map Dialogflow's V1 API calls to equivalent V2 API methods, fields, and objects.

V1 to V2 API methods

Below is a mapping of V1 APIs to equivalent V2 APIs:

V1 API V2 API
/query detectIntent
/entities entityTypes
/userEntities sessions.entityTypes
/intents intents
/contexts sessions.contexts

query to detectIntent

Below is a mapping of V1 API (/query) request and response fields to equivalent V2 API (detectIntent) request and response fields for retrieving your agent's response to a given query:

Request

/query request field detectIntent request field
event (e) queryInput.event
event.name queryInput.event.name
event.data queryInput.event.parameters
v Not applicable.
sessionId session (Path parameter)
lang queryInput.text.languageCode
contexts queryParams.contexts
contexts.name queryParams.contexts.name
contexts.parameters queryParams.contexts.parameters
contexts.lifespan queryParams.contexts.lifespanCount
resetContexts queryParams.resetContexts
entities queryParams.sessionEntityTypes
timezone queryParams.timeZone
location queryParams.geoLocation
location.latitude queryParams.geoLocation.latitude
location.longitude queryParams.geoLocation.longitude
originalRequest queryParams.payload

Response

/query response field detectIntent response field
id responseId
timestamp Not applicable.
lang Not applicable.
result queryResult
result.source Not applicable.
result.resolvedQuery queryResult.queryText
result.action queryResult.action
result.actionIncomplete queryResult.allRequiredParamsCollected
result.parameters queryResult.parameters
result.contexts queryResult.outputContexts
result.contexts.name queryResult.outputContexts.name
result.contexts.parameters queryResult.outputContexts.parameters
result.contexts.lifespan queryResult.outputContexts.lifespanCount
result.fulfillment queryResult.fulfillment
result.fulfillment.speech queryResult.fulfillment.text
result.fulfillment.messages queryResult.fulfillment.messages
result.score queryResult.intentDetectionConfidence
result.metadata queryResult.intent
result.metadata.intentId queryResult.intent.name
result.metadata.webhookUsed queryResult.intent.webhookState
result.metadata.webhookForSlotFillingUsed queryResult.intent.webhookState
result.metadata.webhookResponseTime queryResult.diagnosticInfo.webhookLatencySeconds
result.metadata.intentName queryResult.intent.displayName
status Status, queryResult.webhookStatus
sessionId Not applicable.

entities to entityTypes

Below is a mapping of V1 API (/entities) request fields to equivalent V2 API (entityTypes) request fields for operations that create, update, read, or delete entity types:

/entities fields (V1) entityTypes fields (V2)
id name
name displayName
entries entities
entries.value entities.value
entries.synonyms entities.synonyms
isEnum kind
automatedExpansion autoExpansionMode

userEntities to Session EntityTypes

Below is a mapping of V1 API (/userEntities) request fields to equivalent V2 API (sessions.entityTypes) request fields for operations that create, update, read, or delete session entity types:

/userEntities fields (V1) sessions.entityTypes fields (V2)
sessionId Session Id (Path parameter)
name name
extend entityOverrideMode
entries entities

intents to intents

Below is a mapping of V1 API (/intents) request fields to equivalent V2 API (intents) request fields for operations that create, update, read, or delete session entity types:

/intents fields (V1) intents fields (V2)
id name
name displayName
auto mlEnabled
contexts inputContexts
templates Not applicable.
userSays trainingPhrases
userSays.id trainingPhrases.name
userSays.data trainingPhrases.parts
userSays.data.text trainingPhrases.parts.text
userSays.data.meta trainingPhrases.entityType
userSays.data.alias trainingPhrases.parts.alias
userSays.data.userDefined trainingPhrases.parts.userDefined
userSays.isTemplate trainingPhrases.type
userSays.count trainingPhrases.timesAddedCount
responses result
responses.action result.action
responses.resetContexts result.resetContexts
responses.affectedContexts result.outputContexts
responses.affectedContexts.name result.outputContexts.name
responses.affectedContextslifespan result.outputContexts.lifespanCount
responses.parameters result.parameters
responses.parameters.name result.parameters.displayName
responses.parameters.value result.parameters.value
responses.parameters.defaultValue result.parameters.defaultValue
responses.parameters.required result.parameters.mandatory
responses.parameters.dataType result.parameters.entityTypeDisplayName
responses.parameters.prompts result.parameters.prompts
responses.parameters.isList result.parameters.isList
responses.messages result.messages
responses.defaultResponsePlatforms result.defaultResponsePlatforms
priority priority
webhookUsed webhookState
webhookForSlotFilling webhookState
fallbackIntent isFallback
cortanaCommand Not applicable.
events events
events.name Not applicable.

contexts to session contexts

Below is a mapping of V1 API (/contexts ) request fields to equivalent V2 API (sessions.contexts) request fields for operations that create, update, read, or delete session contexts:

/context fields (V1) sessions.context fields (V2)
name name
lifespan lifespanCount
parameters parameters

SDK Migration Reference

Below is a list of tables mapping Dialogflow's V1 SDKs to equivalent V2 SDKs:

V1 to V2 SDKs

V1 SDK V2 SDK
Android Java
Botkit Node.js
.NET C#
Java Java
Javascript Node.js
Node.js Node.js
Python Python
Ruby Ruby

New V2 SDKs

New V2 SDKs
PHP
Go

V1 SDKs (Legacy)

V1-only SDKs
Unity
Cordova
C++
Xamarin
Apple