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.
- The end-user types or says something, known as end-user input.
- Your user interface or integration system receives the input and forwards it to the Dialogflow API in a detect intent request.
- 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.
- Your webhook service receives the webhook request. Your service takes any actions necessary, like calling external APIs, querying or updating a database, etc.
- Your webhook service builds a response and sends a webhook response back to Conversational Agents (Dialogflow CX).
- 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.
- Your user interface or integration system receives the detect intent response and forwards the text or audio response to the end-user.
- 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:
- Read flow basics.
- Perform setup steps.
- 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
- Open the Dialogflow CX console.
- Select your Google Cloud project to open the agent selector.
- Click the option more_vert menu for an agent in the list.
- Click the copy name filter_none button.
- 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
Agent Builder console
Go to the Agent Builder console:
Your project ID is shown at the top of the console.
The Location column shows region IDs.
Select an app.
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.
Node.js
To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Dialogflow, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Productionization
Before running your agent in production, be sure to implement the productionization best practices.