# Assistant links You can generate a URL that links directly to a specific intent of your Action. Users who click an Assistant link (previously called Action links) in a web or mobile browser are directed to Assistant on their device, where they interact directly with your Action. Assistant links are different from [directory web links](https://developers.google.com/assistant/directory#web_directory), which send a user to your Action's page in the [Assistant directory](https://assistant.google.com/explore). Here are some situations where Assistant 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](https://developers.google.com/assistant/engagement/daily) so they can opt-in to your future updates. ## Generate an Assistant link You can generate Assistant links from within your project in the Actions console. Assistant links are available through all deployment channels (alpha, beta, and production). For example, if your Assistant 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](https://console.actions.google.com), navigate to **Deploy \> Assistant links**. 2. For **Intent**, select the intent you want to generate a link for. 3. Enable the **Would you like to enable linking for intent_name?** option. 4. (optional) In the **Campaign parameters** section, enter any information you want to additionally capture in the link as URL parameters. 5. (optional) 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](https://developers.google.com/assistant/transactions) 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 Assistant link. Use the Assistant link wherever you want to direct users to this specific Action. > [!NOTE] > **Note:** If you enable an Assistant link after your Action is deployed, you must re-deploy your Action for the link to take effect. > [!NOTE] > **Note:** Dialogflow users should follow the steps on [this page](https://developers.google.com/assistant/conversational/df-asdk/engagement/action-links). ## Test Assistant links You can test Assistant links for any intent (main or custom, with or without parameters) through the simulator or on a device. To test your Assistant link on a device, follow these steps: 1. [Generate the Assistant link](https://developers.google.com/assistant/engagement/assistant-links#generate-link) in the Actions console. 2. Send the Assistant 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 Assistant link you sent to yourself. Once you confirm the Assistant link functions as expected, you need to re-deploy your Action to make the link available to your users. ## Assistant link parameters Assistant links can optionally contain an intent and parameters in the URL. Use the **Campaign parameters** section to add campaign parameters. When an Assistant 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 Assistant 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 Assistant link URL using the `MAIN` intent with no additional parameters: https://assistant.google.com/services/invoke/uid/000000d139bbc4d4 ### Assistant link URL specification The general syntax for the URL of an Assistant link is as follows: https://assistant.google.com/services/invoke[/$action_id][?intent=$intent¶m.$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 user 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. | ### Assistant link URLs with built-in intents If the Assistant link contains a [built-in intent](https://developers.google.com/assistant/conversational/df-asdk/discovery/built-in-intents) (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`](https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppRequest) message. The following example shows how you might specify an Assistant 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¶m.name=%22ExampleGame%22 ### Assistant link URLs with user intents For user 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 Assistant link URL that includes a user intent: https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK¶m.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', } ### Assistant link URLS with UTM parameters [UTM parameters](https://wikipedia.org/wiki/UTM_parameters) are strings that Google Assistant sends to your Action when users click on an Assistant 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 Assistant 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', } ## Rich Assistant links ![](https://developers.google.com/static/assistant/engagement/images/rich-link-flow.gif) Rich Assistant links give you a way to increase your Action's discovery through your website, using assist.js. Users can try out your Action, as well as link their Google account to your service, using account linking. When a user visits your website, they see a "Try with Google Assistant" button, which triggers the Rich Assistant link flow. Enabling account linking for your Action allows users to access your Action on any of their Assistant enabled devices. In addition, users can link their account with your service to their Google account, allowing for a more personalized experience. When used with account linking, Rich Assistant links uses your authorization URL, which is set in your project in the Actions console. For more information, see the [account linking documentation](https://developers.google.com/assistant/identity). > [!NOTE] > **Note:** If the user isn't signed in to their Google account, the Rich Assistant link either triggers your Action in the Assistant on the user's device (if Assistant is available) or sends the user to your Action's Assistant directory page. ### Prerequisites To use Rich Assistant links, you need the following: - [Actions project](https://developers.google.com/assistant/conversational/build/projects). - [Assistant link enabled](https://developers.google.com/assistant/engagement/assistant-links#generate-link) for your Action. - (Optional) [Account linking enabled](https://developers.google.com/assistant/identity) for your Action. ### Local development To include a rich Assistant link on your website, complete the following steps: 1. Include the following JavaScript library on your page, replacing `` with your Actions project ID: 2. Add the following HTML tag somewhere on your page. This loads the inline "Try it with Google Assistant" button: > [!NOTE] > **Note:** If an Assistant user is not logged in, the first Assistant link triggers the Assistant or redirects the user to the Assistant Directory page for your Action. #### Proactive triggering If you want the rich Assistant link flow to initiate automatically when users visit your page for this first time, use the `` tag. When you apply this tag, the link activates without users on their first visit, without them selecting the inline button. > [!NOTE] > **Note:** While proactive triggering stays active for some time, users still need to occasionally select the inline button to re-activate the proactive triggering flow. 1. Add an `id` to your Assistant link group tag: 2. Place a `` tag on your webpage and set its `groupId` attribute to the `id`: \ \ ### Deployment Rich Assistant links only work for domains you own and have [verified with Google](https://developers.google.com/assistant/console/brand-verification#connecting_a_website). When developing locally, this requirement is bypassed by having access to the Actions project, being logged into your Google account, and setting the `dev=true` query parameter in your script tag. To deploy your Action with the rich Assistant links: 1. Register your public domain in the Actions console under **Deploy \> Brand Verification \> Connect Site**. 2. Remove the `dev=true` query parameter from the script: ## Restrictions and best practices The following restrictions and best practices apply so your Assistant link URL can be distributed and referenced outside of the directory or other Google services: - Continue to support all of your Assistant links. If you distribute an Assistant 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](https://developers.google.com/assistant/smarthome/overview) 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.