Google Chat API gebruiken voor chatbot-integraties

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.

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.

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.

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.

Een minimaal voorbeeld van een card-body:

{
  "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.

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.

Veelgestelde vragen

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