Alguns produtos e recursos estão sendo renomeados. Os recursos de playbook generativo e de fluxo também estão sendo migrados para um único console consolidado. Confira os detalhes.
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
O tráfego de rede iniciado pelo Dialogflow para solicitações de webhook é enviado em uma rede pública.
Para garantir que o tráfego seja seguro e confiável em ambas as direções, o Dialogflow é compatível com a autenticação TLS mútua (mTLS) (em inglês).
Durante o handshake de TLS padrão do Dialogflow,
o servidor de webhook apresenta um certificado que pode ser validado pelo Dialogflow,
seguindo a cadeia de autoridades certificadoras
ou comparando o certificado a um certificado de AC personalizado.
Ao ativar o mTLS no servidor de webhook, ele poderá autenticar o certificado do Google apresentado pelo Dialogflow para validação, concluindo o estabelecimento de confiança mútua.
Como solicitar mTLS
Para solicitar mTLS:
Prepare o servidor HTTPS de webhook para solicitar o certificado do cliente durante o handshake de TLS.
O servidor de webhook verifica o certificado do cliente ao recebê-lo.
Instale uma cadeia de certificados para seu servidor de webhook. É possível que ele seja mutuamente confiável tanto pelo cliente quanto pelo servidor.
Os aplicativos que se conectam aos Serviços do Google
precisam confiar em todas as autoridades de certificação listadas nos
Serviços de confiança do Google.
Faça o download de certificados raiz em:
https://pki.goog/.
Exemplo de chamada para um servidor de webhook usando mTLS
Este exemplo usa o agente mostrado no início rápido com um servidor de webhook
executando
openssl.
Exemplo de configuração
Um agente do Dialogflow CX que recebe pedidos de camisetas e os envia para um webhook que aponta para um servidor da Web independente.
Uma chave privada para comunicação TLS em um arquivo chamado
key.pem.
Uma solicitação é enviada ao agente de uma máquina cliente. Neste exemplo, a solicitação é
"Quero comprar uma camisa vermelha grande". Essa solicitação pode ser enviada usando o
Console do Dialogflow ou por uma chamada de API.
Saída de openssl s_server na máquina do servidor.
verify depth is 1
Using default temp DH parameters
ACCEPT
depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1
verify return:1
depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1D4
verify return:1
depth=0 CN = *.dialogflow.com
verify return:1
-----BEGIN SSL SESSION PARAMETERS-----
MII...
-----END SSL SESSION PARAMETERS-----
Client certificate
-----BEGIN CERTIFICATE-----
MII...
-----END CERTIFICATE-----
subject=CN = *.dialogflow.com
issuer=C = US, O = Google Trust Services LLC, CN = GTS CA 1D4
Shared ciphers:TLS_AES_128_GCM_SHA256:...
Signature Algorithms: ECDSA+SHA256:...
Shared Signature Algorithms: ECDSA+SHA256:...
Peer signing digest: SHA256
Peer signature type: RSA-PSS
Supported Elliptic Groups: 0xEAEA:...
Shared Elliptic groups: X25519:...
CIPHER is TLS_AES_128_GCM_SHA256
Secure Renegotiation IS NOT supported
POST /shirts-agent-webhook HTTP/1.1
authorization: Bearer ey...
content-type: application/json
Host: www.example.com
Content-Length: 1595
Connection: keep-alive
Accept: */*
User-Agent: Google-Dialogflow
Accept-Encoding: gzip, deflate, br
{
"detectIntentResponseId": "a7951ce2-2f00-4af5-a508-4c2cb45698b0",
"intentInfo": {
"lastMatchedIntent": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
"parameters": {
"color": {
"originalValue": "red",
"resolvedValue": "red"
},
"size": {
"originalValue": "large",
"resolvedValue": "large"
}
},
"displayName": "order.new",
"confidence": 0.9978873
},
"pageInfo": {
"currentPage": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/flows/00000000-0000-0000-0000-000000000000/pages/06e6fc4d-c2f2-4830-ab57-7a318f20fd90",
"displayName": "Order Confirmation"
},
"sessionInfo": {
"session": "projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/sessions/session-test-001",
"parameters": {
"color": "red",
"size": "large"
}
},
"fulfillmentInfo": {
"tag": "confirm"
},
"messages": [{
"text": {
"text": ["Ok, let\u0027s start a new order."],
"redactedText": ["Ok, let\u0027s start a new order."]
},
"responseType": "ENTRY_PROMPT",
"source": "VIRTUAL_AGENT"
}, {
"text": {
"text": ["You have selected a large, red shirt."],
"redactedText": ["You have selected a large, red shirt."]
},
"responseType": "HANDLER_PROMPT",
"source": "VIRTUAL_AGENT"
}],
"text": "I want to buy a large red shirt",
"languageCode": "en"
}ERROR
shutting down SSL
CONNECTION CLOSED
Certificado do cliente personalizado
Os certificados de cliente personalizados podem ser configurados no nível do agente para serem usados por todos os
webhooks. No momento da invocação do webhook, os certificados configurados serão
apresentados durante o handshake.
A chave privada e a senha longa são configuradas como um recurso do Secret Manager. O agente de serviço do Dialogflow precisa receber permissões de acesso ao secret do Secret Manager.
Os certificados do cliente precisam ser assinados por uma autoridade certificadora para que a
negociação seja bem-sucedida.
Prática recomendada
Para garantir que as solicitações de webhook sejam iniciadas pelos seus próprios agentes do Dialogflow,
verifique o token de identidade do serviço
do Bearer no cabeçalho de autorização da solicitação. Como alternativa, é possível verificar um parâmetro de sessão fornecido anteriormente por um servidor de autenticação do seu lado.
Erros
Se a validação do certificado do cliente falhar,
por exemplo, se o servidor de webhook não confiar no certificado do cliente,
o handshake de TLS falhará e a sessão será encerrada.
Mensagens de erro comuns:
Mensagem de erro
Explicação
Falha ao verificar o certificado do cliente: x509: certificado assinado por autoridade desconhecida
O Dialogflow envia seu certificado de cliente para o webhook externo, mas o webhook não pode verificá-lo. Isso pode acontecer porque o webhook externo não instalou a cadeia de CA corretamente. Todas as CAs raiz do Google são confiáveis.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[[["\u003cp\u003eDialogflow webhook requests travel over a public network, but Mutual TLS (mTLS) can be enabled to secure and authenticate traffic in both directions.\u003c/p\u003e\n"],["\u003cp\u003eEnabling mTLS on your webhook server allows it to validate the Google certificate presented by Dialogflow, establishing mutual trust between the two systems.\u003c/p\u003e\n"],["\u003cp\u003eTo use mTLS, the webhook server must be configured to request and verify the client certificate during the TLS handshake, and use a trusted certificate chain.\u003c/p\u003e\n"],["\u003cp\u003eDialogflow agents can be configured with custom client certificates that are presented during the mTLS handshake with the webhook, which need to be signed by a Certificate Authority.\u003c/p\u003e\n"],["\u003cp\u003eTo ensure the webhook requests are initiated from your Dialogflow agent, verify the Bearer service identity token, or a session parameter provided by your authentication server.\u003c/p\u003e\n"]]],[],null,["# Mutual TLS authentication\n\nThe network traffic initiated by Dialogflow for webhook requests\nis sent on a public network.\nTo ensure that traffic is both secure and trusted in both directions,\nDialogflow optionally supports\n[Mutual TLS authentication (mTLS)](https://en.wikipedia.org/wiki/Mutual_authentication).\nDuring Dialogflow's standard [TLS handshake](https://hpbn.co/transport-layer-security-tls/#tls-handshake),\nyour webhook server presents a certificate that can be validated by Dialogflow,\neither by following the [Certificate Authority chain](https://hpbn.co/transport-layer-security-tls/#chain-of-trust-and-certificate-authorities)\nor by comparing the certificate to a [Custom CA certificate](/dialogflow/cx/docs/concept/custom-ca).\nBy enabling mTLS on your webhook server, it will be able to authenticate\nthe [Google certificate](https://pki.goog/roots.pem) presented by Dialogflow\nto your webhook server for validation, completing the establishment of mutual\ntrust.\n\nRequesting mTLS\n---------------\n\nTo request mTLS:\n\n1. Prepare your webhook HTTPS server to request the client certificate during the TLS handshake.\n2. Your webhook server should verify the client certificate upon receiving it.\n3. Install a certificate chain for your webhook server, which can be mutually trusted by both client and server. Applications connecting to Google services should trust all the Certificate Authorities listed by [Google Trust Services](https://pki.goog/faq/#faq-27). You can download root certs from: \u003chttps://pki.goog/\u003e.\n\nSample call to a webhook server using mTLS\n------------------------------------------\n\nThis example uses the agent shown in the quickstart with a\n[webhook](/dialogflow/cx/docs/concept/webhook) server\nrunning\n[`openssl`](https://www.openssl.org/docs/manmaster/man1/openssl.html).\n\n1. Sample setup\n 1. A Dialogflow CX agent that takes shirt orders, and sends them to a webhook pointing to a standalone web server.\n 2. A private key for TLS communication in a file named `key.pem`.\n 3. A certificate chain signed by a [publicly-trusted\n CA (Certificate Authority)](/load-balancing/docs/ssl-certificates/self-managed-certs#use_a_publicly-trusted_ca) in a file named `fullchain.pem`.\n2. Execute the [`openssl s_server`](https://www.openssl.org/docs/manmaster/man1/openssl-s_server.html) program in the server machine. \n\n ```console\n sudo openssl s_server -key key.pem -cert fullchain.pem -accept 443 -verify 1\n ```\n3. A request is sent to the agent from a client machine. For this example, the request is \"I want to buy a large red shirt\". This request can be sent using the Dialogflow Console, or through an API call.\n4. Output of `openssl s_server` in the server machine. \n\n ```\n verify depth is 1\n Using default temp DH parameters\n ACCEPT\n depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1\n verify return:1\n depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1D4\n verify return:1\n depth=0 CN = *.dialogflow.com\n verify return:1\n -----BEGIN SSL SESSION PARAMETERS-----\n MII...\n -----END SSL SESSION PARAMETERS-----\n Client certificate\n -----BEGIN CERTIFICATE-----\n MII...\n -----END CERTIFICATE-----\n subject=CN = *.dialogflow.com\n\n issuer=C = US, O = Google Trust Services LLC, CN = GTS CA 1D4\n\n Shared ciphers:TLS_AES_128_GCM_SHA256:...\n Signature Algorithms: ECDSA+SHA256:...\n Shared Signature Algorithms: ECDSA+SHA256:...\n Peer signing digest: SHA256\n Peer signature type: RSA-PSS\n Supported Elliptic Groups: 0xEAEA:...\n Shared Elliptic groups: X25519:...\n CIPHER is TLS_AES_128_GCM_SHA256\n Secure Renegotiation IS NOT supported\n POST /shirts-agent-webhook HTTP/1.1\n authorization: Bearer ey...\n content-type: application/json\n Host: www.example.com\n Content-Length: 1595\n Connection: keep-alive\n Accept: */*\n User-Agent: Google-Dialogflow\n Accept-Encoding: gzip, deflate, br\n\n {\n \"detectIntentResponseId\": \"a7951ce2-2f00-4af5-a508-4c2cb45698b0\",\n \"intentInfo\": {\n \"lastMatchedIntent\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665\",\n \"parameters\": {\n \"color\": {\n \"originalValue\": \"red\",\n \"resolvedValue\": \"red\"\n },\n \"size\": {\n \"originalValue\": \"large\",\n \"resolvedValue\": \"large\"\n }\n },\n \"displayName\": \"order.new\",\n \"confidence\": 0.9978873\n },\n \"pageInfo\": {\n \"currentPage\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/flows/00000000-0000-0000-0000-000000000000/pages/06e6fc4d-c2f2-4830-ab57-7a318f20fd90\",\n \"displayName\": \"Order Confirmation\"\n },\n \"sessionInfo\": {\n \"session\": \"projects/PROJECT_ID/locations/REGION/agents/AGENT_ID/sessions/session-test-001\",\n \"parameters\": {\n \"color\": \"red\",\n \"size\": \"large\"\n }\n },\n \"fulfillmentInfo\": {\n \"tag\": \"confirm\"\n },\n \"messages\": [{\n \"text\": {\n \"text\": [\"Ok, let\\u0027s start a new order.\"],\n \"redactedText\": [\"Ok, let\\u0027s start a new order.\"]\n },\n \"responseType\": \"ENTRY_PROMPT\",\n \"source\": \"VIRTUAL_AGENT\"\n }, {\n \"text\": {\n \"text\": [\"You have selected a large, red shirt.\"],\n \"redactedText\": [\"You have selected a large, red shirt.\"]\n },\n \"responseType\": \"HANDLER_PROMPT\",\n \"source\": \"VIRTUAL_AGENT\"\n }],\n \"text\": \"I want to buy a large red shirt\",\n \"languageCode\": \"en\"\n }ERROR\n shutting down SSL\n CONNECTION CLOSED\n \n ```\n\nCustom Client Certificate\n-------------------------\n\nCustom client certificates can be configured at an agent level to be used by all\nwebhooks. At the time of webhook invocation, the configured certificates will be\npresented during the handshake.\n\nThe private key and passphrase are configured as a Secret Manager\nresource. The Dialogflow service agent will need to be given Secret\nManager Secret Accessor permissions to the secret.\n\nThe client certificates need to be signed by a Certificate Authority for the\nhandshake to be successful.\n\n\nBest Practice\n-------------\n\nTo make sure that webhook requests are initiated from your own Dialogflow agents,\nyou should verify the Bearer\n[service identity token](/dialogflow/cx/docs/concept/webhook#id-token)\nfrom the request's Authorization header. Alternatively, you can verify a session\nparameter provided previously by an authentication server on your side.\n\nErrors\n------\n\nIf the client certificate validation fails\n(for example, the webhook server does not trust the client certificate),\nthe TLS handshake fails and the session terminates.\n\nCommon error messages:"]]
