Deskhand
Docs menu

Google Chat

Google Chat calls Deskhand at an HTTPS endpoint, so it needs a public URL. See Microsoft Teams for a cloudflared example; both 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, avatar, and description.
  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. Deskhand 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. Deskhand 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, Deskhand 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, Deskhand skips the history.
  • Approvals show as a card with Approve and Deny. A decided card changes to show the outcome. If someone else clicks, Deskhand replies that only the requester can decide.