Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Overview

As of May 17, 2017, we have released an updated Conversation Webhook protocol. This refers to the HTTP request/response format sent from Actions on Google to your API.AI agent or the endpoint in your Action Package. If you created a project on or after May 17, 2017, your Assistant app will use the v2 API by default. Otherwise, you will need to migrate. This document outlines the major steps and considerations for migration.

Why do I need to migrate?

We plan to fully support the v1 API for one year. However, several key new features like visual responses and the Transactions APIs are only supported on v2. Therefore we highly recommend migrating as soon as possible.

How can I tell which API version I am using?

For API.AI users, check by going to the Actions on Google Integration settings and observing whether "Use Actions on Google Conversation API V2" is checked under "Additional settings." If the setting is not there, it means you are using the v2 API and cannot downgrade to the v1 API.

If you created your project using the old Google Developer Console, then your project is using the v1 API. If you created your project using the new Actions Console, then the API version is determined by the action package. By default, your project will use the v1 API.

What does it take to migrate?

This will vary based on whether your current app is interacting with the Conversation Webhook directly or using our Node.js client library. In general, we recommend the following steps:

  1. Import your deployed app's Developer Console project into the Actions Console
  2. Get a copy of your current app's Action Package or API.AI project export running with your newly-imported project.
  3. Modify the Action Package or API.AI project settings to use the Conversation API v2 (details below)
  4. Create a separate fulfillment server and connect it to your Action Package or API.AI project
  5. Wherever your fulfillment code uses the API directly (e.g. reads from originalRequest values in API.AI) -- modify it to use camelCase and String Enum values (as well as several other minor changes detailed below)
  6. Test your experience end to end on all supported surfaces
  7. Submit your v2 API Action Package / API.AI agent

Migration for API.AI

Client Library

We highly recommend using our updated Node.js client library. Simply change the actions-on-google dependency in your package.json to:

"actions-on-google": "^1.1.0"

And run npm install. This will take care of the lion's share of migration issues in your fulfillment code. Note that if using the getArgument() method of the library, in certain cases the returned object will contain int64 values as strings instead of numbers.

API.AI Project Changes

The Actions on Google Integration Settings determines whether your API.AI agent will receive requests in the v2 or v1 format. To toggle, perform the following steps:

  1. Ensure that your API.AI agent is associated with a project created or imported on the new Actions Console
  2. In API.AI, go to Integrations > Actions on Google card
  3. At the bottom, check or uncheck "Use Actions on Google Conversation API V2" under "Additional settings"

API.AI Webhook Protocol Changes

Request to your webhook from API.AI

The main change to the API.AI Webhook Protocol is the originalRequest.data block which contains the full HTTP request that API.AI receives from Actions on Google when your app is triggered. If your fulfillment code interacts with originalRequest directly, it will need to be updated per several schema changes. These changes are described in detail in Conversation Webhook Protocol Changes.

Response from your webhook to API.AI

data.google:

  • Camel case for names of parameters
  • systemIntent uses data instead of spec, inside is changed
  • Permission_request and is_ssml are ignored

V1 API Reference Documentation

We maintain a copy of the reference documentation for the V1 API.AI Webhook here.

Submitting your V2 API-enabled app

Please make sure your API.AI agent is associated with your deployed app. You can verify this by going to the migrated API.AI agent, clicking the Settings gear, and double-checking that the Google Project ID is consistent with the Actions Console project for your deployed app.

To submit, simply go to the Actions on Google Integration in API.AI and click Update. Then go to the Actions Console, and click Submit.

Migration for Actions SDK

Client Library

We highly recommend using our updated Node.js client library. Simply change the actions-on-google dependency in your package.json to:

"actions-on-google": "^1.1.0"

And run npm install. This will take care of the lion's share of migration issues in your fulfillment code. Note that if using the getArgument() method of the library, in certain cases the returned object will contain int64 values as strings instead of numbers.

Action Package changes

If you created your Action Package before May 17, 2017, you will need to rewrite it according to the new Action Package format. This format is documented here and you can see an example here.

Once you've rewritten your action package, you can toggle the Fulfillment API version to v2 by setting fulfillmentApiVersion to an integer value of 2. For example:

conversation {
  name: ...
  ...
  fulfillmentApiVersion: 2
}

Conversation Webhook Protocol Changes

HTTP Request from Actions on Google

The changes to the incoming HTTP request that you receive when a user interacts with your app are:

  • The JSON will be formatted using camelCase instead of snake_case
  • Enum values are passed as Strings instead of Ints. Affected values are:

    • conversation.type
    • inputs.rawInputs.inputType
  • You will receive a header "Google-Actions-API-Version" with value 2

  • Incoming intent names will be different
    • assistant.intent.actions.MAIN is now actions.intent.MAIN
    • assistant.intent.actions.TEXT is now actions.intent.TEXT
    • assistant.intent.actions.PERMISSION is now actions.intent.PERMISSION

HTTP Response to Actions on Google

The changes in your outgoing HTTP response are:

  • The JSON should be formatted using camelCase instead of snake_case
  • Enum values are passed as Strings instead of Ints. Affected values are:
    • expectedInputs.possibleIntents.inputValueSpec.permissionValueSpec.permissions
    • expectedInputs.possibleIntents.inputValueData.permissions
  • Permission helper intent changes

    v2

    "possibleIntents": [
       {
         "intent": "actions.intent.PERMISSION",
         "inputValueData": {
           "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec",
           "optContext": "To deliver your order",
           "permissions": [
             "NAME",
             "DEVICE_PRECISE_LOCATION"
           ]
         }
       }
    ]
    

    v1

       "possibleIntents": [
            {
             "intent": "assistant.intent.actions.PERMISSION",
             "input_value_spec": {
               "permission_value_spec": {
                 "opt_context: "To deliver your order",
                 "permissions": [
                   "NAME",
                   "DEVICE_PRECISE_LOCATION
                 ]
               }
             }
            }
        ]
  • Outgoing intent names will be different
    • assistant.intent.actions.MAIN is now actions.intent.MAIN
    • assistant.intent.actions.TEXT is now actions.intent.TEXT
    • assistant.intent.actions.PERMISSION is now actions.intent.PERMISSION

V1 API Reference Documentation

We maintain a copy of the reference documentation for the V1 Conversation API here.

Submitting your V2 API-enabled app

After you've tested your migrated app end-to-end, submit via gactions as follows:

gactions submit --action_package myv2AP.json --project myDeployedProjectID