Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roark.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Google CES integration connects a Google Customer Engagement Suite app to Roark for chat simulations. Roark sends each persona turn to the CES runSession endpoint and records the agent’s reply as part of the chat transcript. Authentication uses Workload Identity Federation (WIF) — Roark exchanges its AWS identity for a short-lived Google access token at simulation time. No long-lived service account keys are ever stored on Roark’s side.
Google CES is a chat-only integration in Roark. It does not support voice simulations or importing live calls. To test voice agents, use one of our voice platform integrations.

​
Prerequisites

Before connecting, you’ll need:
  • A Google Cloud project with a published Customer Engagement Suite app
  • Permissions in that project to:
    • Create a Workload Identity Pool and AWS provider
    • Create or reuse a service account with access to your CES app, and allow that pool to impersonate it
  • The CES app coordinates: Location, App ID, Version ID, Deployment ID

​
Setting Up Workload Identity Federation

Roark runs in AWS. To call Google APIs without a static key, you grant Roark’s AWS execution role permission to impersonate a Google service account through a Workload Identity Pool.
1

Create a Workload Identity Pool

In your GCP project, follow Configure Workload Identity Federation with AWS to create a pool and an AWS provider that trusts Roark’s AWS account.Contact Roark support to confirm the AWS account ID and role ARN you should authorize.
2

Create or reuse a service account

Create a Google service account that has permission to call runSession on your CES app (typically the Dialogflow API Client role, or a custom role with dialogflow.sessions.run).
3

Grant impersonation

Bind the roles/iam.workloadIdentityUser role on the service account to the principal representing Roark in your Workload Identity Pool.
4

Download the WIF credential JSON

From the pool’s provider, download the credential configuration. It’s a JSON document with type: "external_account". You’ll paste this whole document into Roark.
The credential JSON looks roughly like this: 
{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/<num>/locations/global/workloadIdentityPools/<pool>/providers/<provider>",
  "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<sa>@<project>.iam.gserviceaccount.com:generateAccessToken",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "environment_id": "aws1",
    "region_url": "...",
    "url": "...",
    "regional_cred_verification_url": "..."
  }
}

​
Creating the Integration in Roark

1

Open the integration form

Navigate to Settings → Integrations, click Add Integration, and select Google CES.
2

Fill in the configuration

FieldDescription
Integration NameFriendly name for this integration
WIF Config JSONThe full external-account credential JSON from your Workload Identity Pool. Stored encrypted at rest.
CES LocationGCP region for your CES app (e.g. us, global)
CES App IDUUID of the CES app, from the CES console
CES Version IDUUID of the app version to run
CES Deployment IDUUID of the deployment to target
3

Save

On save, Roark validates the WIF document’s shape, stores it encrypted, and auto-provisions:
  • One Roark agent named after the integration
  • One GOOGLE_CES chat endpoint linked to the integration
The endpoint is immediately usable in run plans.

​
How Authentication Works at Runtime

When a chat simulation runs against a Google CES endpoint, Roark mints a fresh access token for the request rather than storing one:
  1. Roark signs an AWS STS GetCallerIdentity request using its execution role.
  2. The signed request is exchanged at Google STS (token_url) for a federated token.
  3. The federated token is used at service_account_impersonation_url to impersonate your configured service account, returning an OAuth access token scoped to https://www.googleapis.com/auth/cloud-platform.
  4. Roark sends Authorization: Bearer <token> on each call to …/sessions/{sessionId}:runSession.
Tokens are short-lived (≈1 hour) and live only in memory for the duration of the simulation.

​
How Conversations Are Driven

Each simulation generates a unique session ID per run. For every persona turn, Roark POSTs to: 
POST https://<location>-ces.googleapis.com/v1beta/projects/<project>/locations/<location>/apps/<appId>/sessions/<sessionId>:runSession
with a body referencing your app_version and deployment plus the user input text. The agent’s reply is read from outputs[0].text and added to the chat transcript. CES creates the session on the first call with a new session ID and resumes it on subsequent calls with the same ID, so no separate bootstrap call is needed.

​
What’s Not Supported

  • Voice simulations — Google CES integrations are chat-only.
  • Live monitoring / call import — Roark does not pull historical or live conversations from CES. Use chat simulations to evaluate the agent.

​
Next Steps

Run Chat Simulations

Test your CES app with persona-driven chats

Build Scenarios

Define the conversations to test

Metric Policies

Automate evaluation on every chat

Integration Overview

Explore other integrations