Um webhook pode ser padrão ou flexível. Com um webhook padrão, os campos de solicitação e resposta são definidos pelo Dialogflow. Com um webhook flexível, você define os campos de solicitação e resposta.
Webhooks padrão
Com os webhooks padrão, você usa mensagens de solicitação e resposta definidas pelo Dialogflow. A mensagem de solicitação fornece muitos detalhes sobre a sessão. Por exemplo, a página ativa atual, a intent correspondente recente, os valores de parâmetro da sessão e as respostas definidas pelo agente estão incluídos.
Solicitação de webhook padrão
Quando um fulfillment com um webhook é chamado, o Dialogflow envia uma solicitação de webhook POST HTTPS para seu serviço de webhook.
O corpo dessa solicitação é um objeto JSON WebhookRequest
com informações sobre a sessão.
Algumas
integrações
preenchem o campo WebhookRequest.payload
com mais informações.
Por exemplo, a integração do gateway de telefone do Dialogflow CX fornece o identificador de chamadas do usuário final.
Consulte a
documentação de referência de
WebhookRequest
(V3)
ou WebhookRequest
(V3Beta1)
para mais detalhes.
Resposta padrão do webhook
Uma vez que seu serviço de webhook recebe uma solicitação de webhook, ela precisa enviar uma resposta a um webhook. As seguintes limitações se aplicam à sua resposta:
- A resposta precisa ocorrer dentro de um tempo limite que você configura ao criar o recurso de webhook. Caso contrário, a solicitação atingirá o tempo limite.
- É necessário que o tamanho da resposta seja menor ou igual a 64 KiB.
Consulte a
documentação de referência de
WebhookResponse
(V3)
ou WebhookResponse
(V3Beta1)
para mais detalhes.
Configurações padrão de recursos de webhook
Veja a seguir as configurações de recursos para webhooks padrão:
Termo | Definição |
---|---|
Nome de exibição | O nome do webhook exibido no console. |
Tempo limite do webhook | Quando o Dialogflow envia uma solicitação ao seu serviço de webhook, ele pode atingir o tempo limite enquanto aguarda uma resposta. Essa configuração controla esse tempo limite em segundos. Se ocorrer um tempo limite, o Dialogflow invocará um evento webhook.error.timeout. |
Tipo | Defina como Diretório de serviços se você estiver usando o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço da Web genérico. |
URL do webhook | Informe o endereço do URL do serviço de webhook. |
Subtipo | Definido como Padrão |
Webhook específico para ambiente | É possível fornecer webhooks específicos do ambiente. |
Proporção de Eficiência Energética (EER) | Consulte a seção de autenticação. |
Certificado de CA personalizado | Essa informação é usada para fazer upload de certificados de CA personalizados. |
Webhooks flexíveis
Com eles, você define o método HTTP da solicitação, os parâmetros do URL da solicitação e os campos das mensagens de solicitação e resposta. A solicitação só pode fornecer valores de parâmetro selecionados e a resposta só pode fornecer valores de substituição de parâmetro. Essa limitação é realmente benéfica porque simplifica a interface entre o agente e o webhook. Raramente é necessário comunicar algo diferente de valores de parâmetros de sessão entre um agente e um webhook. Ele também simplifica a implementação do webhook porque as mensagens de solicitação e resposta contêm apenas o que você precisa, além de permitir que você forneça mensagens exclusivas para vários cenários.
Solicitação de webhook flexível
Ao criar o recurso de webhook para seu agente, especifique o seguinte para solicitações de webhook:
- O método HTTP usado para solicitações de webhook enviadas ao seu serviço de webhook.
- Valores de parâmetro de sessão que o Dialogflow deve enviar ao serviço de webhook usando o URL.
- Se você escolher
POST
,PUT
ouPATCH
como o método, poderá especificar os valores de parâmetro da sessão que o Dialogflow precisará enviar ao serviço de webhook por meio do corpo JSON da solicitação.
Para enviar valores de parâmetro de sessão usando o URL da solicitação ou o corpo do JSON, use as referências de parâmetros como você faria normalmente. Não é necessário usar o escape de URL da referência de parâmetro e não coloque a referência entre aspas. No ambiente de execução, o Dialogflow fará o escape de URL do valor do parâmetro conforme necessário. Um valor composto ou de lista é fornecido como JSON.
Ao usar uma referência de parâmetro no corpo do JSON, você precisa colocar a referência entre aspas, independente do tipo do parâmetro. Se o parâmetro for realmente um valor numérico, de lista ou composto, o Dialogflow removerá as aspas ao enviar a solicitação no ambiente de execução para preservar o tipo de dados do parâmetro. Os tipos escalares de string vão permanecer entre aspas. Se um valor escalar numérico, de lista ou composto for referenciado em um valor de string (por exemplo: "This is a number: $session.params.size"), o parâmetro será tratado como uma string ("This is a number: 3").
Por exemplo,
é possível fornecer os valores de parâmetro de sessão fruit
e size
ao URL da solicitação da seguinte maneira:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
E no corpo JSON da solicitação:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Resposta flexível do webhook
Ao criar o recurso de webhook para seu agente, é possível especificar parâmetros de sessão que o Dialogflow precisa definir como campos específicos da resposta do webhook no ambiente de execução.
As seguintes limitações se aplicam à sua resposta:
- A resposta precisa ocorrer dentro de um tempo limite que você configura ao criar o recurso de webhook. Caso contrário, a solicitação atingirá o tempo limite.
- É necessário que o tamanho da resposta seja menor ou igual a 64 KiB.
Use o seguinte formato para especificar um campo escalar, de lista ou composto:
$.fully.qualified.path.to.field
Por exemplo, considere a seguinte resposta JSON:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Para especificar o campo "value", use o seguinte:
$.routes[0].legs[0].distance.value
Configurações de recursos de webhook flexível
Veja a seguir as configurações de recursos para webhooks flexíveis:
Termo | Definição |
---|---|
Nome de exibição | O nome do webhook exibido no console. |
Tempo limite do webhook | Quando o Dialogflow envia uma solicitação ao seu serviço de webhook, ele pode atingir o tempo limite enquanto aguarda uma resposta. Essa configuração controla esse tempo limite em segundos. Se ocorrer um tempo limite, o Dialogflow invocará um evento webhook.error.timeout. |
Tipo | Defina como Diretório de serviços se você estiver usando o diretório de serviços para acesso à rede privada. Caso contrário, defina como Serviço da Web genérico. |
URL do webhook | Informe o endereço de URL do serviço de webhook, que pode incluir referências a parâmetros de sessão. |
Subtipo | Definido como Flexível |
Método | Defina o método HTTP para a solicitação do webhook. |
Corpo da solicitação | Forneça o corpo JSON da solicitação conforme descrito acima. |
Configuração de resposta | Informe os parâmetros de sessão que precisam ser definidos para os campos de resposta conforme descrito acima. |
Webhook específico para ambiente | É possível fornecer webhooks específicos do ambiente. |
Proporção de Eficiência Energética (EER) | Consulte a seção de autenticação. |
Certificado de CA personalizado | Essa informação é usada para fazer upload de certificados de CA personalizados. |
Requisitos de serviço do webhook
Os seguintes requisitos devem ser atendidos pelo serviço do webhook:
- Ele precisa processar solicitações HTTPS. O HTTP não é compatível. Se você hospedar seu serviço de webhook no Google Cloud Platform usando uma solução de computação ou computação sem servidor, consulte a documentação do produto para veiculação com HTTPS. Para conhecer outras opções de hospedagem, consulte Adquira um certificado SSL para seu domínio.
- O URL para solicitações precisa ser acessível publicamente, a menos que esteja hospedado como uma função do Cloud ou seja acessado como um webhook do diretório de serviços.
- Ele precisa processar solicitações e respostas conforme descrito na seção Webhook padrão ou Webhook flexível.
- Se o agente não se integrar ao acesso à rede particular do Diretório de serviços, as chamadas do webhook serão consideradas fora do perímetro de serviço e bloqueadas ao ativar o VPC Service Controls. Endpoints limitados são compatíveis com o Diretório de serviços. Consulte Diretório de serviços para detalhes.
Proporção de Eficiência Energética (EER)
É importante proteger seu serviço de webhook para que somente você ou seu agente do Dialogflow sejam autorizados a fazer solicitações. Isso é configurado ao criar um recurso de webhook. O Dialogflow CX é compatível com os seguintes mecanismos de autenticação:
Termo | Definição |
---|---|
Cabeçalhos de autenticação | Para configurações do webhook, especifique pares de chave-valor do cabeçalho HTTP opcionais. Se fornecidos, o Dialogflow adiciona esses cabeçalhos HTTP às solicitações de webhook. É comum fornecer um único par com uma chave de authorization . Os valores do cabeçalho são compatíveis com referências de parâmetros de sessão e análise de funções do sistema, como em mensagens de resposta estáticas. |
Autenticação básica com nome de usuário e senha | Nas configurações do webhook, é possível especificar valores opcionais de nome de usuário e senha. Se fornecido, o Dialogflow adiciona um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho tem o seguinte formato: "authorization: Basic <base 64 encoding of the string username:password>" . |
OAuth de terceiros | É possível especificar a configuração de OAuth de terceiros para que o Dialogflow troque um token de acesso do provedor de OAuth e o adicione ao cabeçalho HTTP de autorização. Somente o fluxo de credenciais do cliente é aceito. |
Tokens de acesso do agente de serviço | Selecione o token de acesso na autenticação do agente de serviço para usar tokens de acesso do agente de serviço na autenticação. Isso pode ser usado para acessar outras APIs do Google Cloud. |
Tokens de ID do agente de serviço | Selecione o token de ID na autenticação do agente de serviço para usar tokens de ID do agente de serviço na autenticação. Isso pode ser usado para acessar os serviços do função do Cloud e do Cloud Run. Se nenhuma outra opção de autenticação for usada, esse recurso será ativado por padrão. |
Autenticação TLS mútua | Consulte a documentação Autenticação TLS mútua. |
Verificação do certificado HTTPS
Por padrão, o Dialogflow usa o armazenamento de confiança padrão do Google para verificar certificados HTTPS. Se você quiser usar certificados não reconhecidos pelo armazenamento de confiança padrão do Google para seu servidor HTTPS, como certificados autoassinados ou certificados raiz personalizados, consulte Certificados de CA personalizados.
Webhooks específicos para ambientes
Se você estiver usando ambientes para isolar sistemas de produção de sistemas de desenvolvimento (recomendado), configure os webhooks para serem específicos do ambiente. Para cada recurso de webhook definido, é possível fornecer configurações de URL e autenticação exclusivas para cada ambiente definido para o agente.
Dessa forma, é possível desenvolver e testar com segurança as atualizações de código do webhook antes de implantá-las na produção.
Criar ou editar recursos de webhook
Depois de ter um serviço de webhook em execução, você precisa criar um recurso de webhook no agente que tenha informações de conectividade e autenticação. Após a criação, você também poderá editar as configurações do recurso do webhook a qualquer momento.
Para criar ou editar um recurso de webhook:
Console
- Abra o Console do Dialogflow CX.
- Escolha seu projeto do Google Cloud.
- Selecione seu agente.
- Selecione a guia Gerenciar.
- Clique em Webhooks.
- Clique em Criar ou em um recurso de webhook na lista para editar.
- Insira as configurações de recurso de webhook padrão ou as configurações de recursos de webhook flexível.
- Clique em Salvar.
API
Para criar um recurso de webhook, consulte o método create
para o tipo Webhook
.
Para editar um recurso de webhook (exceto para configurações específicas do ambiente), consulte o método patch
ou update
para o tipo Webhook
.
Selecione um protocolo e uma versão para a referência do Webhook:
Protocolo | V3 | V3beta1 |
---|---|---|
REST | Recurso de webhook | Recurso de webhook |
RPC | Interface do webhook | Interface do webhook |
C++ | WebhooksClient | Indisponível |
C# | WebhooksClient | Indisponível |
Go | WebhooksClient | Indisponível |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Indisponível | Indisponível |
Python | WebhooksClient | WebhooksClient |
Ruby | Indisponível | Indisponível |
Para editar as configurações específicas do ambiente para um webhook,
consulte o método patch
ou update
para o tipo Environment
.
Selecione um protocolo e uma versão para a Referência de ambiente:
Protocolo | V3 | V3beta1 |
---|---|---|
REST | Recurso do ambiente | Recurso do ambiente |
RPC (remote procedure call) | Interface do ambiente | Interface do ambiente |
C++ | EnvironmentsClient | Indisponível |
C# | EnvironmentsClient | Indisponível |
Go | EnvironmentsClient | Indisponível |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Indisponível | Indisponível |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Indisponível | Indisponível |
Erros de webhook
Se o serviço de webhook encontrar um erro ao processar uma solicitação do webhook, o código do webhook retornará um dos seguintes códigos de status HTTP:
400
Solicitação inválida401
Não autorizado403
Proibido404
Não encontrado500
Falha no servidor503
Serviço não disponível
Em qualquer uma das situações de erro a seguir, o Dialogflow invoca um erro de webhook ou evento integrado de tempo limite e continua processando normalmente:
- Tempo limite de resposta excedido.
- Código de status de erro recebido.
- A resposta é inválida.
- O serviço de webhook não está disponível.
Além disso, se a chamada de serviço do webhook tiver sido acionada por uma chamada de API de intent de detecção, o campo queryResult.webhookStatuses
na resposta de intent de detecção conterá as informações de status do webhook.
Como usar o Cloud Functions
O Dialogflow se integra ao Cloud Functions para que você crie facilmente um webhook seguro e sem servidor. Se você criar uma função que resida no mesmo projeto do agente, ele poderá chamar com segurança o webhook sem precisar de nenhuma configuração especial.
No entanto, há duas situações em que é preciso configurar essa integração manualmente:
- A conta de serviço
do agente de serviço do Dialogflow
com o endereço a seguir precisa existir para o projeto de agente:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Essa conta de serviço especial e a chave associada normalmente são criadas automaticamente quando você cria o primeiro agente de um projeto. Se o agente foi criado antes de 1º de novembro de 2020, a criação dessa conta de serviço especial pode ser acionada:- Crie um novo agente para o projeto.
- execute o seguinte comando:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se a função do webhook residir em um projeto diferente do agente, forneça o Papel do IAM Invocador do Cloud Functions à conta de serviço Agente de serviço do Dialogflow no projeto da função.
Como usar webhooks conteinerizados e o framework Go ezcx
Se você quiser implementar um webhook em contêiner usando Go, consulte a framework do Go ezcx. Esse framework pode simplificar muitas das etapas necessárias ao criar um webhook.
Como usar o diretório de serviços para acesso a redes privadas
O Dialogflow integra-se ao acesso à rede particular do Diretório de serviços para que ele possa se conectar aos destinos do webhook dentro da rede VPC. Isso mantém o tráfego na rede do Google Cloud e aplica o IAM e o VPC Service Controls.
Para configurar um webhook que segmenta uma rede privada:
Siga a configuração de rede particular do Diretório de serviços para configurar sua rede VPC e o endpoint do Diretório de serviços.
A conta de serviço do agente de serviço do Dialogflow com o endereço a seguir precisa existir para o projeto de agente:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Conceda à conta de serviço do Agente de serviço do Dialogflow os seguintes papéis do IAM:servicedirectory.viewer
do projeto do diretório de serviçosservicedirectory.pscAuthorizedService
do projeto de rede
Forneça o serviço do diretório de serviços com o URL e informações de autenticação opcionais ao criar o webhook.
Console
API
Veja o campo
serviceDirectory
para o tipoWebhook
.Selecione um protocolo e uma versão para a referência do Webhook:
Protocolo V3 V3beta1 REST Recurso de webhook Recurso de webhook RPC Interface do webhook Interface do webhook C++ WebhooksClient Indisponível C# WebhooksClient Indisponível Go WebhooksClient Indisponível Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Indisponível Indisponível Python WebhooksClient WebhooksClient Ruby Indisponível Indisponível
Para solucionar problemas, configure uma verificação de tempo de atividade particular para confirmar se o Diretório de serviços está configurado corretamente.
Autenticação do agente de serviço
O Dialogflow pode gerar um token de ID ou token de acesso usando o agente de serviço do Dialogflow (em inglês).
O token é adicionado ao cabeçalho HTTP de autorização quando o Dialogflow chama um webhook.
Token de ID
Um token de ID pode ser usado para acessar os serviços do função do Cloud e do Cloud Run depois que você concede o papel Invocador ao
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comSe os serviços do função do Cloud e do Cloud Run estiverem no mesmo projeto de recursos, você não precisará de outras permissões do IAM para chamá-los.
O público-alvo usado para gerar o token de ID será todo o URL do webhook, exceto os parâmetros de consulta. Se você estiver usando o Cloud Run, verifique se esse URL é aceito pelos públicos-alvo do Cloud Run. Por exemplo, se o URL do webhook for
https://myproject.cloudfunctions.net/my-function/method1?query=value
o URL a seguir precisa estar em públicos-alvo personalizados.
https://myproject.cloudfunctions.net/my-function/method1
Qualquer webhook também pode validar o token usando bibliotecas de cliente do Google ou de código aberto, como github.com/googleapis/google-auth-library-nodejs.
Token de acesso
Um token de acesso pode ser usado para acessar outras APIs do Google Cloud depois que você concede os papéis necessários para
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Amostras e solução de problemas
Consulte o guia de instruções do webhook.