Console
    Contact Us Start free

    Interactions with the API

    For each conversational turn, an interaction takes place. During an interaction, an end-user sends input to Conversational Agents (Dialogflow CX), and Conversational Agents (Dialogflow CX) sends a response. You have two options when implementing your system to handle interactions: using the API or using an integration.

    When using the API, your system needs to handle the following:

    • Build an agent.
    • Provide a user interface for end-users.
    • Call the Dialogflow API for each conversational turn to send end-user input to the API.
    • Unless your agent responses are purely static (uncommon), you need to host a webhook service to handle webhook-enabled fulfillment .

    When using an integration , your system only needs to handle the following:

    • Build an agent.
    • Optionally implement a webhook service.

    The following diagram shows the steps that take place for one conversational turn of a session.

    API flow diagram.

    1. The end-user types or says something, known as end-user input .
    2. Your user interface or integration system receives the input and forwards it to the Dialogflow API in a detect intent request.
    3. The Dialogflow API receives the detect intent request. It matches the input to an intent or form parameter, sets parameters as needed, and updates session state. If it needs to call a webhook-enabled fulfillment, it sends a webhook request to your webhook service, otherwise, go to step 6.
    4. Your webhook service receives the webhook request. Your service takes any actions necessary, like calling external APIs, querying or updating a database, etc.
    5. Your webhook service builds a response and sends a webhook response back to Conversational Agents (Dialogflow CX).
    6. Conversational Agents (Dialogflow CX) creates a detect intent response. If a webhook was called, it uses the response provided in the webhook response. If no webhook was called, it uses the static response defined in the agent. Conversational Agents (Dialogflow CX) sends a detect intent response to your user interface or integration system.
    7. Your user interface or integration system receives the detect intent response and forwards the text or audio response to the end-user.
    8. The end-user sees or hears the response.

    Guide purpose

    This guide shows you how to call the API for one conversational turn for an agent that is not using an integration (step 2 from diagram above). This guide does not show you how to implement a user interface for your end-user.

    Before you begin

    You should do the following before reading this guide:

    1. Read flow basics .
    2. Perform setup steps .
    3. Create a new agent or continue using the agent you created in Build an agent using flows or Build an agent using playbooks

    Collect IDs

    The samples below require several IDs as input. To find your project ID, region ID, and agent ID:

    Dialogflow CX console

    1. Open the Dialogflow CX console .
    2. Select your Google Cloud project to open the agent selector.
    3. Click the option menu for an agent in the list.
    4. Click the copy name button.
    5. This copies the full identifying name of your agent, which includes your project ID, region ID, and agent ID in the form:
      projects/ PROJECT_ID /locations/ REGION_ID /agents/ AGENT_ID

    AI Applications console

    1. Go to the AI Applications console:

      AI Applications console

    2. Your project ID is shown at the top of the console.

    3. The Locationcolumn shows region IDs.

    4. Select an app.

    5. The browser URL path segment after agents/ contains the agent app ID.

    You also need a session ID. A session represents a conversation between a Conversational Agents (Dialogflow CX) agent and an end-user. You create a unique session ID at the beginning of a conversation and use it for each turn of the conversation. For the purpose of trying the API, you can use any string ID that is at most 36 bytes, like test-session-123 .

    Call detect intent

    The following samples call the Sessions.detectIntent method.

    Select a protocol and version for the Session reference:

    Protocol V3 V3beta1
    REST
    		 Session resource Session resource
    RPC
    		 Session interface Session interface
    C++
    		 SessionsClient Not available
    C#
    		 SessionsClient Not available
    Go
    		 SessionsClient Not available
    Java
    		 SessionsClient SessionsClient
    Node.js
    		 SessionsClient SessionsClient
    PHP
    		 Not available Not available
    Python
    		 SessionsClient SessionsClient
    Ruby
    		 Not available Not available

    REST

    Before using any of the request data, make the following replacements:

    • PROJECT_ID : your Google Cloud project ID
    • AGENT_ID : your agent ID
    • REGION_ID : your region ID
    • SESSION_ID : your session ID
    • END_USER_INPUT : the end-user input

    HTTP method and URL:

    POST https:// REGION_ID 
-dialogflow.googleapis.com/v3/projects/ PROJECT_ID 
/locations/ REGION_ID 
/agents/ AGENT_ID 
/sessions/ SESSION_ID 
:detectIntent

    Request JSON body:

    {
  "queryInput": {
    "text": {
      "text": " END_USER_INPUT 
"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

    To send your request, expand one of these options:

    You should receive a JSON response similar to the following:

    {
  "responseId": "38e8f23d-eed2-445e-a3e7-149b242dd669",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Ok, let's start a new order."
          ]
        }
      },
      {
        "text": {
          "text": [
            "I'd like to collect a bit more information from you."
          ]
        }
      },
      {
        "text": {
          "text": [
            "What color would you like?"
          ]
        }
      },
      {}
    ],
    "currentPage": {
      "name": "projects/ PROJECT_ID 
/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/flows/00000000-0000-0000-0000-000000000000/pages/ce0b88c4-9292-455c-9c59-ec153dad94cc",
      "displayName": "New Order"
    },
    "intent": {
      "name": "projects/ PROJECT_ID 
/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
      "displayName": "order.new"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": { ... },
    "match": {
      "intent": {
        "name": "projects/ PROJECT_ID 
/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
        "displayName": "order.new"
      },
      "resolvedInput": "I want to buy a shirt",
      "matchType": "INTENT",
      "confidence": 1
    }
  }
}

    Java

    To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

      import 
  
 com.google.api.gax.rpc. ApiException 
 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.DetectIntentRequest 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.QueryInput 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.QueryResult 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.SessionName 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.SessionsClient 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.SessionsSettings 
 ; 
 import 
  
 com.google.cloud.dialogflow.cx.v3beta1.TextInput 
 ; 
 import 
  
 com.google.common.collect.Maps 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.List 
 ; 
 import 
  
 java.util.Map 
 ; 
 public 
  
 class 
 DetectIntent 
  
 { 
  
 // DialogFlow API Detect Intent sample with text inputs. 
  
 public 
  
 static 
  
 Map<String 
 , 
  
 QueryResult 
>  
 detectIntent 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 locationId 
 , 
  
 String 
  
 agentId 
 , 
  
 String 
  
 sessionId 
 , 
  
 List<String> 
  
 texts 
 , 
  
 String 
  
 languageCode 
 ) 
  
 throws 
  
 IOException 
 , 
  
  ApiException 
 
  
 { 
  
 SessionsSettings 
 . 
 Builder 
  
 sessionsSettingsBuilder 
  
 = 
  
 SessionsSettings 
 . 
 newBuilder 
 (); 
  
 if 
  
 ( 
 locationId 
 . 
  equals 
 
 ( 
 "global" 
 )) 
  
 { 
  
 sessionsSettingsBuilder 
 . 
 setEndpoint 
 ( 
 "dialogflow.googleapis.com:443" 
 ); 
  
 } 
  
 else 
  
 { 
  
 sessionsSettingsBuilder 
 . 
 setEndpoint 
 ( 
 locationId 
  
 + 
  
 "-dialogflow.googleapis.com:443" 
 ); 
  
 } 
  
 SessionsSettings 
  
 sessionsSettings 
  
 = 
  
 sessionsSettingsBuilder 
 . 
 build 
 (); 
  
 Map<String 
 , 
  
 QueryResult 
>  
 queryResults 
  
 = 
  
 Maps 
 . 
 newHashMap 
 (); 
  
 // Instantiates a client. 
  
 // Note: close() needs to be called on the SessionsClient object to clean up resources 
  
 // such as threads. In the example below, try-with-resources is used, 
  
 // which automatically calls close(). 
  
 try 
  
 ( 
 SessionsClient 
  
 sessionsClient 
  
 = 
  
 SessionsClient 
 . 
 create 
 ( 
 sessionsSettings 
 )) 
  
 { 
  
 // Set the session name using the projectID (my-project-id), locationID (global), agentID 
  
 // (UUID), and sessionId (UUID). 
  
 SessionName 
  
 session 
  
 = 
  
 SessionName 
 . 
 ofProjectLocationAgentSessionName 
 ( 
 projectId 
 , 
  
 locationId 
 , 
  
 agentId 
 , 
  
 sessionId 
 ); 
  
 // TODO : Uncomment if you want to print session path 
  
 // System.out.println("Session Path: " + session.toString()); 
  
 // Detect intents for each text input. 
  
 for 
  
 ( 
 String 
  
 text 
  
 : 
  
 texts 
 ) 
  
 { 
  
 // Set the text (hello) for the query. 
  
 TextInput 
 . 
 Builder 
  
 textInput 
  
 = 
  
 TextInput 
 . 
 newBuilder 
 (). 
 setText 
 ( 
 text 
 ); 
  
 // Build the query with the TextInput and language code (en-US). 
  
 QueryInput 
  
 queryInput 
  
 = 
  
 QueryInput 
 . 
 newBuilder 
 (). 
 setText 
 ( 
 textInput 
 ). 
 setLanguageCode 
 ( 
 languageCode 
 ). 
 build 
 (); 
  
 // Build the DetectIntentRequest with the SessionName and QueryInput. 
  
 DetectIntentRequest 
  
 request 
  
 = 
  
 DetectIntentRequest 
 . 
 newBuilder 
 () 
  
 . 
 setSession 
 ( 
 session 
 . 
 toString 
 ()) 
  
 . 
 setQueryInput 
 ( 
 queryInput 
 ) 
  
 . 
 build 
 (); 
  
 // Performs the detect intent request. 
  
 DetectIntentResponse 
  
 response 
  
 = 
  
 sessionsClient 
 . 
 detectIntent 
 ( 
 request 
 ); 
  
 // Display the query result. 
  
 QueryResult 
  
 queryResult 
  
 = 
  
 response 
 . 
 getQueryResult 
 (); 
  
 // TODO : Uncomment if you want to print queryResult 
  
 // System.out.println("===================="); 
  
 // System.out.format("Query Text: '%s'\n", queryResult.getText()); 
  
 // System.out.format( 
  
 //     "Detected Intent: %s (confidence: %f)\n", 
  
 //     queryResult.getIntent().getDisplayName(), 
  
 //         queryResult.getIntentDetectionConfidence()); 
  
 queryResults 
 . 
 put 
 ( 
 text 
 , 
  
 queryResult 
 ); 
  
 } 
  
 } 
  
 return 
  
 queryResults 
 ; 
  
 } 
 }

    Node.js

    To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

      /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // const projectId = 'my-project'; 
 // const location = 'global'; 
 // const agentId = 'my-agent'; 
 // const query = 'Hello'; 
 // const languageCode = 'en' 
 // Imports the Google Cloud Some API library 
 const 
  
 { 
 SessionsClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/dialogflow-cx 
' 
 ); 
 /** 
 * Example for regional endpoint: 
 *   const location = 'us-central1' 
 *   const client = new SessionsClient({apiEndpoint: 'us-central1-dialogflow.googleapis.com'}) 
 */ 
 const 
  
 client 
  
 = 
  
 new 
  
  SessionsClient 
 
 (); 
 async 
  
 function 
  
 detectIntentText 
 () 
  
 { 
  
 const 
  
 sessionId 
  
 = 
  
 Math 
 . 
 random 
 (). 
 toString 
 ( 
 36 
 ). 
 substring 
 ( 
 7 
 ); 
  
 const 
  
 sessionPath 
  
 = 
  
 client 
 . 
 projectLocationAgentSessionPath 
 ( 
  
 projectId 
 , 
  
 location 
 , 
  
 agentId 
 , 
  
 sessionId 
  
 ); 
  
 const 
  
 request 
  
 = 
  
 { 
  
 session 
 : 
  
 sessionPath 
 , 
  
 queryInput 
 : 
  
 { 
  
 text 
 : 
  
 { 
  
 text 
 : 
  
 query 
 , 
  
 }, 
  
 languageCode 
 , 
  
 }, 
  
 }; 
  
 const 
  
 [ 
 response 
 ] 
  
 = 
  
 await 
  
 client 
 . 
 detectIntent 
 ( 
 request 
 ); 
  
 for 
  
 ( 
 const 
  
 message 
  
 of 
  
 response 
 . 
 queryResult 
 . 
 responseMessages 
 ) 
  
 { 
  
 if 
  
 ( 
 message 
 . 
 text 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
 `Agent Response: 
 ${ 
 message 
 . 
 text 
 . 
 text 
 } 
 ` 
 ); 
  
 } 
  
 } 
  
 if 
  
 ( 
 response 
 . 
 queryResult 
 . 
 match 
 . 
 intent 
 ) 
  
 { 
  
 console 
 . 
 log 
 ( 
  
 `Matched Intent: 
 ${ 
 response 
 . 
 queryResult 
 . 
 match 
 . 
 intent 
 . 
 displayName 
 } 
 ` 
  
 ); 
  
 } 
  
 console 
 . 
 log 
 ( 
  
 `Current Page: 
 ${ 
 response 
 . 
 queryResult 
 . 
 currentPage 
 . 
 displayName 
 } 
 ` 
  
 ); 
 } 
 detectIntentText 
 ();

    Python

    To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

      def 
  
 run_sample 
 (): 
 # TODO(developer): Replace these values when running the function 
 project_id 
 = 
 "YOUR-PROJECT-ID" 
 # For more information about regionalization see https://cloud.google.com/dialogflow/cx/docs/how/region 
 location_id 
 = 
 "YOUR-LOCATION-ID" 
 # For more info on agents see https://cloud.google.com/dialogflow/cx/docs/concept/agent 
 agent_id 
 = 
 "YOUR-AGENT-ID" 
 agent 
 = 
 f 
 "projects/ 
 { 
 project_id 
 } 
 /locations/ 
 { 
 location_id 
 } 
 /agents/ 
 { 
 agent_id 
 } 
 " 
 # For more information on sessions see https://cloud.google.com/dialogflow/cx/docs/concept/session 
 session_id 
 = 
 uuid 
 . 
 uuid4 
 () 
 texts 
 = 
 [ 
 "Hello" 
 ] 
 # For more supported languages see https://cloud.google.com/dialogflow/es/docs/reference/language 
 language_code 
 = 
 "en-us" 
 detect_intent_texts 
 ( 
 agent 
 , 
 session_id 
 , 
 texts 
 , 
 language_code 
 ) 
 def 
  
 detect_intent_texts 
 ( 
 agent 
 , 
 session_id 
 , 
 texts 
 , 
 language_code 
 ): 
  
 """Returns the result of detect intent with texts as inputs. 
 Using the same `session_id` between requests allows continuation 
 of the conversation.""" 
 session_path 
 = 
 f 
 " 
 { 
 agent 
 } 
 /sessions/ 
 { 
 session_id 
 } 
 " 
 print 
 ( 
 f 
 "Session path: 
 { 
 session_path 
 } 
 \n 
 " 
 ) 
 client_options 
 = 
 None 
 agent_components 
 = 
 AgentsClient 
 . 
 parse_agent_path 
 ( 
 agent 
 ) 
 location_id 
 = 
 agent_components 
 [ 
 "location" 
 ] 
 if 
 location_id 
 != 
 "global" 
 : 
 api_endpoint 
 = 
 f 
 " 
 { 
 location_id 
 } 
 -dialogflow.googleapis.com:443" 
 print 
 ( 
 f 
 "API Endpoint: 
 { 
 api_endpoint 
 } 
 \n 
 " 
 ) 
 client_options 
 = 
 { 
 "api_endpoint" 
 : 
 api_endpoint 
 } 
 session_client 
 = 
 SessionsClient 
 ( 
 client_options 
 = 
 client_options 
 ) 
 for 
 text 
 in 
 texts 
 : 
 text_input 
 = 
 session 
 . 
 TextInput 
 ( 
 text 
 = 
 text 
 ) 
 query_input 
 = 
 session 
 . 
 QueryInput 
 ( 
 text 
 = 
 text_input 
 , 
 language_code 
 = 
 language_code 
 ) 
 request 
 = 
 session 
 . 
 DetectIntentRequest 
 ( 
 session 
 = 
 session_path 
 , 
 query_input 
 = 
 query_input 
 ) 
 response 
 = 
 session_client 
 . 
 detect_intent 
 ( 
 request 
 = 
 request 
 ) 
 print 
 ( 
 "=" 
 * 
 20 
 ) 
 print 
 ( 
 f 
 "Query text: 
 { 
 response 
 . 
 query_result 
 . 
 text 
 } 
 " 
 ) 
 response_messages 
 = 
 [ 
 " " 
 . 
 join 
 ( 
 msg 
 . 
 text 
 . 
 text 
 ) 
 for 
 msg 
 in 
 response 
 . 
 query_result 
 . 
 response_messages 
 ] 
 print 
 ( 
 f 
 "Response text: 
 { 
 ' ' 
 . 
 join 
 ( 
 response_messages 
 ) 
 } 
 \n 
 " 
 )

    Productionization

    Before running your agent in production, be sure to implement the productionization best practices .

    Previous
    Interactions with an integration
    Next
    Important terms
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: