Content on this page might refer to the legacy Actions SDK. Refer to the main Conversational Actions documentation for guides and procedures that use Actions Builder and the current Actions SDK.

Pre-launch checklists

Before submitting your Actions for approval, review these pre-launch checklists for best practices. These checklists improve your project's chances of approval by helping you catch many of the issues we see during the approval process.

Assistant directory

The following checklist highlights steps you can take to improve the user experience using features of the Assistant directory.

Assistant directory
Write good descriptions

Make sure your Assistant directory descriptions promote your Actions’ utility, benefits, and best features with text and images.

If Google Assistant recommends your Actions to a user, and they ask for more details, Assistant will read your Actions' description to the user. Make sure your description sounds acceptable in this context to create a good first impression.

Use the Assistant directory web link

Promote your Actions using the directory web link. You can provide this link on your website and other marketing materials to drive users to your Actions' directory page.

Use Action links

Promote your Actions by creating Action links and distributing them to users. Users who click your link on compatible devices are taken directly to a conversation with your Actions.

Invocation and discovery

The following checklist contains recommendations to make your Actions easier for users to invoke and discover.

Display name
Avoid words that have multiple pronunciations

Users and the Google Assistant should be able to easily and consistently pronounce your display name. For instance, avoid using the word "Envelope" in your display name, as users and Google Assistant won't know whether to say "en-vel-ope" or "ahn-vel-ope". Other examples include "tear", "bow", and "bass".

Make sure Google recognizes your display name
  • Test your display name in the Actions console in the Develop tab Invocation settings. Check to see if the text output matches what is listed for your display name.
  • Test your Actions on voice-activated speakers. Preview your display name and try to invoke them to ensure they function properly on this type of device.
  • Test with people of different genders and accents. You should make sure that your display name is recognized no matter who says it.
  • .
  • If users cannot consistently pronounce your display name, use the Actions console Display name controls to provide a pronunciation.
Choose an easy but unique name

Users should be able to effortlessly invoke your Actions. If they have to struggle to say the name or can't easily remember the name, they are far less likely to keep using your Actions.

Adhere to our naming policies

See the naming policies for more information on guidelines and restrictions for display names.

If you need a display name for your business that is not well recognized by Google Assistant or violates one of our policies, contact support to request an exception.

Invocation phrases
Design for your Actions' use cases

Design your project's deep links around your specific tasks and real world use cases. Avoid phrases that are too general and don't specifically describe your Actions' purpose.

Specify clear verb-object pairs

Create deep links that consist of a verb-object pair, like "tell a story" or "start meditating". These phrases are easier for users to remember and align well with most user queries.

Use entities with relevant synonyms

Types are useful tools for invocation phrases since they can match multiple user inputs to a single phrase. Make sure all types you add to invocation phrases only include synonyms that are relevant to the phrase(s) and your Actions' use case.

Provide a broad set of high-quality sample invocations;

Ensure your Actions can be invoked regardless of your user's choice of words. Try to provide at least 10 different invocation phrases for each Action. You can edit this setting in the Actions console under Develop > Directory information > Sample invocations.

Review examples of good and bad invocation phrases

Invocation phrases are critical for your Actions being discovered naturally via implicit invocation, so you should take the time to ensure they are designed well. For more information, review our recommendations for writing useful invocation phrases.

User interface

The following checklist highlights common things you can do to make sure your responses appear appropriately on the surface where users experience your Actions.

Cards and options
Use cards and options

Cards and options let you display information in a richer, more customizable format.

  • Basic card: If you need to present a lot of text to the user, use a basic card. A card can display up to 15 lines of text, and link to a website for further reading. Unlike chat bubbles, the card supports text formatting. You can also add an image and a list or carousel to display options.
  • List: If you are asking the user to pick from a list of choices, consider using a list instead of writing out the list in a chat bubble.
  • Carousel: If you want the user to pick from a list of choices with a focus on larger images, use a carousel, which has a limit of 8 items.
Suggestion chips
Use suggestion chips after most turns

Using suggestion chips can significantly increase your Actions' usability on devices with screens. When you implement them, users can quickly tap the screen to respond, in addition to using voice or the keyboard. For example, you can use suggestion chips that say Yes and No for yes or no questions.

Use chips when there are few options

When offering the user a small number of choices (8 or less) you can add a suggestion for each choice. Present them in the same order as in your response, and use the same terminology.

Use chips when there are many choices

If you ask a question with a wide range of possible answers, present a few of the most popular answers.

Use chips when returning media responses

Include suggestion chips with a media response to help users who want to pivot the conversation.

Chat bubbles
Correct capitalization and punctuation

Check your responses for correct capitalization and punctuation.

Fix phonetic spellings

If you spelled something out phonetically using SSML in your response to help with pronunciation, that phonetic misspelling will appear in your chat bubble. Use different display text to use correct spelling for chat bubbles on devices with screens.

Avoid truncation

Chat bubbles are limited to 640 characters and are truncated after that limit (however, we recommend around 300 as a general design guideline). If you have more than that, you can:

  • Use a second chat bubble: Up to 2 chat bubbles are allowed per turn, so find a natural break point and create a second chat bubble.
  • Don't show everything: If you have an extensive spoken response, consider showing only a subset of the content in the text portion of the response, such an introduction.
Recorded audio
Remove <audio> text from chat bubbles

If you have text inside your SSML <audio> tag, it's displayed in your corresponding chat bubble. For example, if your SSML is:

<speak>
  Here's that song.
  <audio src="...">song audio</audio>
</speak>

Your chat bubble text appears as "Here's that song. song audio".

Instead, add a <desc> element inside your <audio> element. Any text inside <desc> is displayed, and any text outside <audio> is used as the alternate text if the audio source file cannot be loaded. For example:

<speak>
  Here's that song.
  <audio src="bad_url"><desc></desc>song audio</audio>
</speak>

This results in the audio output: "Here's that song. song audio" and the chat bubble text: Here's that song.

Alternatively, you can just remove the text from your <audio> tag altogether, or use the SSML <sub> tag.

Eliminate empty chat bubbles

Ensure that every dialog turn has at least one chat bubble. If your Actions have dialogs composed of only spoken responses, the chat bubble text will be missing and your response will fail. In these cases, add matching text to your response.