Manipuladores de estado

Manipuladores de estado, também chamados simplesmente de manipuladores, são usados para controlar a conversa criando respostas para usuários finais e/ou fazendo a transição da página atual. Para cada fala na conversa, os manipuladores são avaliados e podem afetar a sessão. Os manipuladores têm três tipos gerais de dados:

Termo	Definição
Requisitos do gerenciador	Estes são os requisitos que precisam ser atendidos para que o manipulador tenha efeito na sessão. Um manipulador é chamado de chamado quando atende aos requisitos e afeta a sessão de alguma forma.
fulfillment do gerenciador	Se um manipulador for chamado, um fulfillment opcional será usado para criar respostas para os usuários finais. Essas respostas são definidas nos dados do agente estático ou recuperadas dinamicamente do serviço de webhook.
Destino da transição do gerenciador	Se um manipulador for chamado, um destino de transição opcional será usado para alterar a página atual. A próxima página só pode ser uma página inicial de fluxo ou uma página dentro do fluxo ativo no momento.

Há dois tipos de manipuladores de estado com requisitos de gerenciador diferentes:

Termo	Definição
Rotas	Rotas são chamadas quando uma entrada de usuário final corresponde a uma intent e/ou quando alguma condição no status da sessão é atendida. Uma rota com um requisito de intent também é chamada de rota de intent. Uma rota com apenas um requisito de condição também é chamada de rota de condição.
Manipuladores de eventos	Os manipuladores de eventos são chamados quando um evento é invocado. Alguns eventos integrados são acionados quando a entrada inesperada do usuário final é recebida ou quando ocorre um erro do webhook. Também é possível definir eventos personalizados que são invocados quando algo acontece fora da conversa.

Há três etapas para processar um manipulador de estado:

Termo	Definição
1. Scope	O manipulador precisa estar no escopo para ter efeito na sessão. O escopo é determinado pela aplicação de um gerenciador a um fluxo, a uma página ou a um parâmetro de formulário, e se o fluxo associado estiver ativo, a página associada estiver ativa ou se o agente estiver tentando preencher o parâmetro do formulário associado.
2. Avaliação	Cada manipulador no escopo é avaliado em ordem. Se os requisitos de um manipulador forem atendidos, ele será aprovado na avaliação.
3. Chamada	Se um manipulador estiver no escopo e passar na avaliação, ele será chamado. Qualquer fulfillment associado será chamado, e qualquer meta de transição associada será aplicada à sessão.

escopo

Para que um manipulador seja avaliado, ele precisa estar no escopo. O escopo do manipulador é uma ferramenta importante e eficiente que ajuda você a controlar a conversa. Ao controlar o escopo de um manipulador, você pode controlar:

X	Item
	Quando uma intent pode ser correspondida
	Quando uma condição precisa ser verificada
	Quando um determinado evento pode ser manipulado
	Quando uma transição de página pode ocorrer
	Quando uma resposta de conclusão estática é fornecida
	Quando um fulfillment ativado para webhook é chamado para respostas dinâmicas

O escopo é determinado se um manipulador for aplicado a um fluxo, a uma página ou a um parâmetro de formulário, e se o fluxo associado estiver ativo, a página associada estiver ativa ou se o agente estiver tentando preencher o parâmetro de formulário associado.

As regras de escopo detalhadas são as seguintes:

Rotas aplicadas ao fluxo ativo:
- Se a página atual for a página inicial do fluxo, ela estará no escopo.
- Se a página atual não for a página inicial do fluxo, ela estará no escopo somente se tiver um requisito de intent.
As rotas aplicadas à página atual estão no escopo.
Os manipuladores de eventos aplicados ao fluxo ativo estão no escopo.
Os manipuladores de evento aplicados à página atual estão no escopo.
Os manipuladores de evento aplicados a um parâmetro de formulário que o agente está tentando preencher no escopo.

Rotas

As rotas têm dois requisitos, e um ou ambos precisam ser fornecidos. Se os dois requisitos forem fornecidos, ambos precisarão ser atendidos para chamar o trajeto:

Termo	Definição
Requisito de intent	Uma intent que precisa corresponder à entrada do usuário final para a rodada de conversa atual. Quando uma rota tem um requisito de intent, ela é chamada de rota de intent.
Requisito de condição	Uma condição que precisa ser atendida. Quando uma rota tem um requisito de condição, ela é chamada de rota de condição.

Você pode aplicar rotas a fluxos (rotas no nível de fluxo) e a páginas (rotas no nível da página). Por exemplo, é possível usar rotas nas seguintes situações:

X	Item
	Quando a entrada do usuário final corresponde a uma intent, a correspondência precisa acionar uma resposta de fulfillment estático.
	Quando a entrada do usuário final corresponde a uma intent, a correspondência precisa acionar um fulfillment ativado para webhook para uma resposta dinâmica.
	Quando a entrada do usuário final fornece o parâmetro de formulário final exigido, uma verificação de condição aciona uma transição de sessão para outra página.
	Quando a entrada do usuário final tiver fornecido um parâmetro de formulário específico, uma verificação de condição acionará uma resposta de fulfillment estático.
	Uma verificação de condição definida como `true` que força uma transição de página.

Propagação de intents

Normalmente, quando uma rota é chamada devido a uma intent correspondente, ela é consumida. Uma intent consumida não pode ser correspondida novamente, a menos que uma nova entrada de usuário final acione uma nova correspondência de intent. No entanto, é possível propagar uma correspondência de intent de um fluxo para outro no seguinte cenário:

Uma rota em flow F1 tem intent I1 como um requisito e flow F2 como um destino de transição.
Flow F2 tem uma rota que também tem intent I1 como um requisito.

Nesse caso, quando a rota em flow F1 é chamada, intent I1 é correspondido duas vezes para uma única entrada de usuário final, e ambas as rotas são chamadas.

Propagar intents é útil para:

X	Item
	Altere a página atual para uma página específica em outro fluxo (a rota do fluxo de destino de transição tem uma página de destino de transição específica).
	Crie uma mensagem de entrada para a página inicial de um fluxo (a rota do fluxo de conversão de transição tem um fulfillment).

Grupos de rotas

Ao criar um agente, é possível descobrir que muitas páginas têm um conjunto comum de rotas. Para tornar os trajetos reutilizáveis, você pode definir grupos de trajetos. Esses grupos são um recurso para todo o fluxo.

Por exemplo, você pode querer que seu fluxo lide com a entrada do usuário final, como "Quero adicionar uma cobertura à minha pizza" e "Quero alterar o tamanho da minha bebida". Essas entradas devem ser tratadas quando qualquer uma das várias páginas do fluxo estiver ativa. É possível definir duas rotas com intents para processar essas entradas em todas as páginas relevantes, mas isso é muito trabalho duplicado. Em vez disso, é possível definir o grupo de rotas uma vez e adicionar uma referência ao grupo em todas as páginas relevantes.

Rotas de nível de fluxo

Rotas no nível do fluxo são rotas aplicadas a um fluxo adicionando-as à página inicial do fluxo. Esses tipos de manipuladores têm os seguintes casos de uso:

X	Item
	Manipuladores com um requisito de intent ou condição no escopo da página inicial do fluxo.
	Os manipuladores com um requisito de intent no escopo de todas as páginas dentro do fluxo.

Para criar rotas no nível do fluxo no console, faça o seguinte:

Abra a página de início do fluxo.
Clique no botão adicionar no cabeçalho Rotas.
O painel de edição de trajeto é aberto.
Forneça campos de trajeto.
Clique em Save.

Para reordenar rotas de nível de fluxo no console:

Abra a página de início do fluxo.
Clique no título Rotas.
O painel da lista de trajetos é aberto.
Arraste as rotas na ordem desejada. Como alternativa, clique no menu de opção e selecione Mover para.

Para excluir rotas no nível do fluxo no console, faça o seguinte:

Abra a página de início do fluxo.
Clique no título Rotas.
O painel da lista de trajetos é aberto.
Clique no menu de opções .
Selecione Excluir.

Rotas no nível da página

Rotas no nível da página são rotas aplicadas a uma página. Esses tipos de manipuladores têm os seguintes casos de uso:

X	Item
	Manipuladores com uma exigência de intent ou condição no escopo quando páginas específicas estão ativas.

Para criar rotas no nível da página no console:

Abra a página, não a página inicial do fluxo.
Clique no botão adicionar no cabeçalho Rotas.
O painel de edição de trajeto é aberto.
Forneça campos de trajeto.
Clique em Save.

Para reordenar rotas no nível da página no console:

Abra a página, não a página inicial do fluxo.
Clique no título Rotas.
O painel da lista de trajetos é aberto.
Arraste as rotas na ordem desejada. Como alternativa, clique no menu de opção e selecione Mover para.

Para excluir rotas no nível da página no console:

Abra a página, não a página inicial do fluxo.
Clique no título Rotas.
O painel da lista de trajetos é aberto.
Clique no menu de opções .
Selecione Excluir.

Manipuladores de eventos

Os manipuladores de eventos têm um requisito para serem chamados:

Termo	Definição
Requisito do evento	Um evento que precisa ser invocado. Os eventos são identificados pelo nome. Alguns eventos integrados são invocados quando a entrada inesperada do usuário final é recebida ou quando ocorre um erro do webhook. Também é possível definir eventos personalizados que são invocados quando algo acontece fora da conversa.

Você pode aplicar manipuladores de eventos a fluxos (manipuladores de eventos no nível do fluxo), páginas (manipuladores de eventos no nível da página) e parâmetros (manipuladores de eventos no nível do parâmetro). Por exemplo, você pode usar manipuladores de eventos nas seguintes situações:

X	Item
	Quando a entrada do usuário final não corresponde a nenhuma intent, um manipulador de eventos no-match fornece uma resposta fulfillment estática específica.
	Um timer expira no sistema, e você quer fornecer informações de lembrete ao usuário final com uma resposta de fulfillment estático específica.

Manipuladores de eventos no nível do fluxo

Os manipuladores de eventos no nível do fluxo são manipuladores de eventos aplicados a um fluxo. Esses tipos de manipuladores têm os seguintes casos de uso:

X	Item
	Manipuladores com um requisito de evento no escopo da página inicial do fluxo.
	Os manipuladores com um requisito de evento no escopo de todas as páginas dentro do fluxo.
	Lidar com entradas inesperadas do usuário final, compartilhadas por todas as páginas em um fluxo.
	Lidar com erros de webhook, compartilhados por todas as páginas em um fluxo.
	Lidar com eventos personalizados invocados pelo sistema, compartilhados por todas as páginas em um fluxo.

Cada fluxo tem manipuladores de eventos para o no-match e no-input eventos integrados. Esses manipuladores de eventos são criados automaticamente quando você cria um fluxo e não podem ser excluídos.

Para criar manipuladores de eventos no nível de fluxo do console:

Abra a página de início do fluxo.
Clique no botão de adição no cabeçalho Manipuladores de eventos.
O painel de manipulador de eventos é aberto.
Forneça campos do manipulador de eventos.
Clique em Save.

Para excluir manipuladores de eventos no nível do fluxo no console:

Abra a página de início do fluxo.
Clique no título Manipuladores de evento.
O painel da lista de manipuladores de eventos é aberto.
Passe o cursor do mouse sobre um manipulador de eventos e clique no botão de exclusão .

Manipuladores de eventos no nível da página

Os manipuladores de eventos no nível da página são manipuladores de eventos aplicados a uma página. Esses tipos de manipuladores têm os seguintes casos de uso:

X	Item
	Manipualdres com um requisito de evento no escopo quando páginas específicas estão ativas.
	Lidar com entradas inesperadas do usuário final específicas de uma página.
	Como lidar com erros de webhook, específicos de uma página.
	Lidar com eventos personalizados invocados pelo sistema, específicos de uma página.

Para criar manipuladores de eventos no nível da página usando o console:

Abra uma página, não a página inicial do fluxo.
Se não houver um cabeçalho Event manipuladores, clique em Adicionar estado do manipulador, selecione Manipuladores de evento e clique em Aplicar.
Clique no botão de adição no cabeçalho Manipuladores de eventos.
O painel de manipulador de eventos é aberto.
Forneça campos do manipulador de eventos.
Clique em Save.

Para excluir manipuladores de eventos no nível da página no console:

Abra uma página, não a página inicial do fluxo.
Clique no título Manipuladores de evento.
O painel da lista de manipuladores de eventos é aberto.
Passe o cursor do mouse sobre um manipulador de eventos e clique no botão de exclusão .

Manipuladores de eventos no nível do parâmetro

Os manipuladores de eventos no nível do parâmetro são manipuladores de eventos aplicados a um parâmetro de formulário. Eles também são conhecidos como gerenciadores de solicitações novas (reprompt). Esses manipuladores de eventos não permitem eventos personalizados, pois se destinam especificamente a processar entradas de usuário final inválidas durante o preenchimento do formulário.

Esses tipos de manipuladores têm os seguintes casos de uso:

X	Item
	O usuário final não forneceu uma entrada válida quando solicitado a preencher um parâmetro de formulário.

Para criar manipuladores de eventos no nível do parâmetro do console:

Abra uma página que contenha parâmetros de formulário.
Clique em um parâmetro.
O painel de parâmetros é aberto.
Role para baixo até a seção Reprompt manipuladores de eventos e clique em Adicionar manipulador de eventos.
O painel de manipulador de eventos é aberto.
Forneça campos do manipulador de eventos.
Clique em Save.

Para excluir manipuladores de eventos no nível do parâmetro do console:

Abra uma página que contenha parâmetros de formulário.
Clique em um parâmetro.
O painel de parâmetros é aberto.
Role para baixo até a seção Reprompt manipuladores de eventos.
Passe o cursor do mouse sobre um manipulador de eventos e clique no botão de exclusão .

Eventos integrados

Os eventos a seguir são integrados e invocados pelo Dialogflow. Alguns eventos são restritos a determinados níveis.

Nome do evento	Nível do fluxo	Nível da página	Nível do parâmetro	Quando foi invocado
`sys.no-match-default`	✔	✔	✔	No nível do fluxo ou da página: a entrada do usuário final não corresponde a nenhuma intent para gerenciadores no escopo. Para o nível de parâmetro: a entrada do usuário final não satisfaz o parâmetro do formulário.
`sys.no-match-[1-6]`	✔	✔	✔	Se você fornecer gerenciadores para qualquer um desses eventos numerados, eles serão invocados em vez de `sys.no-match-default` e na ordem: `sys.no-match-1`, `sys.no-match-2`, ...
`sys.no-input-default`	✔	✔	✔	A entrada do usuário final não foi recebida. Isso pode ser invocado quando: O Dialogflow recebe entradas de texto do usuário final vazias. O Dialogflow recebe uma entrada de áudio do usuário final vazia ou não contém nenhuma fala reconhecida. Um tempo limite de fala desativado ocorre antes que a entrada de áudio do usuário final contenha qualquer fala reconhecida.
`sys.no-input-[1-6]`	✔	✔	✔	Se você fornecer gerenciadores para qualquer um desses eventos numerados, eles serão invocados em vez de `sys.no-input-default` e na ordem: `sys.no-input-1`, `sys.no-input-2`, ...
`sys.invalid-parameter`			✔	Invocado quando uma resposta de webhook invalida o parâmetro definindo `WebhookResponse.pageInfo.formInfo.parameterInfo.state` como `INVALID`.
`sys.long-utterance`	✔	✔	✔	A entrada do usuário final excede o comprimento máximo permitido (256 caracteres). Se não fornecida, o Dialogflow tratará a fala longa do usuário como `no-match`. Para entradas de áudio de streaming, esse evento é acionado somente depois que o cliente fecha o stream de áudio.
`webhook.error`	✔	✔		A chamada do webhook retornou um erro. Este evento é invocado somente: 1) se não houver um manipulador de eventos de webhook detalhado (por exemplo, webhook.error.timeout) que corresponda ao código de erro do webhook, 2) se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.
`webhook.error.timeout`	✔	✔		A chamada do webhook expirou. Um evento de webhook só será invocado se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.
`webhook.error.bad-request`	✔	✔		O webhook retornou 400 Bad Request. Um evento de webhook só será invocado se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.
`webhook.error.rejected`	✔	✔		O webhook retornou 401 authorized ou 403 Forbidden. Um evento de webhook só será invocado se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.
`webhook.error.unavailable`	✔	✔		O webhook retornou a mensagem 503 Service Unavailable. Um evento de webhook só será invocado se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.
`webhook.error.not-found`	✔	✔		A chamada do webhook falhou porque o URL do webhook estava inacessível. Um evento de webhook só será invocado se não houver um destino de transição definido na rota original que chamou o fulfillment com o webhook com falha. Consulte a seção Ordem de avaliação para mais detalhes.

Eventos personalizados

É possível criar eventos personalizados e manipuladores de eventos. Os eventos personalizados são usados para lidar com eventos que acontecem fora da conversa com o usuário final. Por exemplo, o usuário final clicou em um botão, passou um certo período, o inventário disponível foi alterado durante a conversa e assim por diante.

Os eventos são identificados apenas pelo nome. Evite usar nomes de eventos que começam com sys. ou webhook. para evitar conflito com eventos incorporados.

Para invocar um evento com a API, consulte o campo queryInput.event do método detectIntent para o tipo Session.

Selecione um protocolo e uma versão para a referência de sessão:

Protocolo	V3	V3beta1
REST	Recurso da sessão	Recurso da sessão
RPC (remote procedure call)	Interface da sessão	Interface da sessão
C++	SessionsClient	Indisponível
C#	SessionsClient	Indisponível
Go	SessionsClient	Indisponível
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Indisponível	Indisponível
Python	SessionsClient	SessionsClient
Ruby	Indisponível	Indisponível

Ordem de avaliação

Os manipuladores são avaliados em uma ordem específica. Aplicam-se as seguintes regras gerais:

Somente manipuladores no escopo são avaliados.
Somente os manipuladores com requisitos que podem ser atendidos podem ser chamados.
Se um manipulador sem um destino de transição for chamado, a avaliação da lista de gerenciadores continuará. Devido a essa regra, vários fulfillments podem adicionar mensagens à fila de resposta.
Se um manipulador com um destino de transição for chamado, a avaliação da lista de manipuladores será concluída.
Se um gerenciador com fulfillment for chamado e o fulfillment resultar em um erro de webhook:
- Se o gerenciador tiver um destino de transição definido, o webhook falhará silenciosamente.
- Quando um manipulador de eventos está no escopo do evento, ele manipula o evento e a avaliação da lista de manipuladores termina.
- Se nenhum manipulador de eventos estiver no escopo do evento, o webhook falhará silenciosamente.
Quando o requisito da intent é atendido, a intent é consumida, portanto, apenas o primeiro gerenciador de rotas encontrado para a intent pode ser chamado. Consulte Propagação da intent para ver as exceções.
Quando uma condição de condição é atendida, a condição não é consumida. Portanto, várias rotas com a condição podem ser chamadas.
Quando um requisito de evento é atendido, o evento é consumido. Portanto, somente o primeiro manipulador de eventos encontrado para o evento pode ser chamado.
A pilha de chamadas do gerenciador pode afetar a ordem de avaliação.

Há três fases na avaliação:

As rotas que têm um requisito de intent são avaliadas nesta ordem:
1. Nível da página: rotas individuais aplicadas à página atual, na ordem fornecida.
2. Grupos no nível da página: grupos de rota aplicados à página atual, na ordem fornecida.
3. Nível do fluxo: rotas aplicadas ao fluxo ativo, na ordem fornecida.
4. Grupos no nível do fluxo: grupos de rotas aplicados ao fluxo ativo, na ordem fornecida.
Rotas apenas com um requisito de condição são avaliadas nesta ordem:
1. Nível da página: rotas individuais aplicadas à página atual, na ordem fornecida.
2. Grupos no nível da página: grupos de rota aplicados à página atual, na ordem fornecida.
3. Nível de fluxo (somente se a página atual for a página inicial de fluxo): rotas aplicadas ao fluxo ativo, na ordem fornecida de dados.
4. Grupos no nível do fluxo (somente se a página atual for a página inicial do fluxo): grupos de rotas aplicados à conta ativa fluxo, na ordem fornecida.
Os manipuladores de evento são avaliados nesta ordem:
1. Nível do parâmetro: os manipuladores de eventos aplicados ao parâmetro do formulário da página que o agente está tentando preencher (gerenciadores de reprompts) na ordem fornecida.
2. Nível da página: manipuladores de eventos aplicados à página atual, na ordem fornecida.
3. Nível de fluxo: manipuladores de eventos aplicados ao fluxo ativo, na ordem fornecida.

Alvos de transição simbólica

Ao inserir uma meta de transição para um manipulador, é possível inserir fluxos ou páginas específicos, assim como inserir metas de transição simbólica:

Alvo de transição simbólica	Descrição
`START_PAGE`	Transição para a página inicial do fluxo ativo com nome semelhante.
`END_FLOW`	Encerre o fluxo ativo e volte para a página que causou uma transição para o fluxo atual. Consulte também Limite de pilha de chamadas e de fluxos do gerenciador.
`END_SESSION`	Limpe a sessão atual e faça a transição para a página especial chamada `END_SESSION`. A próxima entrada do usuário reiniciará a sessão na página inicial do Fluxo de início padrão.
`PREVIOUS_PAGE`	Transição para a página anterior que causou a transição para a página atual. O estado da página anterior será restaurado após a transição.
`CURRENT_PAGE`	Faça a transição novamente para a página atual. Isso pode ser útil se você quiser que o agente repita algo.

Limite da pilha de chamadas e de fluxos do gerenciador

Pilha de chamadas do gerenciador

Quando uma sessão passa para END_FLOW, ela retorna à página de chamada que causou a transição para o fluxo concluído. Nesse caso, a pilha de chamadas do gerenciador é preservada. Todos os gerenciadores que foram avaliados anteriormente na página de chamada serão ignorados e os gerenciadores restantes serão avaliados em ordem.

Exemplo:

A página P tem três gerenciadores nesta ordem: H1, H2, H3.
H1 é avaliada, mas não causa uma transição.
H2 é avaliada e causa uma transição para o fluxo F.
Uma página no fluxo F passa para END_FLOW.
A sessão retorna à página P, que fica ativa novamente com um estado preservado.
A avaliação do gerenciador na página P continua do status preservado, portanto, H3 é avaliada.

Limite da pilha de fluxo

Quando uma sessão passa de fluxo para fluxo, cada fluxo é enviado para a pilha de fluxo, que tem um limite máximo de pilha de 25. Exceder o limite máximo da pilha pode fazer com que os fluxos sejam retirados da pilha, levando a um comportamento inesperado ao usar a transição END_FLOW. Para evitar esses possíveis problemas, minimize o número de transições de fluxo para fluxo antes da transição END_FLOW.

Definir condições

Para definir condições com o console, são fornecidas regras de condição com uma das três opções lógicas:

Corresponder pelo menos uma regra (OU)
Corresponder a TODAS as regras (AND)
Personalizar expressão

Por conveniência, você pode usar as opções AND/OR para criar condições simples ou compostas para valores de parâmetro.

Use a opção livre Personalizar expressão para todos os tipos de condições, incluindo funções do sistema e constantes booleanas.

Por exemplo, para definir uma condição com 10% de chance de aprovação na avaliação, selecione a opção Personalizar expressão e digite $sys.func.rand() < 0.1 em Condição:

Captura de tela da configuração de uma condição personalizada

Pages

Intents