# Google Chat API gebruiken voor chatbot-integraties

[[TOC]]

Google Chat is meer dan een berichtenapp: het is een platform waarop je bots bouwt die meldingen sturen, vragen beantwoorden en workflows starten. Of je nu een simpele build-notificatie naar een space wilt sturen of een interactieve assistent wilt bouwen, de Chat API biedt beide.

In dit artikel verken je de twee integratiepaden, wanneer je welke kiest, en hoe je het veilig en betrouwbaar opzet.

## Twee manieren om te integreren

Er zijn twee fundamenteel verschillende benaderingen. De keuze hangt af van of je alleen wilt zenden of ook wilt ontvangen.

| Wat je wilt | Beste aanpak | Complexiteit |
| --- | --- | --- |
| Alleen meldingen naar een vaste space, geen interactie | Inkomende webhook | Laag |
| Gebruikers laten praten met je bot, knoppen, commando's | Volwaardige Chat-app met eigen endpoint | Hoog |
| Proactief berichten sturen vanuit je backend naar meerdere spaces | Chat-app met service account | Gemiddeld |

:::tip title="Begin klein"
Twijfel je? Start met een inkomende webhook. Werkt je use-case en wil je daarna interactie toevoegen, dan bouw je de webhook uit naar een volwaardige Chat-app. Je hoeft niet meteen het zwaarste pad te kiezen.
:::

## Inkomende webhooks

Dit is de snelste manier om iets in Chat te krijgen. Je maakt in de space een webhook aan (via **Apps en integraties**, **Webhooks beheren**) en stuurt er een POST met JSON naartoe.

```python
import requests

requests.post(
    WEBHOOK_URL,
    json={"text": "De nachtelijke build is geslaagd."},
    headers={"Content-Type": "application/json"},
)
```

Goed om te weten over webhooks:

- Een webhook post alleen in de space waarvoor hij is aangemaakt. Eenrichtingsverkeer dus.
- De per-space limiet is ongeveer 1 bericht per seconde, gedeeld door alle webhooks in die space.
- Een bericht mag maximaal 32.000 bytes groot zijn, inclusief tekst en cards.

:::warn title="Behandel de webhook-URL als een wachtwoord"
Iedereen met de webhook-URL kan ongevraagd in de space posten. Stop hem nooit in client-side code of in een publieke repository. Bewaar hem als secret in je secret manager en roteer hem direct als hij ooit lekt.
:::

## Rijke berichten met cards

Platte tekst is prima, maar met cards bouw je gestructureerde berichten met koppen, knoppen en afbeeldingen. Je gebruikt hiervoor de sleutel `cardsV2` in de berichtbody.

:::howto title="Een card opbouwen en versturen"
1. Bouw een `cardsV2`-structuur op met `sections` en daarin `widgets`.
2. Voeg knoppen toe die naar een URL linken of een actie triggeren.
3. Verpak de card in de berichtbody onder de sleutel `cardsV2`.
4. Verstuur de body via de webhook of via de Chat API.
:::

Een minimaal voorbeeld van een card-body:

```json
{
  "cardsV2": [
    {
      "cardId": "build-status",
      "card": {
        "header": { "title": "Build geslaagd" },
        "sections": [
          {
            "widgets": [
              { "textParagraph": { "text": "Versie 2.4.0 staat klaar." } },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Bekijk logs",
                      "onClick": { "openLink": { "url": "https://example.com/logs" } }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
```

## Een interactieve Chat-app

Voor echte interactie bouw je een app die events ontvangt. Google stuurt een HTTPS-request naar jouw endpoint wanneer een gebruiker je bot aanspreekt. De flow ziet er zo uit:

1. Een gebruiker noemt je bot of stuurt een bericht in een space.
2. Google stuurt een event naar je geconfigureerde endpoint.
3. Je app verwerkt het bericht en bepaalt een antwoord.
4. Je stuurt een JSON-response terug, eventueel met een card.
5. Voor proactieve berichten roep je `spaces.messages.create` aan op de Chat API.

:::danger title="Verifieer elk inkomend request"
Google voegt aan elk request een bearer-token toe in de `Authorization`-header. Bij audience-instelling Project Number is dat een self-signed JWT, uitgegeven en ondertekend door `chat@system.gserviceaccount.com`. Valideer dit token altijd tegen Google's publieke sleutels met een officiele Google API-clientbibliotheek (Java, Python, Node.js of .NET). Verifieert het token niet, antwoord dan met HTTP-status 401. Sla deze controle nooit over, anders kan iedereen je bot-endpoint misbruiken.
:::

## Authenticatie voor de API

Voor het proactief sturen van berichten via de API gebruik je een service account met de juiste Chat-scopes. De app moet in je Workspace gepubliceerd en goedgekeurd zijn voordat hij in spaces kan posten.

Een Chat-app configureer je in de Google Cloud Console onder de Chat API-instellingen. Daar stel je in:

- hoe gebruikers de bot vinden;
- welk endpoint events ontvangt;
- welke authentication audience geldt (Project Number of HTTP endpoint URL);
- welke slash-commando's beschikbaar zijn.

:::info title="Cloud Run als endpoint"
Draait je app-logica op een Cloud Run-functie? Kies dan **HTTP endpoint URL** als authentication audience en zorg dat de geconfigureerde URL exact overeenkomt met de URL van je Cloud Run-endpoint. Anders mislukt de tokenverificatie.
:::

## Veelgestelde vragen

:::faq
### Wat is het verschil tussen een webhook en een Chat-app?
Een webhook stuurt berichten maar een kant op, naar een specifieke space. Een Chat-app kan tweerichtingsverkeer aan: reageren op gebruikers, knoppen verwerken en in meerdere spaces werken.

### Kan mijn bot in elke space posten?
Alleen in spaces waar de bot is toegevoegd. Voor webhooks geldt: uitsluitend de space waarvoor de webhook is aangemaakt.

### Hoe maak ik slash-commando's?
Definieer ze in de Chat API-configuratie in de Google Cloud Console. Je app ontvangt dan een gestructureerd event zodra iemand het commando gebruikt.

### Ondersteunt Chat interactieve formulieren?
Ja. Met dialogs en form-widgets in cards verzamel en verwerk je invoer zonder dat de gebruiker de space hoeft te verlaten.

### Hoeveel berichten mag ik per seconde sturen?
Webhooks delen een limiet van ongeveer 1 bericht per seconde per space. Voor de Chat API gelden ruimere, per-project quota die je in de Cloud Console kunt bekijken.

### Hoe groot mag een bericht zijn?
Maximaal 32.000 bytes, inclusief tekst en cards. Grote payloads splits je beter op in meerdere berichten of een card met meerdere secties.
:::

Met de Chat API breng je je systemen direct in de communicatiestroom van je team, van simpele meldingen tot slimme assistenten.