> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Chat

> Developer notes for the Google Chat upstream connector: Cards v2 over the Chat API, interaction events and dialogs, JWT request verification.

These are developer notes for the Google Chat upstream connector: how Triage's diagnostic runs as a Chat app, rendered with Cards v2 over the Chat API. The page documents the platform surface the Intake Gateway's Google Chat renderer builds on. The gateway itself is described in [Upstream connectors](/connectors/overview).

<Info>
  The Google Chat connector is on the roadmap. The Google Chat renderer ships in the reference implementation; the hosted transport is planned. Method names, scopes and field names on this page are taken from the Chat API v1 discovery document (revision 2026-08-15) and the pages listed under Developer references.
</Info>

## Platform at a glance

<AccordionGroup>
  <Accordion title="App and install" icon="package">
    A Chat app configured in a Google Cloud project (Chat API configuration) and published to a Workspace organisation or the Marketplace. Base URL `https://chat.googleapis.com`, REST v1.
  </Accordion>

  <Accordion title="Authentication" icon="key-round">
    App authentication with a service account for the app's own actions (scope `chat.bot`, or the granular `chat.messages.create` and `chat.messages`); user authentication with OAuth when acting for a person. Inbound deliveries carry a bearer JWT signed by `chat@system.gserviceaccount.com` with the audience set to the app's project number, verified against Google's published keys.
  </Accordion>

  <Accordion title="Post a question" icon="send">
    `spaces.messages.create`: `POST /v1/{parent=spaces/*}/messages` with a `cardsV2` payload. An optional `requestId` makes the create idempotent: an existing request ID returns the message it already created instead of posting a second one. `privateMessageViewer` keeps a question visible to one named person, so a diagnostic can run inside a busy space.
  </Accordion>

  <Accordion title="Lock in place" icon="lock">
    `spaces.messages.patch` (`PATCH /v1/{name=spaces/*/messages/*}`) with `updateMask=cardsV2` replaces the card in place, leaving an answered question with no buttons. A custom `messageId` at create time means the app can update or delete later without storing Chat's own resource name.
  </Accordion>

  <Accordion title="Question rendering" icon="layers">
    Cards v2. A message carries a list of `{cardId, card}` pairs, each card at most 32 KB, built from `textParagraph`, `decoratedText`, `buttonList` and `divider`, plus `textInput`, `selectionInput` and `dateTimePicker`. Where one step needs several fields at once, the app answers `actionResponse.type = DIALOG` with a `dialogAction.dialog.body` card instead.
  </Accordion>

  <Accordion title="Interactivity" icon="circle-dot">
    A button's `onClick.action` names a `function` and `parameters`. Chat posts a `CARD_CLICKED` event back and the app reads `commonEventObject.invokedFunction`, `.parameters` and `.formInputs.WIDGET_NAME`. Typed events cover `MESSAGE`, `ADDED_TO_SPACE`, `REMOVED_FROM_SPACE`, `CARD_CLICKED`, `WIDGET_UPDATED`, `APP_COMMAND`, `APP_HOME` and `SUBMIT_FORM`.
  </Accordion>

  <Accordion title="Transport" icon="radio">
    An HTTPS endpoint, a Pub/Sub topic, or Apps Script. A synchronous reply must be posted within 30 seconds; anything slower answers asynchronously by calling the Chat API. `spaces.spaceEvents.list` replays typed history such as `google.workspace.chat.message.v1.created`, so a missed delivery is recovered by reading history. Quotas are per space and per project: 60 writes per minute per space, and an exceeded quota returns 429 to retry with backoff.
  </Accordion>

  <Accordion title="Identity" icon="users">
    The acting person arrives as `user` on the event (`name`, `displayName`, `email` where the scope allows), which is what the gateway records as the requester.
  </Accordion>
</AccordionGroup>

## How the diagnostic runs in Google Chat

| Step | What happens on the platform                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | The requester opens the Triage app in Google Chat, or @mentions it in a space. Chat delivers a `MESSAGE` or `APP_COMMAND` interaction event to the gateway endpoint, carrying a bearer JWT.                                                                                                                                                                                                  |
| 2    | The gateway verifies the JWT against Google's published keys, checks issuer and audience, rejects anything unverifiable with 401, then resolves the requester from `user` and the conversation from `space` and `thread`.                                                                                                                                                                    |
| 3    | The gateway posts the first question with `spaces.messages.create`: one Cards v2 card, one question, buttons carrying the answer values. In a shared space the message sets `privateMessageViewer` so only the requester sees it.                                                                                                                                                            |
| 4    | A click delivers a `CARD_CLICKED` event within the 30 second window. The gateway reads `commonEventObject.invokedFunction` and `.parameters`, records the answer, and calls `spaces.messages.patch` with `updateMask=cardsV2` to replace the card with a locked version that has no buttons. Where a step needs several fields it answers `DIALOG` instead and reads `formInputs` on submit. |
| 5    | On the final answer the gateway calls the Triage decision core. The Intent Record is minted and the completion card (channel, confidence, `intent://` chip) is sent.                                                                                                                                                                                                                         |
| 6    | When composerID publishes downstream, the gateway updates the completion card with a button that deep-links to the created record.                                                                                                                                                                                                                                                           |

## Developer references

Google's official developer documentation. The REST facts on this page come from the machine-readable discovery document, which is the same artefact Google's own client libraries are generated from.

| Reference                                  | Vendor documentation                                                                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Chat API overview                          | [developers.google.com: Chat API overview](https://developers.google.com/workspace/chat/api-overview)                                      |
| Discovery document (v1, machine-readable)  | [chat.googleapis.com: discovery document](https://chat.googleapis.com/\$discovery/rest?version=v1)                                         |
| spaces.messages.create                     | [developers.google.com: spaces.messages.create](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create) |
| spaces.messages.patch                      | [developers.google.com: spaces.messages.patch](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch)   |
| Cards v2 reference                         | [developers.google.com: Cards](https://developers.google.com/workspace/chat/api/reference/rest/v1/cards)                                   |
| Receive and respond to interaction events  | [developers.google.com: Receive and respond to interactions](https://developers.google.com/workspace/chat/receive-respond-interactions)    |
| EventType                                  | [developers.google.com: EventType](https://developers.google.com/workspace/chat/api/reference/rest/v1/EventType)                           |
| Support interactive dialogs                | [developers.google.com: Dialogs](https://developers.google.com/workspace/chat/dialogs)                                                     |
| Collect and process information from users | [developers.google.com: Read form data](https://developers.google.com/workspace/chat/read-form-data)                                       |
| Verify requests from Google Chat           | [developers.google.com: Verify requests from Chat](https://developers.google.com/workspace/chat/verify-requests-from-chat)                 |
| Work with events from Google Chat          | [developers.google.com: Events overview](https://developers.google.com/workspace/chat/events-overview)                                     |
| Usage limits                               | [developers.google.com: Usage limits](https://developers.google.com/workspace/chat/limits)                                                 |

<Note>
  The Google Chat renderer and its contract tests live in `upstream/google_chat_cards.py`: the same gateway core as Teams, a different renderer. Locking is structural on this surface too: the answered card is replaced through `updateMask=cardsV2` with a version that has no buttons. [Upstream connectors](/connectors/overview) explains how to run the reference implementation.
</Note>

## Next steps

<Columns cols={2}>
  <Card title="Upstream connectors" icon="messages-square" href="/connectors/overview">
    The Intake Gateway, the card lifecycle and the hand-off to composerID.
  </Card>

  <Card title="Coverage and status" icon="table" href="/destinations/index">
    Every surface and destination with its registry status.
  </Card>
</Columns>