Link to your Actions

You can generate a URL that links directly to a specific intent of your Action. Users who click an Action link in a web or mobile browser are directed to Assistant on their device, where they interact directly with your Action.

Action links are different from directory web links, which send a user to your Action's page in the Assistant directory.

Here are some situations where Action links can be useful:

  • Linking users to voice-guided instructions from a how-to website.
  • Linking users to a customer support experience from a help page.
  • Linking users to an update intent so they can opt-in to your future updates.

You can generate Action links from within your project in the Actions console. Action links are available through all deployment channels (alpha, beta, and production). For example, if your Action link is enabled in the alpha release of your Action, the link is available to alpha testers.

To generate a URL for an Action, follow these steps:

  1. In the Actions console, navigate to Deploy > Action links.
  2. For the Intent, select the intent you want to generate a link for.
  3. In the Campaign parameters section, enter any information you want to additionally capture in the link as URL parameters.
  4. Enter a Link title. Use this title to describe what the Action does. For example, if your Action takes the user down a transaction flow to buy tickets to a concert, your link title could be "purchase concert tickets."

After you enter your information, you can view and copy the generated URL or generated code snippet for the Action link. Use the Action link wherever you want to direct users to this specific Action.

You can test Action links for any intent (main or custom, with or without parameters) through the simulator or on a device.

To test your Action link on a device, follow these steps:

  1. Generate the Action link in the Actions console.
  2. Send the Action link as a URL to yourself in an email, chat message, or other format.
  3. On an Assistant-enabled device, sign in to Assistant with the same account you used to create your Actions project.
  4. On the same device, click on the Action link you sent to yourself.

Once you confirm the Action link functions as expected, you need to re-deploy your Action to make the link available to your users.

Action links can optionally contain an intent and parameters in the URL. Use the Campaign parameters section to add campaign parameters.

When an Action link contains no additional parameters, Google Assistant links to the MAIN intent (actions.intent.MAIN) of your Action with the following behavior:

  • If you didn't explicitly enable the MAIN intent in the Action link, Assistant matches the main intent without any parameters, similar to the behavior for "Talk to app_name".
  • If you explicitly enabled the MAIN intent, Assistant passes the parameters to your Actions.

Here's an example of an Action link URL using the MAIN intent with no additional parameters:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

The general syntax for the URL of an Action link is as follows:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

The URL parameters you can set are described in the following table:

URL parameter Description
$action_id Action's numeric identifier.
$intent Full name of a built-in or custom intent.
$param Full name of an intent parameter specified in the Action package.
$value URL encoded value of the type declared for $param in the Action package.
$utm_param List of one or more UTM parameter types. Valid values include: utm_source, utm_medium, utm_campaign, utm_term, and utm_content.
$utm_value String value of the UTM parameter.

If the Action link contains a built-in intent (the intent starts with actions.intent.), Google Assistant tries to extract any built-in intent parameters in the URL and passes them on to your Action. Any parameters that Assistant does not understand as built-in intent parameters are removed.

For Conversational Actions, Assistant sends these parameters to your fulfillment as part of the AppRequest message.

The following example shows how you might specify an Action link URL that includes a built-in intent with a single intent parameter:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

For custom intents, Google Assistant extracts only those parameters that are defined by your Action as part of the intent and discards any other parameters.

The following example shows how you might specify an Action link URL that includes a custom intent:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

For the above example URL, in the AppRequest, Assistant adds a JSON object as follows:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

UTM parameters are strings that Google Assistant sends to your Action when users click on an Action link. You can use information contained in these strings later for analytics.

The UTM parameters that Assistant sends to your Action include the following:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

The following example shows how you might specify an Action link URL that includes UTM parameters:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

For the example URL above, Assistant adds the following arguments in the AppRequest message:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Restrictions and best practices

The following restrictions and best practices apply so your Action link URL can be distributed and referenced outside of the directory or other Google services:

  • Continue to support all of your Action links. If you distribute an Action link that later breaks, your Actions project may be flagged as unhealthy and taken down.

  • Publishing a link means you support triggering from untrusted sources. For any linked Actions, you must explicitly confirm with the user before taking any real-world action. For example, an Action that turns off a smart home appliance should prompt the user saying, "Are you sure you want to turn off $applianceName?"

    In this context, a real world action is any action that affects the user's services, data, devices, networks, computers, or APIs. For example, sending an email, performing a transaction, altering the status of a smart home appliance, creating a subscription, or updating a piece of content.