Google Chat Showcase Bot for Cognigy Payloads

A demonstration Chat App that translates JSON payloads from the Cognigy platform into interactive Google Chat Card V2 messages. This project serves as a reference for integrating a conversational AI backend with a Google Chat frontend using a serverless GCP architecture.

Overview

This repository contains the source code and deployment instructions for a Google Chat application designed to act as a middleware and translator. The application receives proprietary JSON formats from a backend like Cognigy and transforms them into rich, interactive UI cards for display within Google Chat.

This showcase bot is pre-configured with five common Cognigy output formats (Gallery, Quick Replies, Buttons, List, and Image) and demonstrates their visual representation in Google Chat.

Architecture

The solution uses a secure, scalable, and fully serverless architecture on Google Cloud Platform.

• Google Chat: The user interface where users interact with the application.
• API Gateway: Provides a secure, public-facing HTTPS endpoint to receive webhook events from Google Chat. It handles authentication and forwards requests to the backend service.
• Cloud Run: A serverless container platform that hosts the core application logic written in Python (Flask). It receives requests, performs the JSON translation, and returns the formatted card message.

Features

• Modular Code Structure: The Python code is organized into separate files for routing (main.py), payload storage (payloads.py), and card creation logic (cards.py) for improved readability and maintenance.
• Interactive Showcase: The bot presents a welcome card with buttons, allowing users to easily trigger and view each of the five translated card types.
• Secure by Default: The Cloud Run service is deployed to require authentication, and API Gateway is configured to use a dedicated Service Account with the Cloud Run Invoker role to securely communicate with the backend.

Deployment Steps (UI Guide)

This guide outlines the process for deploying the Showcase Bot using the Google Cloud Console.

Prerequisites

• A Google Cloud Project with billing enabled.
• A Google Workspace account with permissions to configure Google Chat applications.
• The source code for main.py, cards.py, and payloads.py ready to be copied.

Step 1: Enable Required APIs

1. In the Google Cloud Console, navigate to APIs & Services > Library.
2. Search for and enable each of the following APIs one by one:
   • Cloud Run API
   • Cloud Build API
   • API Gateway API
   • Service Management API
   • Service Control API
   • Identity and Access Management (IAM) API

Step 2: Create and Configure the Cloud Run Service

1. Initial Service Creation:
   1. Navigate to Cloud Run in the Google Cloud Console.
   2. Click Create Service.
   3. Select Function: Use an inline editor to create a function. (We will add the code in a later step).
   4. Enter a Service name, for example, chatbot-vcard.
   5. Select a Region.
   6. Under Authentication, select Require authentication.
   7. Under Ingress, select All: Allow direct access from the internet.
   8. Click Create. This will create the service shell.
2. Add Source Code:
   1. On the service details page for your newly created service, click Edit Source or similar.
   2. This will open an inline code editor.
   3. In the editor's file explorer on the left:
      • Click the main.py file and replace all of its content with the code from the repository.
      • Click the requirements.txt file and add a single line: Flask.
      • Click in the + at the top of the directory and select New File. Name it cards.py. Paste the corresponding code from the repository into this file.
      • Create another new file named payloads.py. Paste the corresponding code from the repository into this file.
   4. Click Deploy. Cloud Build will now build and deploy your service with the correct code.
   5. Once deployed, copy the Service URL from the top of the Cloud Run service page.

Step 3: Configure API Gateway for Secure Invocation

1. Create a Service Account:
   1. Navigate to IAM & Admin > Service Accounts.
   2. Click Create Service Account.
   3. Enter a name (e.g., api-gateway-invoker) and click Create and Continue, then Done.
   4. Copy the email address of the new service account.
2. Grant Invoker Permissions:
   1. Navigate back to your Cloud Run service page.
   2. In "Services" check the box of the Cloud Run Function and click on "Permissions"
   3. Click Add Principal.
   4. In the New principals field, paste the service account's email.
   5. In the Assign roles dropdown, select the role Cloud Run Invoker.
   6. Click Save.
3. Create the API Gateway Specification:
   1. Create a file on your local machine named openapi.yaml.
   2. Add the repository yaml content, replacing [YOUR_CLOUDRUN_SERVICE_URL] in both places with your actual service URL from Step 2.
4. Create and Deploy the Gateway:
   1. Navigate to API Gateway in the Cloud Console.
   2. Click Create Gateway.
   3. In the "API" section, select Create a new API and give it a name (e.g., chatbot-api) and a corresponding API ID.
   4. In the "Config" section, select Create new API Config.
   5. Under "API Spec", click Browse and upload the openapi.yaml file you just created.
   6. Give the configuration a name (e.g., chatbot-config-v1).
   7. For the Service account dropdown, select the api-gateway-invoker service account you created.
   8. Enter a Gateway name (e.g., chatbot-gateway) and select your region.
   9. Click Create Gateway.
   10. After deployment is complete, go to the gateway's details page and copy the URL.

Step 4: Configure the Google Chat API

1. Navigate to the "Google Chat API" > "Configuration" page in the Google Cloud Console.
2. Fill out the "Application info" (App name, Avatar URL, Description).
3. Important: Ensure the checkbox for "Build this Chat as a Workspace add-on" is NOT checked.
4. In the "Connection settings" section:
   1. "HTTP endpoint URL": Paste your new API Gateway URL.
   2. "Authentication Audience": Select "HTTP endpoint URL".
5. Set your desired "Visibility" and click "SAVE".