Google Direct Actions Packages
Published in
12 min readMar 1, 2017
Direct Action packages are persistent and developer can only have one Preview for an Action Package.
The ActionPackage is the main operation unit developer works on, it’s the home of list of actions, 3P agents want to support to extend Google Assistant capabilities. It mainly includes triggering grammars, authentication info, cloud endpoint and other application level metadata such as access control.
The list of actions the agent is able to handle represents what a specific conversation agent supports, it can be a single shot action, or a multi-step conversation.
An “initialTrigger” is used to define an intent and is associated to query patterns which are used to indicate the query patterns used to invoke this agent, something like:
“order a coffee”
Note that for Assistant V1 to trigger the agent user needs to include agent invocation name too:
“order a coffee with Starbucks”
matches user’s queries. It can be used for both initial trigger, and follow-on queries.
The programmable queries list all patterns used to identify the specified intent. A QueryPattern is an annotated instance of a developer provided example, or a query pattern. As of August 2016, only query patterns are supported.
The query pattern is a string, it represents the instance that would be used to match to user’s phrases, e.g.,
“book a table at $Restaurant:restaurant”
The intent indicates the intent of this query match:
“BOOK_A_TABLE”
The HTTP endpoint for the 3P agent, can be a Google Cloud Function endpoint or a self-hosting HTTP endpoint. Assistant sends a POST request to exchange data with 3P.
“signInRequired” Indicates whether sign-in is required for this action. Note this is valid only when agent has AccountLinking specified inside AgentInfo.
“description” is the English description of what the action does. This is mainly used for Google to review the action or debugging purpose. It won’t be surfaced to users. It must be less than 100 ASCII letters.
“inDialogTriggers” triggers after the user is interacting with the agent.
Specifying these in the action is optional — they can be referred to from speech.
Source:
>>> print(build(serviceName='assistant', version='v1', http=GoogleUser.objects.first().credential.authorize(httplib2.Http()), developerKey='notasecret').actionPackages().create.__doc__)The created Action Package will be persistent. Developer can only have one Preview for an Action Package.Args:
body: object, The request body. (required)
The object takes the form of:{ # ActionPackage is the main operation unit developer works on, it's the home
# for list of actions 3P agent wants to support to extend Google Assistant
# capabilities. It mainly includes triggering grammars, authentication info,
# cloud endpoint and other application level metadata such as access control.
"actions": [ # List of actions the agent is able to handle.
{ # Next Id: 8
# Action represents a specific conversation agent supports, it can be a single
# shot action, or a multi-step conversation.
"initialTrigger": { # Trigger is an intent and its associated query patterns which are used to # Indicates the query patterns used to invoke this agent, e.g., [order a
# coffee] for starbucks. Note that for Assistant V1 API, to trigger the agent
# user needs to include agent invocation name too, something like [order a
# coffee with starbucks].
# match user's queries. Used for both initial trigger, and follow-on queries.
"queryPatterns": [ # List of patterns used to identify the specified intent.
{ # QueryPattern is an annotated instance of a developer provided example, or a
# query pattern. As of Aug, we only support query pattern.
"queryPattern": "A String", # The instance would be used to match to user's phrases, e.g.,
# [book a table at $Restaurant:restaurant].
},
],
"intent": "A String", # Indicates the intent of this query match, e.g., "BOOK_A_TABLE".
},
"httpExecution": { # Indicates the Execution is based on HTTP API. # The cloud endpoint where Assistant sends the HTTP request to. The request
# response will follow assistant conversation API.
"url": "A String", # The HTTP endpoint for the 3P agent, can be a Google Cloud Function endpoint
# or a self-hosting HTTP endpoint. Assistant sends a POST request to exchange
# data with 3P. Note that as of Nov 2016, only SSL is supported.
},
"arguments": [ # List of arguments for the action.
{ # Argument of the action.
"name": "A String", # Name of the argument.
"entityType": "A String", # Entity type. Could be built-in or custom.
},
],
"signInRequired": True or False, # Indicates whether sign-in is required for this action. Note this is valid
# only when agent has AccountLinking specified inside AgentInfo.
"description": "A String", # English description what the action does. This is mainly used for Google to
# review the action or debugging purpose. It won't be surfaced to users. It
# must be less than 100 ASCII letters.
"inDialogTriggers": [ # In-dialog triggers after the user is interacting with the agent. Specifying
# these in the action is optional. They can be referred to from speech
# biasing based on the dialog state.
{ # Trigger is an intent and its associated query patterns which are used to
# match user's queries. Used for both initial trigger, and follow-on queries.
"queryPatterns": [ # List of patterns used to identify the specified intent.
{ # QueryPattern is an annotated instance of a developer provided example, or a
# query pattern. As of Aug, we only support query pattern.
"queryPattern": "A String", # The instance would be used to match to user's phrases, e.g.,
# [book a table at $Restaurant:restaurant].
},
],
"intent": "A String", # Indicates the intent of this query match, e.g., "BOOK_A_TABLE".
},
],
},
],
"deploymentStatus": { # Indicates the status of the Action Package. # Describes the deployment status of the Action Package, e.g., how long it
# will be valid for Action Preview, what's the overall status of the Action
# Package for all users. When the Action Package is created, it's set to
# NEW.
"state": "A String", # Detailed status for the Action Package in question.
"previewEndTime": "A String", # End time for action preview, it only make sense when state is IN_PREVIEW.
},
"versionLabel": "A String", # Indicates the developer friendly label for this action package.
"customTypes": [ # List of customized types defined by developer.
{ # Tye defined by Developer such as list of colors, or list of uber types.
"entityCategory": "A String", # Semantic built-in type that is a hypernym of the entity type. Must be a
# built-in type.
"items": [ # List of items for this type. Each includes a key and list of synonyms.
{ # Each Item corresponds a unique entity for this type, it has a unique key
# and list of synonyms which are used to trigger.
"key": "A String", # Unique key for this item.
"synonyms": [ # List of synonyms which can be used to refer to this item.
"A String",
],
},
],
"isDynamicDefined": True or False, # Indicates the type is runtime defined. Prefer is_user_defined instead. This
# field will be deprecated.
"name": "A String", # Name of the custom type, in the format of "$Type".
"isUserDefined": True or False, # Whether the values are user-defined (different for every user).
},
],
"name": "A String", # Unique ID for this Action Package, assigned by CreateActionPackage API.
"agentInfo": { # AgentInfo is mutable before agents submits the ActionPackage for review. It # Metadata for this agent like the agent name.
# becomes immutable once she submits for review.
"accountLinking": { # AccountLinking is used for 3P agent to allow Google Assistant to guide user # Metadata used to link user's Google account with 3P account.
# to sign-in 3P web services.
"accessTokenUrl": "A String", # The url to fetch access token given an authentication, e.g.,
# https://login.uber.com/oauth/v2/token .
"scopes": [ # List of scopes user needs to grant permission for, <= 10 scopes are
# supported.
"A String",
],
"clientId": "A String", # Unique public string used to identify client requesting for authentication.
"grantType": "A String", # Indicate type of authentication.
"authenticationUrl": "A String", # The url where customers will be redirected in the companion app to enter
# login credentials, e.g., https://login.uber.com/oauth/v2/authorize
"privacyUrl": "A String", # Link to the Privacy Policy for this skill. This is mandatory for account
# linking.
"clientSecret": "A String", # Client secret maintained by developer.
},
"languageCode": "A String", # The BCP-47 language code, such as "en-US" or "sr-Latn". As of Aug 2016, we
# only support en-US. Note for agents with multiple languages, we recommend
# developer to split Action Package by language.
"privateKey": "A String", # Private key provided by 3P agent, it's used for 3P to verify request from
# Assistant. In the runtime, Assistant computes a HMAC-SHA256 signature and
# populates an HTTP header, 3P needs to use HMAC-SHA256 to calculate the
# signature again to verify the request comes from Assistant, e.g., lets
# say FunBrain provides a private key "fun_brain_private_key", the header
# sent by Assistant looks like:
# Google-Assistant-Signature: 2b9c2afbf67e1aca90e05f191036f257daf88f4dde4c5722d060a8d958b18833 // NOLINT
# where the signature is SHA256(private_key:post_body).
"logoUrl": "A String", # Logo image for the application
# This is required when account linking is enabled
"invocationNames": [ # List of invocation names for this agent, they are used for users to refer
# to the agent, e.g., user can say [talk to uber], or [book a cab using uber]
# if she wants to talk directly to uber agent.
# Note as of Sep 2016, we only allow one invocation name for an agent.
"A String",
],
"projectId": "A String", # The Pantheon project ID associated with this agent.
"voiceName": "A String", # 3P agent needs to specify a specific voice name from 10 options. Note those
# options will be available around 09/10/2016.
},
"versionId": "A String", # Indicates the version ID for this action package that is populated
# by the Google Assistant platform for action packages that have been
# submitted. This ID will match the one given in the developer console.
}x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
2 - v2 error formatReturns:
An object of the form:{ # ActionPackage is the main operation unit developer works on, it's the home
# for list of actions 3P agent wants to support to extend Google Assistant
# capabilities. It mainly includes triggering grammars, authentication info,
# cloud endpoint and other application level metadata such as access control.
"actions": [ # List of actions the agent is able to handle.
{ # Next Id: 8
# Action represents a specific conversation agent supports, it can be a single
# shot action, or a multi-step conversation.
"initialTrigger": { # Trigger is an intent and its associated query patterns which are used to # Indicates the query patterns used to invoke this agent, e.g., [order a
# coffee] for starbucks. Note that for Assistant V1 API, to trigger the agent
# user needs to include agent invocation name too, something like [order a
# coffee with starbucks].
# match user's queries. Used for both initial trigger, and follow-on queries.
"queryPatterns": [ # List of patterns used to identify the specified intent.
{ # QueryPattern is an annotated instance of a developer provided example, or a
# query pattern. As of Aug, we only support query pattern.
"queryPattern": "A String", # The instance would be used to match to user's phrases, e.g.,
# [book a table at $Restaurant:restaurant].
},
],
"intent": "A String", # Indicates the intent of this query match, e.g., "BOOK_A_TABLE".
},
"httpExecution": { # Indicates the Execution is based on HTTP API. # The cloud endpoint where Assistant sends the HTTP request to. The request
# response will follow assistant conversation API.
"url": "A String", # The HTTP endpoint for the 3P agent, can be a Google Cloud Function endpoint
# or a self-hosting HTTP endpoint. Assistant sends a POST request to exchange
# data with 3P. Note that as of Nov 2016, only SSL is supported.
},
"arguments": [ # List of arguments for the action.
{ # Argument of the action.
"name": "A String", # Name of the argument.
"entityType": "A String", # Entity type. Could be built-in or custom.
},
],
"signInRequired": True or False, # Indicates whether sign-in is required for this action. Note this is valid
# only when agent has AccountLinking specified inside AgentInfo.
"description": "A String", # English description what the action does. This is mainly used for Google to
# review the action or debugging purpose. It won't be surfaced to users. It
# must be less than 100 ASCII letters.
"inDialogTriggers": [ # In-dialog triggers after the user is interacting with the agent. Specifying
# these in the action is optional. They can be referred to from speech
# biasing based on the dialog state.
{ # Trigger is an intent and its associated query patterns which are used to
# match user's queries. Used for both initial trigger, and follow-on queries.
"queryPatterns": [ # List of patterns used to identify the specified intent.
{ # QueryPattern is an annotated instance of a developer provided example, or a
# query pattern. As of Aug, we only support query pattern.
"queryPattern": "A String", # The instance would be used to match to user's phrases, e.g.,
# [book a table at $Restaurant:restaurant].
},
],
"intent": "A String", # Indicates the intent of this query match, e.g., "BOOK_A_TABLE".
},
],
},
],
"deploymentStatus": { # Indicates the status of the Action Package. # Describes the deployment status of the Action Package, e.g., how long it
# will be valid for Action Preview, what's the overall status of the Action
# Package for all users. When the Action Package is created, it's set to
# NEW.
"state": "A String", # Detailed status for the Action Package in question.
"previewEndTime": "A String", # End time for action preview, it only make sense when state is IN_PREVIEW.
},
"versionLabel": "A String", # Indicates the developer friendly label for this action package.
"customTypes": [ # List of customized types defined by developer.
{ # Tye defined by Developer such as list of colors, or list of uber types.
"entityCategory": "A String", # Semantic built-in type that is a hypernym of the entity type. Must be a
# built-in type.
"items": [ # List of items for this type. Each includes a key and list of synonyms.
{ # Each Item corresponds a unique entity for this type, it has a unique key
# and list of synonyms which are used to trigger.
"key": "A String", # Unique key for this item.
"synonyms": [ # List of synonyms which can be used to refer to this item.
"A String",
],
},
],
"isDynamicDefined": True or False, # Indicates the type is runtime defined. Prefer is_user_defined instead. This
# field will be deprecated.
"name": "A String", # Name of the custom type, in the format of "$Type".
"isUserDefined": True or False, # Whether the values are user-defined (different for every user).
},
],
"name": "A String", # Unique ID for this Action Package, assigned by CreateActionPackage API.
"agentInfo": { # AgentInfo is mutable before agents submits the ActionPackage for review. It # Metadata for this agent like the agent name.
# becomes immutable once she submits for review.
"accountLinking": { # AccountLinking is used for 3P agent to allow Google Assistant to guide user # Metadata used to link user's Google account with 3P account.
# to sign-in 3P web services.
"accessTokenUrl": "A String", # The url to fetch access token given an authentication, e.g.,
# https://login.uber.com/oauth/v2/token .
"scopes": [ # List of scopes user needs to grant permission for, <= 10 scopes are
# supported.
"A String",
],
"clientId": "A String", # Unique public string used to identify client requesting for authentication.
"grantType": "A String", # Indicate type of authentication.
"authenticationUrl": "A String", # The url where customers will be redirected in the companion app to enter
# login credentials, e.g., https://login.uber.com/oauth/v2/authorize
"privacyUrl": "A String", # Link to the Privacy Policy for this skill. This is mandatory for account
# linking.
"clientSecret": "A String", # Client secret maintained by developer.
},
"languageCode": "A String", # The BCP-47 language code, such as "en-US" or "sr-Latn". As of Aug 2016, we
# only support en-US. Note for agents with multiple languages, we recommend
# developer to split Action Package by language.
"privateKey": "A String", # Private key provided by 3P agent, it's used for 3P to verify request from
# Assistant. In the runtime, Assistant computes a HMAC-SHA256 signature and
# populates an HTTP header, 3P needs to use HMAC-SHA256 to calculate the
# signature again to verify the request comes from Assistant, e.g., lets
# say FunBrain provides a private key "fun_brain_private_key", the header
# sent by Assistant looks like:
# Google-Assistant-Signature: 2b9c2afbf67e1aca90e05f191036f257daf88f4dde4c5722d060a8d958b18833 // NOLINT
# where the signature is SHA256(private_key:post_body).
"logoUrl": "A String", # Logo image for the application
# This is required when account linking is enabled
"invocationNames": [ # List of invocation names for this agent, they are used for users to refer
# to the agent, e.g., user can say [talk to uber], or [book a cab using uber]
# if she wants to talk directly to uber agent.
# Note as of Sep 2016, we only allow one invocation name for an agent.
"A String",
],
"projectId": "A String", # The Pantheon project ID associated with this agent.
"voiceName": "A String", # 3P agent needs to specify a specific voice name from 10 options. Note those
# options will be available around 09/10/2016.
},
"versionId": "A String", # Indicates the version ID for this action package that is populated
# by the Google Assistant platform for action packages that have been
# submitted. This ID will match the one given in the developer console.
}
