Fulfillments

No turno de conversas do agente, ele precisa responder ao usuário final com uma resposta a uma pergunta, uma consulta de informações ou o encerramento da sessão. O agente também pode precisar entrar em contato com seu serviço para gerar respostas dinâmicas ou realizar ações por uma volta. O fulfillment é usado para fazer tudo isso.

Um fulfillment pode conter:

• Mensagens de resposta estática.
• Chamadas de webhook para respostas dinâmicas e/ou para realizar ações.
• Predefinições de parâmetros para definir ou substituir valores de parâmetros.

Durante a rodada de um agente, é possível (e às vezes desejável) chamar vários fulfillments, e cada um deles pode gerar uma mensagem de resposta. O Dialogflow CX mantém essas respostas em uma fila de respostas. Depois que a rodada do agente terminar, o Dialogflow CX enviará as respostas ordenadas ao usuário final.

Casos de uso de fulfillment

O fulfillment permite fornecer mensagens de resposta nos seguintes locais:

• Fulfillment de entrada de página
• Rotas
• Manipuladores de eventos
• Solicitações iniciais para formulários
• Gerenciadores de prompts para formulários

Para cada um desses casos de uso, o console abre um painel de edição de fulfillment.

Respostas do agente (opções de diálogo)

Defina mensagens de resposta do agente no momento do design ao criar o fulfillment. No ambiente de execução, essas respostas são adicionadas à fila de respostas.

Há vários tipos de mensagens de resposta, que são descritos nas subseções a seguir. Ao usar o console, um painel de fulfillment tem um cartão inicial de diálogo do agente, mas é possível clicar em Adicionar resposta de diálogo para adicionar mais cartões para outros tipos de mensagens de resposta.

Resposta de texto estático

As mensagens de resposta de texto estático fornecem diálogo de texto ao usuário. Se as chamadas de API de intent de detecção ou de integração usarem a síntese de fala, esse texto vai gerar conteúdo de áudio. Para essas mensagens, o texto fornecido usa a Linguagem de marcação de síntese de fala (SSML).

É possível definir vários cartões de resposta de texto e várias respostas de texto em cada cartão. Se você definir vários cartões, eles serão concatenados para uma única resposta no ambiente de execução. Se você definir várias respostas dentro de um cartão, uma das mensagens no cartão será selecionada aleatoriamente no ambiente de execução.

Essas mensagens de texto podem conter referências de parâmetro e funções do sistema in-line.

Payload personalizado

Algumas integrações são compatíveis com uma resposta de payload personalizada para lidar com respostas avançadas. Esses payloads personalizados precisam ser fornecidos no formato JSON definido na documentação de integração. Por exemplo, consulte o formato de payload personalizado do Dialogflow CX Messenger.

É possível incluir referências de parâmetros no seu JSON de payload personalizado. Coloque-os entre aspas duplas para tratá-los como valores de string JSON. Exemplo:

{
  "someField": "$session.params.date"
}

O JSON de payload personalizado precisa ser limitado a 24 níveis de profundidade.

Também é possível enviar um payload personalizado para as integrações que você desenvolve. Por não ser processado pelo Dialogflow CX, ele precisará ser manipulado na sua própria lógica de negócios.

Para mais informações, consulte Modelos de payload personalizados.

Transferência de agente ao vivo

Essa resposta sinaliza ao autor da chamada da API de intent de detecção que a conversa precisa ser enviada a um agente humano. O Dialogflow CX usa esse sinal apenas para identificar conversas entregues para fins de medição, sem alterar o estado da sessão.

Seu sistema ou integração pode usar esse sinal para executar as ações necessárias para entregar a conversa. Como o Dialogflow CX não impõe nenhuma estrutura nesses dados, é possível escolher qualquer estrutura que se encaixe no seu sistema.

Metadados de conversação bem-sucedida

Essa resposta sinaliza ao autor da chamada da API de intent de detecção que a conversa com o agente do Dialogflow CX foi bem-sucedida. O Dialogflow CX usa esse sinal para identificar conversas que foram bem-sucedidas para fins de medição e não muda o estado da sessão de forma alguma.

O sistema ou a integração pode usar esse sinal para realizar as ações necessárias. O Dialogflow CX não impõe nenhuma estrutura nesses dados. Assim, é possível escolher qualquer estrutura que se encaixe no seu sistema.

Ouvir áudio pré-gravado

Essa resposta reproduz um arquivo de áudio para integrações compatíveis com esse recurso.

Os requisitos de formato de arquivo de áudio podem ser diferentes para integrações diferentes. Por exemplo, consulte os requisitos do Dialogflow CX Phone Gateway.

Para integrações de telefonia de parceiros, o parceiro precisa ter acesso ao URL do arquivo de áudio. Um URL disponível publicamente, como um arquivo público no Cloud Storage, sempre pode ser acessado pelo parceiro. O parceiro também pode fornecer acesso restrito a arquivos de áudio. Consulte a documentação do parceiro para mais detalhes.

Texto de saída de áudio

Essa resposta é semelhante à resposta de texto, mas só é aplicável à síntese de fala. Se o agente processar sessões de texto e voz, use respostas de texto e texto de áudio de saída exclusivas para criar uma experiência do usuário diferente no texto. Voz. Se o texto de saída de áudio for fornecido para uma sessão de voz, as respostas de texto simples serão ignoradas.

Se o agente processar sessões de texto e voz, e você quiser as mesmas mensagens de resposta, basta usar respostas de texto para sessões de texto e de voz.

O texto de áudio de saída é concatenado de forma semelhante às respostas de texto. Se as respostas de texto de áudio de saída forem uma mistura de texto e SSML, o resultado concatenado será tratado como SSML. O ideal é usar texto ou SSML de maneira consistente.

Resposta condicional

Esse tipo de resposta fornece respostas condicionais:

Este é o formato geral:

if [condition]
  [response]
elif [condition]
  [response]
elif [condition]
  [response]
else
  [response]
endif

em que:

• [condition] usa o mesmo formato que condições de rota.
• [response] é uma resposta de texto.
• Os blocos elif e else são opcionais.

Exemplo:

if $session.params.user-age >= 21
  Ok, you may enter.
else
  Sorry, you cannot enter.
endif

Tanto [condition] quanto [response] podem usar funções in-line do sistema para gerar valores dinâmicos durante as conversas. Para mais informações, consulte Funções do sistema e Condições de rota. A [condition] é resolvida com base no estado da sessão no início do fulfillment. Se a [response] depender do estado da sessão, ela será resolvida com base no estado atualizado da sessão no final do fulfillment.

Para agentes multilíngues, [condition] é comum para todos os idiomas, enquanto [response] é específico de um idioma. Quando você altera [condition] para um idioma no console, essa parte é atualizada em todos os idiomas do agente. Como se torna uma nova condição, [response] é apagado para todos os idiomas diferente do idioma selecionado ao atualizar o [condition].

Transferência de chamada telefônica

As transferências de chamadas estão disponíveis apenas para o Dialogflow CX Phone Gateway.

Para algumas integrações de telefonia, é possível especificar um número de telefone nos EUA para transferências de chamadas. No ambiente de execução, quando o agente do Dialogflow CX aciona um fulfillment com a transferência de chamada, a chamada é transferida para o número especificado, e o processamento do agente é suspenso.

Resposta da ferramenta de repositório de dados

Esse tipo de resposta configura as respostas do agente retornadas pelas ferramentas de repositório de dados vinculadas . Se você configurou uma ferramenta de repositório de dados nesse fulfillment, um cartão de resposta da ferramenta de repositório de dados será preenchido automaticamente.

• Links de origem:defina o número máximo de citações a serem retornadas ao usuário após a resposta. Uma citação é um link para a fonte de informações no repositório de dados, renderizado como botões. O padrão é 1.
• Citações in-line:limite o número de citações in-line retornadas por frase em vez de listar links após a resposta.
• Fallback generativo:configure o agente para tentar uma resposta gerada por IA se o repositório de dados retornar um resultado vazio. Se isso falhar, o agente usará respostas estáticas.
• Respostas estáticas: Insira respostas de texto estático no campo final para enviar ao usuário palavra por palavra.

Mensagens de resposta específicas do canal

Ao definir o fulfillment, é possível criar mensagens de resposta específicas do canal para criar respostas segmentadas para chat de texto, voz, SMS ou integrações específicas que aceitam canais. Todas as mensagens de resposta que não são específicas de um canal são chamadas de mensagens de resposta padrão.

No ambiente de execução, o Dialogflow CX seleciona a mensagem de resposta padrão ou uma mensagem de resposta específica do canal quando uma solicitação de intent de detecção especifica um canal. Como prática recomendada, defina mensagens de resposta padrão, mesmo que você esteja usando mensagens de resposta específicas do canal. As mensagens de resposta padrão atuam como um fallback quando o sistema não consegue fornecer um canal válido.

Um nome de canal é um campo personalizado que pode ser definido como qualquer texto. Se você usar a API Dialogflow CX diretamente para chamadas de ambiente de execução, poderá usar os nomes de canal que quiser. Se você usar uma integração atual, será necessário usar os nomes de canal que a integração reconhece.

Como definir mensagens de resposta específicas do canal no momento do design

Para fornecer mensagens de resposta específicas do canal para fulfillment ao usar o console:

• Clique em Adicionar canal depois de adicionar mensagens de resposta padrão para adicionar mensagens de resposta específicas do canal. Clique em Adicionar canal novamente para adicionar outros canais.

Para fornecer mensagens de resposta específicas do canal para fulfillment ao usar a API:

• Defina o campo Fulfillment.messages[i].channel para o canal escolhido para cada mensagem de resposta. Se esse campo não estiver definido, a resposta será tratada como uma mensagem de resposta padrão.

Como usar mensagens de resposta específicas do canal no ambiente de execução

Se você estiver usando uma integração atual que aceita canais, a implementação da integração vai executar essas etapas.

Para receber uma mensagem de resposta específica do canal, é necessário especificar o canal na mensagem de solicitação de intent de detecção. Consulte o campo queryParams.channel no método detectIntent do tipo Sessions. Acessar a referência da API 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

Fechar

O Dialogflow CX retorna a mensagem de resposta padrão se uma solicitação não definir um canal ou se o fulfillment não encontrar um canal correspondente.

Modelos de payload personalizados

Se você usa payloads personalizados com frequência, use modelos de payload personalizados. Os payloads personalizados às vezes são grandes e complexos. Portanto, o uso de modelos simplifica o processo de criação de agentes.

Forneça esses modelos nas configurações do agente para que eles fiquem disponíveis para seleção ao criar o fulfillment do agente.

Por exemplo, o payload JSON para os botões "sim" e "não" pode ser definido como modelos de payload personalizados. Ao criar um fulfillment que exige esses botões, selecione o modelo ao criar o fulfillment.

Quando você seleciona um modelo para um payload personalizado de fulfillment, o conteúdo do modelo é inserido no payload. Em seguida, é possível editar o payload conforme necessário.

Se você mudar um modelo, as mudanças não serão propagadas automaticamente para todos os payloads de fulfillment em que ele foi referenciado.

Para criar um modelo de payload personalizado, consulte as configurações gerais do agente.

Para selecionar um modelo de payload personalizado ao criar o fulfillment, clique em Selecionar modelo ao criar um payload personalizado de fulfillment.

Chamadas de webhook

Quando um fulfillment aciona um webhook, o agente envia uma solicitação ao seu serviço. O webhook pode realizar ações, fornecer mensagens de resposta dinâmicas, modificar os valores dos parâmetros e alterar a página atual.

A seguir, descrevemos as configurações de webhook para fulfillment:

X	Item
Ativar webhook	Isso ativa o webhook para o fulfillment.
Webhook	Selecione o recurso de webhook.
Tag	A tag de texto fornecida aqui será preenchida no campo WebhookRequest.fulfillmentInfo.tag da solicitação de webhook enviada ao serviço de webhook. Isso pode ser usado para controlar o comportamento do webhook de uma maneira específica do fulfillment.
Retornar resposta parcial	Permite o cancelamento de uma reprodução de resposta parcial. Para mais detalhes, consulte Configurações avançadas de fala.

Predefinições de parâmetros

Use o fulfillment para fornecer predefinições que definem ou modifiquem os valores de parâmetros atuais. Essas predefinições são aplicadas antes de resolver mensagens de resposta estática ou chamar um webhook.

Também é possível usar funções do sistema para predefinir um parâmetro para um valor gerado dinamicamente.

Estes são alguns exemplos:

• Como definir um parâmetro now para o horário atual:

  Parâmetro	Valor
  now	$sys.func.NOW()

• Incrementar um parâmetro atual counter em 1:

  Parâmetro	Valor
  Contador	$sys.func.ADD($session.params.counter, 1)

• Como definir um parâmetro new-cost para o valor de parâmetro other-cost, mantendo o valor completo do objeto composto:

  Parâmetro	Valor
  new-cost	$sys.func.IDENTITY($session.params.other-cost)

Ferramentas de repositório de dados

Para mais informações sobre esse recurso, consulte a documentação das ferramentas de repositório de dados.

Configurações avançadas de fala

Essas configurações avançadas de fala podem substituir as configurações de fala da página, configurações de fala do fluxo, e configurações de fala do agente.

Fila de resposta

Durante a rodada de um agente, é possível chamar vários fulfillments, e cada um deles pode gerar uma mensagem de resposta. O Dialogflow CX mantém essas respostas em uma fila de respostas.

Resposta parcial para a API Streaming

Por padrão, o Dialogflow CX só envia respostas ordenadas aos usuários finais depois que a rodada do agente termina. Também é possível ativar a opção Retornar resposta parcial no fulfillment para retornar respostas na fila como uma resposta parcial ao usar as APIs de streaming. Para saber mais, consulte Ciclo de vida de uma página.

Por exemplo, se o webhook provavelmente for executado por muito tempo, adicione uma resposta estática no fulfillment e ative a resposta parcial. Isso faz o Dialogflow CX limpar a fila de respostas e enviar todas as mensagens como uma resposta parcial antes de chamar o webhook.

A resposta parcial não é aceita para o seguinte:

• Entradas de áudio no simulador.
• As integrações de telefonia de parceiros podem não aceitar respostas parciais. Consulte a documentação do parceiro para verificar.

Para testar esse recurso no simulador, ative a resposta parcial.

No exemplo a seguir, considere que o webhook leva cinco segundos para ser concluído e você não ativa a resposta parcial. A vez de conversar com o agente do Dialogflow CX não é concluída até que o webhook seja concluído. Durante essa sequência de cinco segundos, as respostas são colocadas na fila enquanto aguardam o webhook e não são retornadas ao usuário final até que a conversão seja concluída. Isso leva a uma experiência negativa do usuário.

Se você ativar a resposta parcial no primeiro fulfillment, o Dialogflow CX retornará a primeira mensagem rapidamente e chamará o webhook. Depois que o webhook for concluído, o Dialogflow CX retornará a resposta final. Esse cenário melhora a experiência do usuário final porque ele é informado de que precisa aguardar um curto período. Além disso, a chamada do webhook é executada simultaneamente com uma resposta enviada ao usuário final.

Linguagem de marcação de síntese de voz (SSML)

É possível usar a Linguagem de marcação de síntese de voz (SSML) em campos de fulfillment de texto ou texto de áudio de saída. Isso permite personalizar a resposta de áudio fornecendo detalhes sobre pausas e formatação de áudio para acrônimos, datas, horas, abreviaturas ou texto que deva ser censurado.

Para detalhes de sintaxe, consulte a documentação de SSML do Text-to-Speech.

**Observação**: um campo de fulfillment pode ter no máximo um par de tags <speak></speak>.