Um webhook pode ser padrão ou flexível. Com um webhook padrão, os campos de solicitação e resposta são definidos por agentes de conversação (Dialogflow CX). Com um webhook flexível, você define os campos de solicitação e resposta.
Webhooks padrão
Com webhooks padrão, você usa mensagens de solicitação e resposta definidas por agentes de conversação (Dialogflow CX). 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 do parâmetro de sessão e as respostas definidas pelo agente são incluídos.
Solicitação de webhook padrão
Quando um
fulfillment
com um webhook é chamado,
os agentes de conversação (Dialogflow CX) enviam 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 informações adicionais.
Por exemplo, a
integração do gateway telefônico 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 de webhook padrão
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 do recurso de webhook
Confira a seguir as configurações de recursos de webhooks padrão:
Termo | Definição |
---|---|
Nome de exibição | O nome mostrado no console para o webhook. |
Tempo limite do webhook | Quando os agentes de conversação (Dialogflow CX) enviam uma solicitação de webhook para o serviço de webhook, o tempo limite pode ser atingido enquanto aguarda uma resposta. Essa configuração controla o tempo limite em segundos. Se ocorrer um tempo limite, os agentes de conversação (Dialogflow CX) vão invocar um evento webhook.error.timeout. |
Tipo | Defina como Diretório de serviços se você usar o diretório de serviços para acesso a redes privadas. 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 do ambiente | É possível fornecer webhooks específicos do ambiente. |
Autenticação | Consulte a seção de autenticação. |
Certificado de CA personalizado | Ele é usado para fazer upload de certificados de AC personalizados. |
Webhooks flexíveis
Com webhooks flexíveis, você define o método HTTP da solicitação, os parâmetros de URL da solicitação e os campos das mensagens de solicitação e resposta. A solicitação só pode fornecer valores de parâmetros selecionados, e a resposta só pode fornecer valores de substituição de parâmetros. Essa limitação é benéfica, porque simplifica a interface entre o agente e o webhook. Raramente é necessário comunicar algo além dos valores dos parâmetros de sessão entre um agente e um webhook. Isso também simplifica a implementação do webhook, porque as mensagens de solicitação e resposta contêm apenas o que você precisa, e você pode fornecer mensagens de webhook exclusivas para vários cenários.
Solicitação de webhook flexível
Ao criar o recurso de webhook para o agente, especifique o seguinte para solicitações de webhook:
- O método HTTP usado para solicitações de webhook enviadas para seu serviço de webhook.
- Valores de parâmetro de sessão que os agentes de conversação (Dialogflow CX) precisam enviar ao serviço de webhook usando o URL.
- Se você escolher
POST
,PUT
ouPATCH
como o método, é possível especificar valores de parâmetro de sessão que os agentes de conversação (Dialogflow CX) precisam enviar para o serviço de webhook pelo corpo JSON da solicitação.
Para enviar valores de parâmetro de sessão usando o URL da solicitação ou o corpo JSON, use referências de parâmetro como de costume. Não é necessário usar a codificação de URL na referência do parâmetro nem colocar a referência entre aspas. No momento da execução, os agentes de conversação (Dialogflow CX) vão escapar o valor do parâmetro no URL conforme necessário. Uma lista ou um valor composto será fornecido como JSON.
Ao usar uma referência de parâmetro no corpo JSON, é necessário colocar a referência entre aspas, independentemente do tipo do parâmetro. Se o parâmetro for um valor numérico escalar, de lista ou composto, os agentes de conversação (Dialogflow CX) vão remover as aspas ao enviar a solicitação no momento da execução para preservar o tipo de dados do parâmetro. Os tipos escalares de string vão continuar entre aspas. Se um valor escalar, de lista ou composto numérico for referenciado em um valor de string (por exemplo: "Este é um número: $session.params.size"), o parâmetro será tratado como uma string ("Este é um número: 3").
Por exemplo,
é possível fornecer os valores dos parâmetros de sessão fruit
e size
ao URL da solicitação desta forma:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
E, para o corpo JSON da solicitação, como este:
{
"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 os agentes de conversação (Dialogflow CX) precisam definir em campos específicos da resposta do webhook no momento da 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 flexíveis de recursos de webhook
Confira a seguir as configurações de recursos de webhooks flexíveis:
Termo | Definição |
---|---|
Nome de exibição | O nome mostrado no console para o webhook. |
Tempo limite do webhook | Quando os agentes de conversação (Dialogflow CX) enviam uma solicitação de webhook para o serviço de webhook, o tempo limite pode ser excedido enquanto aguarda uma resposta. Essa configuração controla o tempo limite em segundos. Se ocorrer um tempo limite, os agentes de conversação (Dialogflow CX) vão invocar um evento webhook.error.timeout. |
Tipo | Defina como Diretório de serviços se você usar o diretório de serviços para acesso a redes privadas. 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, que pode incluir referências a parâmetros de sessão. |
Subtipo | Definir como Flexível |
Método | Defina o método HTTP para a solicitação de webhook. |
Corpo da solicitação | Forneça o corpo JSON da solicitação conforme descrito acima. |
Configuração de resposta | Informe os parâmetros da sessão que precisam ser definidos nos campos de resposta conforme descrito acima. |
Webhook específico do ambiente | É possível fornecer webhooks específicos do ambiente. |
Autenticação | Consulte a seção de autenticação. |
Certificado de CA personalizado | Ele é usado para fazer upload de certificados de AC personalizados. |
Usar um modelo personalizado predefinido
O Dialogflow oferece modelos personalizados predefinidos que podem ser usados para integrar webhooks flexíveis ao CRM do Salesforce.
Na guia Gerenciar, clique em Webhooks e em + Criar.
Em Subtipo, selecione Flexível.
Clique em Configurar usando o modelo predefinido para ativar o recurso.
No menu suspenso Tipo de integração, selecione Salesforce.
No menu suspenso Nome da API, selecione um nome de API. O modelo preenche automaticamente o formulário do webhook com base no nome da API que você escolhe.
É possível configurar manualmente os campos a seguir, se aplicável, com base nos seus parâmetros:
- URL do webhook
- Método
- JSON do corpo da solicitação
- Configuração da resposta
Os campos obrigatórios do OAuth serão destacados na seção Autenticação.
Clique em Salvar para criar o webhook.
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 seja hospedado como uma função do Cloud Run ou 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.
Autenticação
É importante proteger seu serviço de webhook para que somente você ou seu agente de conversação (Dialogflow CX) sejam autorizados a fazer solicitações. Isso é configurado ao criar um recurso de webhook. Os agentes de conversação (Dialogflow CX) são compatíveis com os seguintes mecanismos de autenticação:
Termo | Definição |
---|---|
Cabeçalhos de autenticação | Para as configurações do webhook, é possível especificar pares de chave-valor de cabeçalho HTTP opcionais. Se fornecidos, os agentes de conversação (Dialogflow CX) adicionam esses cabeçalhos HTTP às solicitações de webhook. É comum fornecer um único par com uma chave de authorization . Os valores do cabeçalho oferecem suporte a referências de parâmetro de sessão e análise de função do sistema, como em mensagens de resposta estáticas. |
Autenticação básica com nome de usuário e senha | Para as configurações do webhook, é possível especificar valores opcionais de nome de usuário e senha de login. Se fornecido, os agentes de conversação (Dialogflow CX) adicionam 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 do OAuth de terceiros para que os agentes de conversação (Dialogflow CX) troquem um token de acesso do sistema OAuth e o adicionem ao cabeçalho HTTP de autorização. Somente o fluxo de credenciais do cliente é aceito. |
Tokens de acesso do agente de serviço | É possível selecionar o token de acesso na autenticação do agente de serviço para usar tokens de acesso do agente de serviço para autenticação. Isso pode ser usado para acessar outras APIs do Google Cloud. |
Tokens de ID do agente de serviço | É possível selecionar o token de ID na autenticação do agente de serviço para usar tokens de ID do agente de serviço para autenticação. Ele pode ser usado para acessar funções e serviços do Cloud Run. |
Autenticação TLS mútua | Consulte a documentação sobre Autenticação TLS mútua. |
OAuth de terceiros
Os agentes de conversação (Dialogflow CX) podem coletar um token de acesso de um provedor OAuth de terceiros e adicioná-lo ao cabeçalho HTTP de autorização ao fazer solicitações de webhook.
Confira a seguir as configurações de recursos para OAuth de terceiros:
Termo | Definição |
---|---|
ID do cliente | O ID do cliente a ser usado ao solicitar um token OAuth. |
Chave secreta do cliente | A chave secreta a ser usada ao solicitar um token OAuth. |
URL do endpoint OAuth | O URL a ser usado para solicitar um token OAuth. |
Escopos do OAuth | Uma lista separada por vírgulas de escopos para os quais o token do OAuth pode ser usado. |
As solicitações enviadas ao URL do endpoint OAuth para receber um token não incluem os cabeçalhos de solicitação personalizados configurados para a solicitação de webhook. É possível transmitir informações personalizadas ao servidor OAuth como parâmetros na string de consulta do URL do endpoint OAuth.
Tokens de acesso do agente de serviço
Os agentes de conversação (Dialogflow CX) podem gerar um token de ID ou token de acesso usando o agente de serviço de agentes de conversação (Dialogflow CX).
O token é adicionado no cabeçalho HTTP de autorização quando os agentes de conversação (Dialogflow CX) chamam um webhook.
Token de ID
Um token de ID pode ser usado para acessar funções e serviços do Cloud Run depois que você concede a função de invocador a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
O público-alvo usado para gerar o token de ID será o URL completo 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, opcionalmente, validar o token usando bibliotecas de cliente do Google ou bibliotecas de código aberto, como github.com/googleapis/google-auth-library-nodejs (em inglês).
Token de acesso
Um token de acesso pode ser usado para acessar outras APIs do Google Cloud depois que você conceder as funções necessárias a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Verificação do certificado HTTPS
Por padrão, os agentes de conversação (Dialogflow CX) usam 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 do ambiente
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.
Isso permite que você desenvolva e teste com segurança as atualizações do 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. Depois da criação, você também pode editar as configurações do recurso de 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 que você quer editar.
- Insira as configurações do recurso de webhook padrão ou do recurso 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 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 webhook | Recurso 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 de 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, os agentes de conversação (Dialogflow CX) invocam um erro de webhook ou um evento integrado de tempo limite e continuam 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.
Novas tentativas automáticas
Os agentes de conversação (Dialogflow CX) incluem mecanismos internos que tentam novamente automaticamente em determinados erros de webhook para melhorar a robustez. Somente erros não terminais são retentativas (por exemplo, erros de tempo limite ou de conexão).
Para reduzir a probabilidade de chamadas duplicadas:
- Defina limites de tempo limite de webhook mais longos.
- Ofereça suporte à idempotencia na lógica do webhook ou faça a deduplicação.
Como usar as funções do Cloud Run
Os agentes de conversação (Dialogflow CX) se integram às funções do Cloud Run, para que você crie facilmente um webhook seguro e sem servidor. Se você criar uma função que resida no mesmo projeto do agente, basta selecionar Autentificação do agente de serviço -> Token de ID na configuração de autenticação. O agente poderá chamar o webhook com segurança.
No entanto, há duas situações em que é preciso configurar essa integração manualmente:
- A conta de serviço
do agente de serviço de agentes de conversação (Dialogflow CX)
com o endereço a seguir precisa existir para o projeto de agente:
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, você pode acionar a criação desta conta de serviço especial:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- 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 de agentes de conversação (Dialogflow CX) no projeto da função.
- Selecione Autentificação do agente de serviço -> Token de ID na seção "Configuração de autenticação".
Como usar webhooks conteinerizados e o framework Go ezcx
Se você quiser implementar um webhook conteinerizado usando Go, consulte o framework Go ezcx. Esse framework pode simplificar muitas das etapas necessárias para criar um webhook.
Como usar funções do Cloud Run com tráfego somente interno
As funções do Cloud Run configuradas para aceitar tráfego interno de redes VPC no mesmo projeto ou no mesmo perímetro VPC SC podem ser usadas como um webhook, desde que o agente esteja no mesmo projeto ou no mesmo perímetro VPC SC.
Como usar o diretório de serviços para acesso a redes privadas
Os agentes de conversação (Dialogflow CX) se integram 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 de agentes de conversação (Dialogflow CX) com o endereço a seguir precisa existir para o projeto de agente:
Conceda à conta de serviço do Agente de serviço de agentes de conversação (Dialogflow CX) os seguintes papéis do IAM:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
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 webhook Recurso 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 resolver problemas, configure uma verificação de tempo de atividade particular para verificar se o Diretório de serviços está configurado corretamente.
Amostras e solução de problemas
Consulte o guia de instruções do webhook.