dialogflow-cx-conversations

name	dialogflow-cx-conversations
description	Manage conversations and sessions in Google Dialogflow CX via REST API. Use for testing intents, handling user interactions, and managing conversation state. Supports v3beta1 API.

Permission Setup Review

python scripts/_prepare_workspace.py is an optional setup helper for the Dialogflow CX Conversations skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.

Dialogflow CX Conversations

Manage conversations and sessions in Google Dialogflow CX via REST API for testing and interaction handling.

Prerequisites

• Google Cloud project with Dialogflow CX API enabled
• Service account or OAuth credentials with Dialogflow API access
• gcloud CLI authenticated OR bearer token

Authentication

Option 1: gcloud CLI (recommended)

gcloud auth application-default login
TOKEN=$(gcloud auth print-access-token)

Option 2: Service Account

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
TOKEN=$(gcloud auth application-default print-access-token)

API Base URL

https://dialogflow.googleapis.com/v3beta1

Regional endpoints available:

• https://{region}-dialogflow.googleapis.com (e.g., us-central1, europe-west1)

Common Operations

Detect Intent

curl -X POST \
  "https://dialogflow.googleapis.com/v3beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/${AGENT_ID}/sessions/${SESSION_ID}:detectIntent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "queryInput": {
      "text": {
        "text": "Hello"
      },
      "languageCode": "en"
    }
  }'

Match Intent (no state change)

curl -X POST \
  "https://dialogflow.googleapis.com/v3beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/${AGENT_ID}/sessions/${SESSION_ID}:matchIntent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "queryInput": {
      "text": {
        "text": "Hello"
      },
      "languageCode": "en"
    }
  }'

Create Test Case

curl -X POST \
  "https://dialogflow.googleapis.com/v3beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/${AGENT_ID}/testCases" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Greeting Test",
    "testCaseConversationTurns": [
      {
        "userInput": {
          "input": {
            "text": {
              "text": "Hi"
            }
          }
        },
        "virtualAgentOutput": {
          "textResponses": [
            {
              "text": ["Hello!"]
            }
          ]
        }
      }
    ]
  }'

Key Resources

Resource	Description
Sessions	Conversation instances with state
Detect Intent	Process user input and get responses
Test Cases	Automated conversation testing

Quick Reference

For detailed API reference:

• Conversations & Testing: See references/conversations.md

Scripts

• scripts/conversations.py — CLI wrapper for conversation operations

Usage

python scripts/conversations.py detect-intent --agent AGENT_NAME --text "Hello"
python scripts/conversations.py match-intent --agent AGENT_NAME --text "Hello"

Tips

• Session IDs can be any unique string (e.g., UUID)
• Use detectIntent for full conversation flow, matchIntent for testing without state changes
• Test cases help validate conversation logic before deployment