HULFT Square から Google Chat に「終わったよ」と言わせたい（Google Chat API ）

Last updated at 2026-10-28Posted at 2026-10-28

はじめに：バッチは黙って働きすぎる

HULFT Square のデータ連携は、今日も黙々と働いています。
深夜に、誰にも見られず、文句ひとつ言わずに。

……でも、終わったなら終わったと言ってほしい。失敗したならなおさら言ってほしい。
朝イチで実行履歴を開いて「あ、昨日の夜コケてたのか……」と気づくあの瞬間、心がちょっとだけ冷えますよね。

そこで本記事では、HULFT Square に Google Chat でしゃべってもらう 方法をまとめます。

ちなみに HULFT Square には Google Chat 専用のコネクターはありません。
でも大丈夫。汎用の RESTコネクター という「HTTP なら誰とでも話せる」頼れる子がいます。

この記事でやること

	方式	できること	準備の手間	投稿者の表示	たとえるなら
①	受信 Webhook	送信のみ（一方通行）	★☆☆	Webhook に付けた名前	郵便受けに手紙を入れる
②	Chat API + OAuth 2.0	送信・取得・更新など	★★★	認証したユーザーの名前	合鍵をもらって家に上がる

通知を送るだけなら ① Webhook で十分です。
「Chat の書き込みを読みたい」「メッセージを書き換えたい」など欲が出てきたら ② に進みましょう。

送る以外もしたいなら ② Chat API の出番です。
Google Chat API は、実はかなりの多才です。メッセージだけでなく、スペースの作成、メンバーの追加、リアクション、添付ファイル、カスタム絵文字、既読状態……と、Chat でできることの多くを API から操作できます。

ただ、全部試していたら記事が終わりません。今回はその中から 「メッセージを送る」 と 「メッセージを取得する」 の 2 つをつまみ食いしました

前提条件：まずは入場券

Google Workspace（Business または Enterprise）のアカウント
Google Cloud プロジェクト（② の方式のみ）
HULFT Square の環境（Designer が使えること）

Google Cloud の契約だけでは Google Chat は使えません。
Google Chat は Google Workspace の製品です。「Google Cloud ならあるから大丈夫！」と意気揚々と始めると、スペースを作る段階で膝から崩れ落ちることになります¹。

検証目的であれば、Google Workspace の 14日間無料試用（Business Starter で OK）が使えます。

① 受信 Webhook で通知する

1-1. 管理コンソールで「郵便受けの設置」を許可する

Workspace を新しく作った場合は、まず Webhook を使ってよいか確認します。

管理コンソール（ https://admin.google.com ）を開く
「アプリ」→「Google Workspace」→「Google Chat」
「Chat アプリ」の設定で、以下がオンになっていることを確認
- ユーザーに Chat アプリのインストールを許可する
- ユーザーに受信 Webhook の追加と使用を許可する

1-2. スペースと Webhook を作る

PC のブラウザ で Google Chat（ https://chat.google.com ）を開く
通知用のスペースを作成（例：HULFT通知テスト）
スペース名の横の ▼ →「アプリと統合」→「Webhook を追加」
名前（例：HULFT Square）を入力して「保存」
作成した Webhook の「︙」→「リンクをコピー」

Webhook は スマホアプリからは設定できません。PC の前に座りましょう。

アバター URL には何を入れる？

空欄で OK です。送信者のアイコンとして表示される画像の URL で、空欄なら Google の標準アイコンになります。
Google Chat のアイコンにしたい場合は、Google 公式の手順でも使われている以下の URL が使えます。

https://developers.google.com/chat/images/chat-product-icon.png

コピーした URL はこんな形です。

Webhook URL の形式

https://chat.googleapis.com/v1/spaces/{SPACE_ID}/messages?key={KEY}&token={TOKEN}

この URL は スペースの合鍵 のようなものです。知っていれば誰でも投稿できます。

1-3. まず PC から呼びかけてみる

いきなり HULFT Square で試してうまくいかないと、「Google が悪いのか、HULFT Square が悪いのか、私が悪いのか」の 三択問題 に突入します。
先に Google 側だけで動くか確かめておきましょう。

コマンドプロンプト

curl -X POST -H "Content-Type: application/json; charset=UTF-8" -d "{\"text\":\"test\"}" "{コピーしたWebhook URL}"

スペースに「test」と表示されれば成功です

成功時のレスポンス例

レスポンス

{
  "name": "spaces/{SPACE_ID}/messages/xxxxxxxx",
  "text": "test",
  "thread": {
    "name": "spaces/{SPACE_ID}/threads/xxxxxxxx"
  },
  "space": {
    "name": "spaces/{SPACE_ID}"
  }
}

1-4. URL を 3 つに分解する

HULFT Square では、URL を「本体」と「クエリパラメータ」に分けて設定します。

部分	例	設定場所
`?` より前	`https://chat.googleapis.com/v1/spaces/{SPACE_ID}/messages`	RESTコネクションの URL
`key=` の値	`{KEY}`	クエリパラメータ `key`
`token=` の値	`{TOKEN}`	クエリパラメータ `token`

1-5. 送るメッセージを用意する

メモ帳で以下を作成し、UTF-8 で保存します。

message.json

{"text": "HULFT Squareからのテスト通知です"}

保存したファイルを HULFT Square のストレージにアップロードします（例：/test/message.json）。

1-6. RESTコネクションを作る

メニュー →「HULFT INTEGRATE」→「コネクション」→「追加」
種類：REST接続
全般：名前（例：GoogleChat_Webhook）、ワークスペースを設定
設定：URL に 1-4 の「? より前」を入力
プロファイル → サマリーで「完了」

1-7. Designer で POST実行を設定する

新規スクリプトを作成し、ツールパレットの REST →「POST実行」 を置いて、開始 → POST実行 → 終了をつなぎます。

タブ	項目	設定値
必須設定	接続先	`GoogleChat_Webhook`
必須設定	クエリパラメータ	`key` ／ `{KEY}` `token` ／ `{TOKEN}`

タブ	項目	設定値
リクエスト設定	データ入力元	ファイル（ファイルパスは手順1-5で用意したファイルのパス）

タブ	項目	設定値
ヘッダ設定	リクエストヘッダ	`Content-Type` ／ `application/json; charset=UTF-8`

1-8. 実行して確認する

スクリプトを実行して、スペースに「HULFT Squareからのテスト通知です」が届けば完了です。
無口だった HULFT Square が、ついにしゃべりました

② Chat API + OAuth 2.0 で連携する

Webhook は「送るだけ」でした。
Chat API を使えば、読む・書き換える・スペースを作る なども可能になります。そのぶん準備は増えますが、がんばりましょう。

認証方式の選び方

Chat API の認証方式はユーザー認証とアプリ認証の 2 種類があります。
本記事では ユーザー認証（OAuth 2.0） を使います。

OAuth 2.0 の流れ

2-1. Google Cloud プロジェクトを作る

Google Cloud コンソール（ https://console.cloud.google.com ）に、Google Workspace のアカウント でログインします。

「新しいプロジェクト」を作成
Organization（組織）／ Parent resource（親リソース） に Workspace の組織（例：example.com）を選択

Workspace の組織配下にプロジェクトを作ると、後で OAuth 同意画面を「内部（Internal）」にできます。
「外部（External）」かつ「テスト中」のままだと、リフレッシュトークンが 7日で失効 します。毎週月曜に再発行する運用は、なかなかの修行です。

親リソースに組織が出てこない場合

右上のアカウントアイコンで、Workspace のアカウントでログインしているか確認する
Workspace の管理コンソールで「アプリ」→「追加の Google サービス」→「Google Cloud Platform」がオンになっているか確認する
Workspace の組織は、初めて Google Cloud にログインしたときに作られるため、数分待ってから再読み込みする

2-2. Google Chat API を有効化する

上部の検索ボックスで「Google Chat API」を検索して、「有効にする（Enable）」をクリック。ここは一瞬で終わります

2-3. Chat アプリを構成する

Google Chat API の画面で「構成（Configuration）」タブを開き、以下を入力して保存します。

項目	設定値（例）
アプリ名	`HULFT Square`
アバター URL	`https://developers.google.com/chat/images/chat-product-icon.png`
説明	`HULFT Square連携`
インタラクティブ機能	オフ

「ユーザー認証なんだから、アプリの構成はいらないでしょ？」と思いがちですが、必要です。
ここを飛ばすと、トークンは元気に発行できるのに、API を呼んだ瞬間に怒られます。

2-4. OAuth 同意画面（Google Auth Platform）を設定する

メニュー →「Google Auth Platform」→「Get started」から設定します。

ステップ	項目	設定値（例）
App Information	App name	`HULFT Square`
	User support email	Workspace のメールアドレス
Audience	ユーザーの種類	Internal（内部）
Contact Information	Email addresses	Workspace のメールアドレス
Finish	ポリシーへの同意	チェック → Create

2-5. OAuth クライアント ID を作る

「Clients」→「Create client」から作成します。

項目	設定値
Application type	Web application
Name	`HULFT Square`
Authorized JavaScript origins	（空欄）
Authorized redirect URIs	`https://app.square.hulft.com/connections/oauth2/callback`

リダイレクト URI は、HULFT Square の OAuth 2.0 コネクション設定画面に表示されている「Redirect URI」と同じ値です。コピペ推奨。手打ちは事故のもとです。

作成後に表示される クライアント ID と クライアントシークレット を控えておきます（JSON のダウンロードもしておくと安心）。

画面に「反映まで 5 分〜数時間かかることがある」と書かれています。
次の手順でエラーが出たら、コーヒーでも淹れて少し待ってから再挑戦しましょう

2-6. HULFT Square で OAuth 2.0 コネクションを作る

メニュー →「HULFT INTEGRATE」→「コネクション」→「追加」
種類：検索ボックスに「OAuth」と入力し、OAuth 2.0認証 を選択
全般：名前（例：GoogleChat_OAuth）を設定
設定：以下のとおり入力

項目	設定値
クライアントID	2-5 で取得した値
クライアントシークレット	2-5 で取得した値
認可エンドポイント	`https://accounts.google.com/o/oauth2/v2/auth`
トークンエンドポイント	`https://www.googleapis.com/oauth2/v4/token`
スコープ	`https://www.googleapis.com/auth/chat.messages.create`
クライアント認証方式	`client_secret_basic`
アクセストークン有効期間(秒)	`3500`
詳細設定 / 追加パラメータ	`access_type` ／ `offline` `prompt` ／ `consent`

すべて入力してから「リフレッシュトークン発行...」をクリック
Google のログイン画面で Workspace のアカウントでログインし、同意する
「authorization succeeds」と表示されたら OK → 「次へ」
プロファイル → サマリーで「完了」

2-7. Chat API 用の RESTコネクションを作る

Webhook 用とは別に、Chat API 用の RESTコネクションも作ります。

項目	設定値
名前	`GoogleChat_API`
URL	`https://chat.googleapis.com`

2-8. メッセージを送る（spaces.messages.create）

Designer で「POST実行」を置き、以下のとおり設定します。

タブ	項目	設定値
必須設定	接続先	`GoogleChat_API`
必須設定	パス	`v1/spaces/{SPACE_ID}/messages`
必須設定	クエリパラメータ	なし

タブ	項目	設定値
リクエスト設定	データ入力元	ファイル
リクエスト設定	ファイルパス	`/test/message.json`

タブ	項目	設定値
ヘッダ設定	リクエストヘッダ	`Content-Type` ／ `application/json; charset=UTF-8`

タブ	項目	設定値
認証設定	認証	Authコネクション利用
認証設定	接続先	`GoogleChat_OAuth`

落とし穴：OAuth コネクションが見当たらない
POST実行では、コネクションを 2か所で別々に 指定します。

「必須設定」の接続先 → RESTコネクション（GoogleChat_API）
「認証設定」の接続先 → OAuth 2.0コネクション（GoogleChat_OAuth）

「必須設定」のプルダウンをいくら眺めても OAuth コネクションは出てきません。
「認証設定」タブで「Authコネクション利用」を選ぶと、ようやく姿を現します。

{SPACE_ID} は、ブラウザでスペースを開いたときの URL（.../space/{SPACE_ID}）や、Webhook URL の spaces/ の後ろで確認できます。

実行してメッセージが届けば成功です
ただし Webhook と違い、投稿者はあなた自身（OAuth 認証したユーザー） として表示されます。
深夜 2 時に自分の名前で「バッチ完了しました」と投稿され、同僚に「こんな時間まで働いてるの……？」と心配されないようご注意ください²。

2-9. メッセージを読む（spaces.messages.list）

しゃべれるようになったら、次は聞く番です

スコープを追加してトークンを再発行する

OAuth 2.0 コネクション（GoogleChat_OAuth）を編集し、スコープを追加

追加するスコープ

https://www.googleapis.com/auth/chat.messages.readonly

「リフレッシュトークン発行...」をもう一度クリックして、同意し直す

スコープを追加したのにトークンを再発行しないと、403 で門前払い されます。
「権限を増やしたら、合鍵も作り直す」と覚えておきましょう。

GET実行を設定する

Designer で REST の「GET実行」を置き、以下のとおり設定します。

タブ	項目	設定値
必須設定	接続先	`GoogleChat_API`
必須設定	パス	`v1/spaces/{SPACE_ID}/messages`
必須設定	クエリパラメータ	`pageSize` ／ `10` `orderBy` ／ `createTime desc`
レスポンス設定	データ出力先	ファイル
レスポンス設定	ファイルパス	`/test/messages_result.json`
レスポンス設定	4xx、5xxの場合エラーにする	チェックあり
認証設定	認証	Authコネクション利用 → `GoogleChat_OAuth`

実行すると、こんな JSON が出力されます。

messages_result.json

{
  "messages": [
    {
      "name": "spaces/{SPACE_ID}/messages/xxxxxxxx",
      "sender": { "name": "users/1234567890", "type": "HUMAN" },
      "createTime": "2026-10-16T02:10:00.123456Z",
      "text": "取得テストです"
    }
  ],
  "nextPageToken": "xxxxxxxx"
}

項目	説明
`text`	メッセージ本文
`createTime`	投稿日時（UTC）。日本時間は +9 時間です
`sender.name`	投稿者。表示名ではなくユーザー ID で返ります
`nextPageToken`	続きがあるときに返る値。次のリクエストで使います