Skip to main content
Version: 2.0

Connect agents to Google Chat

Connect a Vectara agent to Google Chat so messages from a Chat app create or continue agent sessions and the agent replies in the same space or thread.

How Google Chat connectors work​

A Google Chat connector enables bidirectional communication between Vectara agents and Google Chat:

  1. Webhook ingestion: Google Chat sends interaction events to the connector webhook.
  2. Request verification: Vectara verifies the Google-signed bearer token and checks that the token audience matches the connector URL.
  3. Agent execution: The agent processes the message with the current space and thread context.
  4. Response posting: The agent response is sent back to Google Chat.

Each connector gets its own unguessable endpoint. Keep that URL private: Google Chat uses it as the token audience, and Vectara rejects events whose token is addressed to a different connector.

Create a Google Chat connector​

Before you begin​

You need:

  • A Vectara account with agent creation permissions.
  • A Google Cloud project with the Google Chat API enabled.
  • A Google Chat app configured for HTTP endpoint interaction events.
  • A service account key JSON file for the account Vectara uses to call Google Chat APIs.
  • An OAuth consent screen configured for the Google Cloud project.
  • Google Workspace Marketplace OAuth Client enabled on the service account.
  • The App Configuration and Store Listing tabs completed in the Google Workspace Marketplace SDK.

Step 1: Create the connector​

curl -X POST https://api.vectara.io/v2/agents/<agent_key>/connectors \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Google Chat",
    "description": "Receives messages from the support Google Chat app",
    "enabled": true,
    "configuration": {
      "type": "gchat",
      "service_account_key": "{...service account key JSON...}"
    }
  }'

Expected response:

{
  "id": "con_3Kx9QpVn2mZr8YbLc5TdWe",
  "agent_key": "support_agent",
  "name": "Support Google Chat",
  "type": "gchat",
  "status": "active",
  "enabled": true,
  "configuration": {
    "type": "gchat",
    "audience_url": "https://api.vectara.io/v2/agents/support_agent/connectors/con_3Kx9QpVn2mZr8YbLc5TdWe/gchat",
    "client_email": "vectara-chat@example-project.iam.gserviceaccount.com",
    "project_id": "example-project"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

The service account key is encrypted and is not returned in the response. Copy configuration.audience_url; use this value for both the HTTP endpoint URL and the authentication audience in Google Chat.

Step 2: Configure the Google Chat app​

Complete the OAuth consent screen, enable Google Workspace Marketplace OAuth Client on the service account, and complete the App Configuration and Store Listing tabs in the Google Workspace Marketplace SDK. Then, in the Google Cloud Console:

  1. Open Google Chat API for your project.
  2. Open the Chat app configuration.
  3. Set the app's HTTP endpoint URL to the connector's audience_url.
  4. Set the app's Authentication audience to the same audience_url.
  5. Save and publish the app according to your workspace policy.

Google Chat sends each event with a Google-signed bearer token. Vectara verifies the token signature and requires the token audience to equal the connector's audience_url.

Step 3: Test the connector​

  1. Add the Chat app to a test space.
  2. Send a message to the app.
  3. Confirm the agent replies in the same space or thread.
  4. If Google Chat rejects the webhook, list connectors and inspect last_webhook_status.

Google Chat tools and connector credentials​

Attach the gchat_post_message tool when the agent must post proactive notifications, progress updates, or messages to other Google Chat spaces or threads. The tool can use a service account key from an argument override or the credentials from an attached Google Chat connector.

A Google Chat-triggered agent automatically posts its final reply to the triggering space and thread. Do not also call gchat_post_message with that same final reply, or the message is posted twice. Use the tool only for additional messages beyond the connector's automatic final reply.

Manage connectors​

List connectors​

curl https://api.vectara.io/v2/agents/<agent_key>/connectors \
  -H "x-api-key: $VECTARA_API_KEY"

Update connector​

curl -X PATCH https://api.vectara.io/v2/agents/<agent_key>/connectors/<connector_id> \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Google Chat connector"
  }'

When a PATCH request includes a configuration object, that object fully replaces the stored configuration. Because the service account key is never returned in a response, you must resupply service_account_key in every PATCH that sends configuration; otherwise the request fails with 400 because service_account_key is required. Resupply hidden_output_types as well, since any field you omit is dropped.

Delete connector​

curl -X DELETE https://api.vectara.io/v2/agents/<agent_key>/connectors/<connector_id> \
  -H "x-api-key: $VECTARA_API_KEY"

Deleting a connector removes the configuration and stops event processing. Active sessions are not affected.

Troubleshooting​

Webhook requests return 401​

  • Verify the Chat app's HTTP endpoint URL and authentication audience both exactly match the connector's audience_url.
  • Confirm Google Chat is sending an Authorization: Bearer ... header.
  • Check that the connector still exists and has type gchat.

The webhook is rejected​

  • Confirm the service account key is valid and belongs to the expected Google Cloud project.
  • Confirm the Chat app is installed in the space where you are testing.
  • List connectors and inspect last_webhook_status for jwt_verification_failed, audience_mismatch, event_parse_failed, or internal_error.

The webhook succeeds but the agent does not reply​

A last_webhook_status value of success means Vectara accepted the event and launched processing. It does not confirm that the agent run completed or that the reply was posted to Google Chat. Investigate the downstream agent run and response delivery.

Last updated on by Ayesha Saddiqua