Google Chat

Google Chat calls @housecall at an HTTPS endpoint, so it needs a public URL. We recommend a cloudflared tunnel, or running the container on a hosted platform such as Google Cloud Run, which gives it a public HTTPS URL. Teams and Google Chat use the same port.

cloudflared tunnel --url http://localhost:3978

1. Create a service account

1. In Google Cloud, pick or create a project and enable the Google Chat API.
2. Create a service account and download a JSON key.
3. Put the key JSON in a secrets/ folder in your project. It is gitignored.
4. In deploy/docker-compose.yml, uncomment the ../secrets:/app/secrets:ro line.
5. Set the path in .env:

GOOGLE_SERVICE_ACCOUNT_FILE=secrets/<file>.json

The same service account reads Google Drive if you use it.

2. Configure the Chat app

In the Google Chat API’s Configuration page:

1. Set the app name and description. For the avatar URL, use https://chat.ithousecall.app/icon.png.
2. Turn on interactive features and Join spaces and group conversations.
3. Under Connection settings, choose HTTP endpoint URL and enter your public URL plus /googlechat. Set Authentication audience to Project Number. @housecall rejects the HTTP endpoint URL audience, because any Chat app could be pointed at your URL with it.
4. Under Visibility, choose who in your domain can find the app.

3. Enable it

Set endpoint_url to the URL from step 2 and project_number to the Google Cloud project’s number, from the project’s dashboard. Both are required. @housecall serves the path of endpoint_url and accepts only requests signed for that project.

chat:
  googlechat:
    enabled: true
    endpoint_url: https://random-words.trycloudflare.com/googlechat
    project_number: "123456789012"
http: { port: 3978 }

If your Chat app is built as a Google Workspace add-on, @housecall accepts it only from the project’s own add-on service agent, service-<project_number>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com.

docker compose -f deploy/docker-compose.yml up -d --build

How it behaves

• Message the app directly, or add it to a space and mention it.
• In spaces it replies in the thread. In a DM it replies directly, and the whole DM is one conversation.
• When mentioned, it reads earlier messages in the thread. This needs the chat.app.messages.readonly scope, which a Workspace admin must grant. Without it, @housecall skips the history.
• Images uploaded to a message are downloaded with the app’s chat.bot scope, which needs no extra grant. With the history scope, it also reads the images the person who mentioned it posted in the thread since its last reply. Google Drive files attached to a message are named to the model but not read.
• Approvals show as a card with Approve and Deny. A decided card changes to show the outcome. If someone else clicks, @housecall replies that only the requester can decide.