Dialogflow CX

Connect the Google Cloud project that holds your Dialogflow CX agents, then test and edit them in Bluejay.

Connect

One credential on the Google Agents tab covers every Dialogflow CX and CES agent in the project.

Save a Google credential

In Bluejay, open Settings → Integrations and choose the Google Agents tab. Use keyless access unless you only want a quick trial. No key exists, so no key can leak. If you save more than one credential, Bluejay uses the access token first, then keyless, then the key.

Keyless
Access token
Service account key

Run the script in Keyless setup and paste the four values it prints.

Paste the output of gcloud auth print-access-token. The token stops working after about one hour, so paste a new one when it does.

Sync the agents

Click Sync Agents from Google. Bluejay creates one agent for each Dialogflow CX agent and each CES deployment. Sync again after you add agents in Google.

To connect one agent by hand instead, give it the Dialogflow CX connection type and set Dialogflow CX Agent Path to projects/<project>/locations/<location>/agents/<agentId>.

Add an agent the sync misses

An access token that can open an agent but not list its location leaves that agent out of the sync. Open Can’t find an agent? Add it by Dialogflow CX agent ID and enter any of these, separated by commas:

The agent ID, a UUID such as 6a1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d.
The resource path, projects/<project>/locations/<location>/agents/<agentId>.
The agent’s Dialogflow CX console URL.

You can add only agents in the project of your saved credential. If Bluejay cannot find or read an agent there, the sync results list it as failed.

Permissions

The keyless setup script grants the read and run roles. To push, version, or promote from Bluejay, also grant the write permissions.

Use	Permissions	Predefined roles
Sync and read	`get` and `list` on `dialogflow` agents, flows, pages, intents, transitionRouteGroups, playbooks, tools, and generators, such as
Run simulations	, ,	,
Push, version, promote	Create, update, and delete flows, playbooks, pages, intents, route groups, and tools. Create flow and playbook versions. Deploy flows to an environment.

Keyless setup

The script creates a service account with no keys in your project, and only your Bluejay tenant can use it. To run it, you need the Owner role on the project, or Workload Identity Pool Admin, Service Account Admin, and Project IAM Admin.

Write the script in Cloud Shell

In Cloud Shell, paste this block. It only writes bluejay-wif.sh, so you can read the file before you run it.

bluejay-wif.sh

cat > bluejay-wif.sh <<'BLUEJAY'
#!/bin/bash
# Bluejay keyless access (Workload Identity Federation) for your Google Cloud project.
#
#   bash bluejay-wif.sh <BLUEJAY_TENANT_ID> <GCP_PROJECT_ID> [--ces]
#
# Creates, in YOUR project: a workload identity pool + OIDC provider that trust
# Bluejay's token issuer and are pinned to YOUR Bluejay tenant id, a dedicated
# service account with no keys, permission for that one tenant to impersonate it,
# and read + run roles for Dialogflow CX (add --ces to also cover CES agents).
# Safe to re-run. Nothing secret is created or printed.
set -euo pipefail

run() { local out; if ! out=$("$@" 2>&1); then echo "$out" >&2; return 1; fi; }

TENANT_ID="${1:?usage: bash bluejay-wif.sh <BLUEJAY_TENANT_ID> <GCP_PROJECT_ID> [--ces]}"
PROJECT_ID="${2:?usage: bash bluejay-wif.sh <BLUEJAY_TENANT_ID> <GCP_PROJECT_ID> [--ces]}"
WITH_CES=0; [[ "${3:-}" == "--ces" ]] && WITH_CES=1

# The tenant id is pasted by hand and ends up inside the provider's CEL
# condition, so a stray space or quote would produce a provider that rejects
# every exchange. Fail here instead, with the value in front of you.
[[ $TENANT_ID =~ ^[A-Za-z0-9_-]+$ ]] || {
  echo "tenant id looks wrong: '$TENANT_ID'. Copy it from the Google Agents tab in Bluejay." >&2; exit 1; }

POOL=bluejay
PROVIDER=bluejay
SA_ID=bluejay-integration
ISSUER="https://api.getbluejay.ai"

PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')
SA="${SA_ID}@${PROJECT_ID}.iam.gserviceaccount.com"
PROVIDER_PATH="projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL}/providers/${PROVIDER}"
AUDIENCE="//iam.googleapis.com/${PROVIDER_PATH}"
# The security boundary. Google checks this before issuing any credential: only
# Bluejay tokens that carry YOUR tenant id (and come from production) are accepted.
CONDITION="assertion.tenant_id == '${TENANT_ID}' && assertion.environment == 'production'"
MAPPING="google.subject=assertion.sub,attribute.tenant_id=assertion.tenant_id,attribute.integration_id=assertion.integration_id,attribute.environment=assertion.environment"
MEMBER="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL}/attribute.tenant_id/${TENANT_ID}"

echo "==> Enabling APIs"
APIS="iamcredentials.googleapis.com sts.googleapis.com dialogflow.googleapis.com"
[[ $WITH_CES == 1 ]] && APIS="$APIS ces.googleapis.com"
gcloud services enable $APIS --project="$PROJECT_ID"

echo "==> Workload identity pool: $POOL"
STATE=$(gcloud iam workload-identity-pools describe "$POOL" --location=global --project="$PROJECT_ID" --format='value(state)' 2>/dev/null || true)
case "$STATE" in
  ACTIVE)  ;;
  DELETED) run gcloud iam workload-identity-pools undelete "$POOL" --location=global --project="$PROJECT_ID" ;;
  *)       run gcloud iam workload-identity-pools create "$POOL" --location=global --project="$PROJECT_ID" --display-name="Bluejay" ;;
esac

echo "==> OIDC provider: $PROVIDER (trusts $ISSUER, pinned to tenant $TENANT_ID)"
STATE=$(gcloud iam workload-identity-pools providers describe "$PROVIDER" --workload-identity-pool="$POOL" --location=global --project="$PROJECT_ID" --format='value(state)' 2>/dev/null || true)
if [[ "$STATE" == "DELETED" ]]; then
  run gcloud iam workload-identity-pools providers undelete "$PROVIDER" --workload-identity-pool="$POOL" --location=global --project="$PROJECT_ID"
  STATE=ACTIVE
fi
if [[ "$STATE" == "ACTIVE" ]]; then
  run gcloud iam workload-identity-pools providers update-oidc "$PROVIDER" --workload-identity-pool="$POOL" --location=global --project="$PROJECT_ID" \
    --issuer-uri="$ISSUER" --allowed-audiences="$AUDIENCE" --attribute-mapping="$MAPPING" --attribute-condition="$CONDITION"
else
  run gcloud iam workload-identity-pools providers create-oidc "$PROVIDER" --workload-identity-pool="$POOL" --location=global --project="$PROJECT_ID" \
    --display-name="Bluejay OIDC" \
    --issuer-uri="$ISSUER" --allowed-audiences="$AUDIENCE" --attribute-mapping="$MAPPING" --attribute-condition="$CONDITION"
fi

echo "==> Service account: $SA (no keys)"
gcloud iam service-accounts describe "$SA" --project="$PROJECT_ID" >/dev/null 2>&1 \
  || run gcloud iam service-accounts create "$SA_ID" --project="$PROJECT_ID" --display-name="Bluejay Integration" \
       --description="Impersonated by Bluejay via Workload Identity Federation. No keys are issued for this account."

echo "==> Allowing your Bluejay tenant (and only it) to impersonate the service account"
for i in 1 2 3 4 5 6; do   # a brand-new service account takes a few seconds to become bindable
  ADD_ERR=$(gcloud iam service-accounts add-iam-policy-binding "$SA" --project="$PROJECT_ID" \
    --role=roles/iam.workloadIdentityUser --member="$MEMBER" --condition=None --quiet 2>&1) && break
  [[ $i == 6 ]] && { echo "$ADD_ERR" >&2; echo "could not add the impersonation binding, re-run this script" >&2; exit 1; }
  sleep 10
done

echo "==> Roles (read + run only, never admin)"
ROLES="roles/dialogflow.reader roles/dialogflow.client roles/serviceusage.serviceUsageConsumer"
[[ $WITH_CES == 1 ]] && ROLES="$ROLES roles/ces.viewer roles/ces.client"
for ROLE in $ROLES; do
  run gcloud projects add-iam-policy-binding "$PROJECT_ID" --member="serviceAccount:${SA}" --role="$ROLE" --condition=None --quiet
  echo "    $ROLE"
done

echo "==> Verifying, as the service account, that Google is enforcing the new roles (usually 1 to 3 minutes)"
# Google applies IAM changes over a few minutes. Rather than leave you to find out
# in Bluejay, this waits until the service account can really list your agents.
# To test as the service account, your own account is temporarily allowed to
# impersonate it; that grant is removed again below.
# Scope: this checks the roles only. It calls Google directly with your own
# credentials, so it says nothing about the token exchange (issuer, audience,
# tenant pin). Test connection in Bluejay is what exercises that path.
ME=$(gcloud config get-value account 2>/dev/null)
case "$ME" in *.gserviceaccount.com) ME_MEMBER="serviceAccount:${ME}" ;; *) ME_MEMBER="user:${ME}" ;; esac
if run gcloud iam service-accounts add-iam-policy-binding "$SA" --project="$PROJECT_ID" \
     --role=roles/iam.serviceAccountTokenCreator --member="$ME_MEMBER" --condition=None --quiet; then
  # Hand the grant back even if you Ctrl-C during the wait below.
  DROPPED=0
  drop_grant() {
    if [[ $DROPPED == 0 ]]; then
      DROPPED=1
      run gcloud iam service-accounts remove-iam-policy-binding "$SA" --project="$PROJECT_ID" \
        --role=roles/iam.serviceAccountTokenCreator --member="$ME_MEMBER" --condition=None --quiet || true
    fi
  }
  trap drop_grant EXIT
  trap 'drop_grant; exit 130' INT TERM
  CHECK_URLS="https://dialogflow.googleapis.com/v3/projects/${PROJECT_ID}/locations/global/agents"
  [[ $WITH_CES == 1 ]] && CHECK_URLS="$CHECK_URLS https://ces.googleapis.com/v1/projects/${PROJECT_ID}/locations/us/apps https://ces.googleapis.com/v1/projects/${PROJECT_ID}/locations/eu/apps"
  VERIFIED=0
  for attempt in $(seq 1 30); do   # up to ~5 minutes
    TOKEN=$(gcloud auth print-access-token --impersonate-service-account="$SA" 2>/dev/null || true)
    if [[ -n "$TOKEN" ]]; then
      ALL_OK=1
      for URL in $CHECK_URLS; do
        CODE=$(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer ${TOKEN}" "$URL")
        [[ "$CODE" == 200 ]] || ALL_OK=0
      done
      [[ $ALL_OK == 1 ]] && { VERIFIED=1; break; }
    fi
    printf '.'; sleep 10
  done
  echo
  drop_grant
  trap - EXIT INT TERM
  if [[ $VERIFIED == 1 ]]; then
    echo "    roles are live: the service account can list your agents"
  else
    echo "    roles still not enforced after 5 minutes. Paste the values anyway; if Test connection or Sync complains, wait a minute and try again."
  fi
else
  echo "    (your account cannot impersonate the service account here, skipping the role check; give Google a minute or two before Test connection)"
fi

cat <<EOF

Done. Paste these into Bluejay (Settings > Integrations > Google Agents), click Save, then Test connection:

  Service account email      : $SA
  Workload identity provider : $PROVIDER_PATH
  Project ID                 : $PROJECT_ID
  Project number             : $PROJECT_NUMBER
EOF
BLUEJAY

Run the script

Copy Your Bluejay tenant id from the Keyless tab, and run the script with it and your project ID. Add --ces if you also use CES agents.

bash bluejay-wif.sh PASTE_YOUR_BLUEJAY_TENANT_ID your-project-id

The script waits until Google applies the roles, usually 1 to 3 minutes, then prints four values. If the tenant ID has a typo, every token exchange fails with Could not obtain a federated token.

Paste the values

Paste the four values into the Keyless fields and click Save & test connection. None of them is secret. The test checks the token exchange, the impersonation, and the Dialogflow CX read roles, but not CES.

To push, version, or promote from Bluejay, also grant the write permissions. To revoke Bluejay’s access, remove the impersonation binding. Tokens that Bluejay already has expire within one hour.

gcloud iam service-accounts remove-iam-policy-binding \
  bluejay-integration@PROJECT_ID.iam.gserviceaccount.com --project=PROJECT_ID \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bluejay/attribute.tenant_id/BLUEJAY_TENANT_ID"

To delete all of it, delete the service account and the pool with gcloud iam workload-identity-pools delete bluejay --location=global.

Terraform

To manage keyless access in Terraform, apply these files in your own repository. They create the same resources as the script.

terraform {
  required_version = ">= 1.5"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 5.0"
    }
  }
}

provider "google" {
  project = var.project_id
}

locals {
  pool_id     = "bluejay"
  provider_id = "bluejay"

  # Paste this path into Bluejay as the workload identity provider.
  provider_path          = "projects/${var.project_number}/locations/global/workloadIdentityPools/${local.pool_id}/providers/${local.provider_id}"
  provider_resource_name = "//iam.googleapis.com/${local.provider_path}"

  service_roles = {
    dialogflow = ["roles/dialogflow.reader", "roles/dialogflow.client"]
    ces        = ["roles/ces.viewer", "roles/ces.client"]
    logging    = ["roles/logging.viewer"]
    storage    = ["roles/storage.objectViewer"]
    bigquery   = ["roles/bigquery.jobUser", "roles/bigquery.dataViewer"]
    vertex     = ["roles/aiplatform.user"]
  }

  role_grants = flatten([
    for svc in var.enabled_services : [
      for role in lookup(local.service_roles, svc, []) : {
        key  = "${svc}:${role}"
        role = role
      }
    ]
  ])
}

resource "google_iam_workload_identity_pool" "bluejay" {
  project                   = var.project_id
  workload_identity_pool_id = local.pool_id
  display_name              = "Bluejay"
}

resource "google_iam_workload_identity_pool_provider" "bluejay" {
  project                            = var.project_id
  workload_identity_pool_id          = google_iam_workload_identity_pool.bluejay.workload_identity_pool_id
  workload_identity_pool_provider_id = local.provider_id
  display_name                       = "Bluejay OIDC"

  attribute_mapping = {
    "google.subject"           = "assertion.sub"
    "attribute.tenant_id"      = "assertion.tenant_id"
    "attribute.integration_id" = "assertion.integration_id"
    "attribute.environment"    = "assertion.environment"
  }

  # The security boundary: only tokens for your tenant id are accepted.
  attribute_condition = "assertion.tenant_id == \"${var.bluejay_tenant_id}\" && assertion.environment == \"production\""

  oidc {
    issuer_uri        = "https://api.getbluejay.ai"
    allowed_audiences = [local.provider_resource_name]
  }
}

resource "google_service_account" "bluejay_integration" {
  project      = var.project_id
  account_id   = "bluejay-integration"
  display_name = "Bluejay Integration"
}

resource "google_service_account_iam_member" "workload_identity_user" {
  service_account_id = google_service_account.bluejay_integration.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.bluejay.name}/attribute.tenant_id/${var.bluejay_tenant_id}"
}

resource "google_project_iam_member" "service_roles" {
  for_each = { for g in local.role_grants : g.key => g }
  project  = var.project_id
  role     = each.value.role
  member   = "serviceAccount:${google_service_account.bluejay_integration.email}"
}

# Without this role, every voice simulation fails with USER_PROJECT_DENIED.
resource "google_project_iam_member" "service_usage_consumer" {
  project = var.project_id
  role    = "roles/serviceusage.serviceUsageConsumer"
  member  = "serviceAccount:${google_service_account.bluejay_integration.email}"
}

variable "bluejay_tenant_id" {
  type        = string
  description = "Your Bluejay tenant id from Settings > Integrations > Google Agents."
  validation {
    condition     = length(var.bluejay_tenant_id) > 0
    error_message = "bluejay_tenant_id must be the non empty value shown in Bluejay."
  }
}

variable "project_id" {
  type = string
}

variable "project_number" {
  type        = string
  description = "gcloud projects describe <project_id> --format='value(projectNumber)'"
}

variable "enabled_services" {
  type        = set(string)
  description = "Any of: dialogflow, ces, logging, storage, bigquery, vertex."
  default     = ["dialogflow"]
  validation {
    condition = alltrue([
      for s in var.enabled_services :
      contains(["dialogflow", "ces", "logging", "storage", "bigquery", "vertex"], s)
    ])
    error_message = "enabled_services entries must be one of: dialogflow, ces, logging, storage, bigquery, vertex."
  }
}

output "workload_identity_provider" {
  value = local.provider_path
}

output "service_account_email" {
  value = google_service_account.bluejay_integration.email
}

output "project_number" {
  value = var.project_number
}

cat > terraform.tfvars <<'EOF'
bluejay_tenant_id = "PASTE_YOUR_BLUEJAY_TENANT_ID"
project_id        = "acme-voice-prod"
project_number    = "123456789012"
enabled_services  = ["dialogflow"]        # add "ces" for CES agents
EOF

terraform init && terraform apply

Paste the three outputs and your project ID into Bluejay. Terraform does not wait for Google to apply the roles, so Test connection can fail for a few minutes. The storage and bigquery options grant read access to the whole project.

Test

The connection type on the agent decides whether you test by voice or by chat. In both, Bluejay replies {"status": "ok"} to each client-side tool call.

Voice
Chat

Choose the Dialogflow CX voice tile. Voice tests need no phone number and work for inbound agents only.Use Generate From Workflow so that each path in the agent gets a test, not only the main path. It makes Digital Humans from the flows, event handlers, and playbooks, including paths across handoffs.

Generate From Workflow listing each path through the agent with a Digital Human count

Edit, version, and promote

Versions and deployments that you make in Bluejay are real Dialogflow CX versions and deployments.

Pull the live agent

On the agent’s Workflow tab, click Pull to replace the local copy with the live agent.

Edit and push

Edit flows, pages, routes, event handlers, and playbooks, then click Push to DFCX. The push writes your edits to the agent draft. If the agent changed in Google after your last sync, Bluejay shows the conflicts first.Turn on Version on push to save a new Dialogflow CX version of each flow and playbook that the push changed. Dialogflow CX limits the number of versions for each flow.

Promote

Promote deploys the flow versions you select to an environment. Only admins can promote.

Troubleshooting

Symptom	Fix
Test connection shows `Could not obtain a federated token`	Google rejected the token exchange. Check the tenant ID, the provider path, and the project number. Make sure the `iamcredentials` and `sts` APIs are on. After a manual or Terraform setup, wait a few minutes.
Test connection shows `credential rejected`	The credential expired or is not valid. For an access token, paste a new one.
Test connection shows `no permission`	The credential works, but a role or an API is missing. Run the setup script again.
Test connection shows `unreachable`	Google returned another error, or the request did not reach Google.
Voice fails with	Grant the service account . Chat can still work without it, so a green Test connection does not prove voice works.

Get Started

Test

Monitor

Improve

Cookbook

Integrations

Administration

Connect

Add an agent the sync misses

Permissions

Keyless setup

Test

Edit, version, and promote

Troubleshooting

​Connect

​Add an agent the sync misses

​Permissions

​Keyless setup

​Test

​Edit, version, and promote

​Troubleshooting

​Related

Connect

Add an agent the sync misses

Permissions

Keyless setup

Test

Edit, version, and promote

Troubleshooting

Related