Vincular às suas ações (Dialogflow)

Você pode gerar um URL com um link direto para a ação específica, por ação. Os usuários que clicarem no link do Google Assistente (antes chamados de links de ação) em um navegador da Web ou para dispositivos móveis serão direcionados para o Google Assistente no dispositivo, onde vão interagir diretamente com a ação correspondente.

Veja alguns exemplos de links úteis do Google Assistente:

  • Vincular usuários a instruções guiadas por voz de um site de instruções.
  • Vincular usuários a uma experiência de suporte ao cliente na página "Receber ajuda".
  • Vincular usuários a uma intent de atualização para que eles possam aceitar as atualizações futuras.

Para gerar o URL de uma ação, faça o seguinte:

  1. No Console do Actions, acesse Desenvolver > Ações.
  2. Clique na ação para a qual você quer gerar um link.
  3. Na seção Links, ative a opção Gostaria de ativar um URL para esta ação.
  4. Digite o Título do link. Esse título precisa incluir um verbo descritivo do que a ação vai fazer. Por exemplo, se a ação leva o usuário a um fluxo de transações para comprar ingressos para um show, um título de link útil seria "comprar ingressos para um show".
  5. Clique em Salvar.

Você pode copiar o URL fornecido e referenciá-lo sempre que quiser direcionar os usuários para essa ação específica.

Opcionalmente, os links do Assistente podem conter uma intent e parâmetros no URL. O Google processa os parâmetros de acordo com o tipo de intenção especificado no URL.

A sintaxe geral do URL de um link do Assistente é a seguinte:

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

Os parâmetros de URL que podem ser configurados são descritos na tabela a seguir:

Parâmetro de URL Descrição
$action_id Identificador numérico da ação.
$intent Nome completo de uma intent integrada ou personalizada.
$param Nome completo de um parâmetro de intent especificado no pacote de ações.
$value Valor codificado de URL do tipo declarado para $param no pacote de ações.
$utm_param Lista de um ou mais tipos de parâmetros de UTM. Os valores válidos incluem: utm_source, utm_medium, utm_campaign, utm_term e utm_content.
$utm_value Valor de string do parâmetro UTM.

Se o link do Google Assistente tiver uma intent integrada (que começa com actions.intent.*), o Google vai tentar extrair os parâmetros de intent integrada no URL e transmiti-los para a ação. Todos os parâmetros que o Google não entende como parâmetros de intent integrada são removidos.

Para ações de conversa, o Google envia esses parâmetros para o fulfillment como parte da mensagem AppRequest.

O exemplo a seguir mostra como especificar um URL de link do Google Assistente que inclua uma intent integrada com um único parâmetro de intent:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.GET_HOROSCOPE&param.astrologySign=%22cancer%22

Para intents personalizadas, o Google extrai apenas os parâmetros definidos pela sua ação como parte da intent e descarta todos os outros parâmetros.

O exemplo a seguir mostra como especificar um URL de link do Google Assistente que inclua uma intent personalizada:

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

Para o URL de exemplo acima, no AppRequest, o Google adiciona um objeto JSON da seguinte maneira:

argument {
  name: ‘topic’,
  raw_text: ‘sports’,
  text_value: ‘sports’,
}

Se você não especificar uma intent no link do Google Assistente, o Google vai vincular a intent MAIN (actions.intent.MAIN) da ação por padrão com o seguinte comportamento:

  • Se você não tiver ativado explicitamente a intent MAIN no link do Google Assistente, o Google acionará a intent principal sem nenhum parâmetro, semelhante ao comportamento de "Falar com app_name".
  • Se você ativou explicitamente a intent MAIN, o Google transmite os parâmetros para suas ações.

O exemplo a seguir mostra como especificar um URL de link do Google Assistente sem intent:

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

Os parâmetros do UTM são strings que o Google envia para sua ação quando os usuários clicam em um link do Assistente, que você pode usar depois para análises.

Os parâmetros UTM que o Google envia para sua Ação incluem o seguinte:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

O exemplo a seguir mostra como especificar um URL de link do Assistente que inclua parâmetros UTM:

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

Para o URL de exemplo acima, o Google adiciona os seguintes argumentos à mensagem AppRequest:

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’,
}

Você pode testar links do Google Assistente para qualquer intent (principal ou personalizada, com ou sem parâmetros) usando o simulador ou um dispositivo.

Para testar o link do Google Assistente:

  1. Ative o link do Assistente no console.
  2. Faça login no Assistente com a mesma conta que você usou para criar o projeto do Actions on Google.
  3. Crie uma versão clicável do seu link do Assistente (em e-mail, chat, documento etc.).
  4. Em um dispositivo com Google Assistente, clique no link criado na etapa anterior.

Depois de confirmar que o link do Google Assistente funciona conforme o esperado, você vai precisar implantar a ação novamente para disponibilizar o link aos usuários.

Restrições e práticas recomendadas

Como agora o URL do link do Assistente pode ser distribuído e referenciado fora do diretório ou de outros serviços do Google, as seguintes restrições e práticas recomendadas se aplicam:

  • Continue a oferecer suporte a todos os links do Google Assistente. Se você distribuir um link do Assistente que, posteriormente, for corrompido, seu projeto do Actions poderá ser sinalizado como não íntegro e removido.
  • Publicar um link significa que você oferece suporte ao acionamento de fontes não confiáveis. Para qualquer ação vinculada, é necessário confirmar explicitamente com o usuário antes de realizar qualquer "ação real". Por exemplo, uma ação que desativa um dispositivo de casa inteligente solicita que o usuário diga "Tem certeza de que quer desativar o $applianceName?"

    Neste contexto, uma "ação do mundo real" é qualquer ação que afeta os serviços, dados, dispositivos, redes, computadores ou APIs do usuário. Por exemplo, enviar um e-mail, fazer uma transação, alterar o status de um dispositivo de casa inteligente, criar uma assinatura ou atualizar um conteúdo.