Referência da API Interactive Canvas

A API de tela interativa é uma biblioteca JavaScript usada para interagir com sua ação de conversa usando o objeto interactiveCanvas no app da Web.

Observação: o objeto interactiveCanvas está anexado ao objeto window. Se você usar um framework de front-end para desenvolver seu app da Web, confira se tem acesso a window para configurar a API.

Para mais informações sobre a tela interativa, consulte a documentação sobre a tela interativa.

Métodos

Aviso: no momento, algumas das APIs de tela interativa estão na prévia para desenvolvedores. Você pode testar as APIs no simulador, mas não implante uma ação que use esses recursos nos canais Alfa, Beta ou de produção. As ações implantadas com esses recursos não vão funcionar em dispositivos de usuários finais.

pronto

ready(callbacks) returns undefined

Chamado pelo app da Web de tela interativa depois que ele é carregado para registrar callbacks.

Parâmetros
callbacks	InteractiveCanvasCallbacks Um objeto que contém callbacks de método.

Observação: é necessário invocar a API ready no app da Web assim que a página for carregada. Caso contrário, ela será fechada.

sendTextQuery

sendTextQuery(textQuery) returns Promise<state>

Envia uma consulta de texto para a ação de conversa.

Parâmetros
textQuery	string A consulta a ser enviada para a ação de conversa.
state	string Opções: READY: As solicitações podem ser aceitas pela plataforma. BLOCKED: Há uma consulta em andamento, e a nova consulta será descartada. UNKNOWN: Não foi possível determinar o estado atual da consulta.

Atenção: textQuery precisa ter até 640 caracteres.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

Determina a altura do cabeçalho na parte superior de uma tela.

Parâmetros
height	number A altura em pixels.

outputTts

outputTts(text, openMic) returns undefined;

Reproduz texto SSML.

Parâmetros
text	string A string compatível com SSML a ser reproduzida.
openMic	boolean Define se o microfone será aberto após a reprodução do TTS.

createIntentHandler

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

createIntentHandler(intentId, callback) returns IntentHandler

Cria um gerenciador de intent para uma intent personalizada de PLN.

Parâmetros
intentId	string Nome da intent, conforme definido no Actions Builder.
callback	function(MatchedIntent) Função a ser executada quando houver correspondência com a intent.
IntentHandler	object Objeto do gerenciador da intent que pode ser registrado usando expect().

IntentHandler

Um objeto que representa um gerenciador de intents. Pode ser registrado usando expect() ou prompt().

MatchedIntent

Um objeto que contém os dados de uma intent correspondente.

Métodos
getIntentArg(parameterName)	function(string) Método para receber o parâmetro de uma intent correspondente.

createNumberSlot

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

createNumberSlot(callback, hints?) returns Slot<number>

Cria um slot com o tipo número.

Parâmetros
callback	function(FilledSlot) Função a ser executada quando o slot for preenchido.
hints	Hints Palavras curtas que o usuário pode dizer ao preencher um slot. hints ajudam o sistema PLN a decidir qual slot preencher.
Slot	object Objeto de slot que pode ser registrado usando prompt().

createTextSlot

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

createTextSlot(callback, hints?) returns Slot<string>

Cria um slot do tipo string.

Parâmetros
callback	function(FilledSlot) Função a ser executada quando o slot for preenchido.
hints	Hints Palavras curtas que o usuário pode dizer ao preencher um slot. hints ajudam o sistema PLN a decidir qual slot preencher.
Slot	object Objeto de slot que pode ser registrado usando prompt().

createConfirmationSlot

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

createConfirmationSlot(callback, hints?) returns Slot<boolean>

Cria um slot do tipo booleano.

Parâmetros
callback	function(FilledSlot) Função a ser executada quando o slot for preenchido.
hints	Hints Palavras curtas que o usuário pode dizer ao preencher um slot. hints ajudam o sistema PLN a decidir qual slot preencher.
Slot	object Objeto de slot que pode ser registrado usando prompt().

createOptionsSlot

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

createOptionsSlot(options, callback, hints?) returns Slot<string>

Cria um slot a partir de uma lista predefinida de opções.

Parâmetros
options	array<Option> Função a ser executada quando o slot for preenchido.
callback	function(FilledSlot) Função a ser executada quando o slot for preenchido.
hints	Hints Palavras curtas que o usuário pode dizer ao preencher um slot. hints ajudam o sistema PLN a decidir qual slot preencher.
Slot	object Objeto de slot que pode ser registrado usando prompt().

Slot

Um objeto que representa um espaço a ser preenchido. Pode ser registrado usando expect() ou prompt().

FilledSlot<T>

Um objeto que representa um espaço preenchido.

Parâmetro
T	boolean|number|string O tipo de slot.

Opção

Um objeto que representa uma entrada de tipo de slot.

Campos
key	string O identificador exclusivo da entrada do tipo de slot.
synonyms	array<string> Uma lista de palavras usadas para selecionar a opção de espaço.

Dicas

Um objeto que representa dicas para um slot.

Campos
associatedWords	array<string> Uma lista de palavras usadas para ajudar o sistema PLN a decidir qual slot preencher.

expect

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

expect(expectation) returns HandlerRegistration

Registra a expectativa no cliente. Pode ser chamado em gerenciadores e slots de intent.

Parâmetros
expectation	IntentHandler|Slot O gerenciador ou slot da intent a ser registrado.
HandlerRegistration	object O gerenciador ou slot da intent registrado.

HandlerRegistration

Um objeto que representa um gerenciador de intents registrado.

Métodos
deleteHandler()	function Cancela o registro do gerenciador de intents esperados.

clearExpectations

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

clearExpectations() returns undefined;

Remove todas as expectativas excluindo todos os gerenciadores e slots de intent registrados anteriormente.

prompt

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

prompt(tts, expectation) returns Promise<Answer<T>>

Solicita o usuário com a string de TTS fornecida e registra a expectativa no cliente. Pode ser chamado em gerenciadores e slots de intent.

Parâmetros
tts	string A string de TTS usada para solicitar a expectativa fornecida ao usuário.
expectation	IntentHandler|Slot O gerenciador ou slot da intent a ser registrado.
Answer<T>	object A resposta à solicitação fornecida pelo usuário.

Resposta<T>

Um objeto que representa uma resposta fornecida pelo usuário a um comando.

Campos
value	boolean|number|string O valor da resposta fornecida pelo usuário.
status	string O status da resposta. Opções: ANSWERED: O usuário respondeu à solicitação. NO_MATCH: O usuário recebeu uma solicitação e respondeu com uma resposta que não corresponde à resposta esperada ou a qualquer outra intent esperada. YIELD: O usuário respondeu à solicitação com uma intent diferente.

triggerScene

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

Aciona uma cena.

Parâmetros
sceneName	string O nome do cenário a ser acionado.
TriggerSceneStatus	string O status da chamada para triggerScene(). Opções: SUCCESS: A solicitação foi processada com sucesso pelo servidor. BLOCKED: A solicitação foi bloqueada por uma consulta em andamento. UNKNOWN: O status da solicitação é desconhecido.

setUserParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

setUserParam(key, value) returns Promise<undefined>;

Define o par de chave-valor transmitido e mantido entre conversas.

Parâmetros
key	string A chave de parâmetro.
value	object|array|boolean|number|string Valor de parâmetro.

getUserParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

getUserParam(key) returns Promise<object|array|boolean|number|string>;

Recebe o valor do parâmetro para a chave especificada, se ela existir, e o status da invocação.

Parâmetros
key	string A chave de parâmetro.

resetUserParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

resetUserParam() returns Promise<void>;

Limpa todos os parâmetros do usuário.

setHomeParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

setHomeParam(key, value) returns Promise<undefined>;

Define o par de chave-valor transmitido e mantido entre conversas.

Parâmetros
key	string A chave de parâmetro.
value	object|array|boolean|number|string Valor de parâmetro.

getHomeParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

Recebe o valor do parâmetro para a chave especificada, se ela existir, e o status da invocação.

Parâmetros
key	string A chave de parâmetro.

resetHomeParam

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

resetHomeParam() returns Promise<void>;

Limpa todos os parâmetros do usuário.

setCanvasState

setCanvasState(state) returns undefined

Notifica ao Google Assistente que o app da Web Canvas atualizou o estado. O método setCanvasState não retorna um valor. O payload do estado pode ser acessado usando a propriedade conv.context.canvas.state.

Cuidado: o comprimento da representação de string do objeto state precisa ser menor ou igual a 50.000 caracteres. Se a string exceder 50.000 caracteres, um erro será gerado.

Parâmetros
state	Object O estado atualizado do app Canvas como um objeto JSON.

InteractiveCanvasCallbacks

Esses callbacks oferecem uma maneira de responder a informações ou solicitações da ação de conversa, enquanto os métodos fornecem uma maneira de enviar informações ou solicitações para a ação.

onUpdate

onUpdate(data) returns Promise|undefined

Chamado quando uma resposta Canvas é enviada a partir da ação de conversa. O TTS vai começar quando a promessa retornada for resolvida ou atingir o tempo limite após 10 segundos.

Parâmetros
data	Object Dados atualizados enviados pelo webhook.

onTtsMark

onTtsMark(markName) returns undefined

Callback invocado durante a reprodução de TTS.

Marcas especiais que sempre são acionadas:

• START indica o início do TTS.
• END indica o fim do TTS.
• ERROR indica um erro ao tocar o TTS.

Você também pode definir marcas personalizadas usando SSML e a tag <mark>, como <mark name="custom"/>.

Observação:as marcas SSML não são invocadas quando ocorre o seguinte:

• Antes do TTS começar, o usuário toca no microfone ou o cliente da tela interativa invoca sendTextQuery. A TTS é cancelada, e todas as marcas SSML no TTS são ignoradas.
• Durante o TTS, o usuário toca no microfone ou o cliente de tela interativa invoca sendTextQuery. O TTS é interrompido, e todas as marcas SSML restantes no TTS são ignoradas.

Parâmetros
markName	string Marcar o nome invocado durante a reprodução de TTS.

onInputStatusChanged

Atenção: no momento, essa API está na prévia para desenvolvedores. Você pode testar essa API no simulador, mas não implante uma ação que use esse recurso nos canais Alfa, Beta ou de produção. As ações implantadas com esse recurso não vão funcionar em dispositivos de usuários finais.

onInputStatusChanged(inputStatus) returns undefined

Notifica o app Canvas sobre a mudança do status de entrada do Google Assistente.

Parâmetros
inputStatus	Enum Status do processamento de entrada de texto e/ou voz no dispositivo. Pode ser o seguinte: LISTENING : o microfone está aberto. IDLE : o microfone está fechado. PROCESSING : o Google Assistente está executando uma consulta (o microfone está fechado).