Chat APIでメッセージ検索とピン留め 社内ツールに使う条件

「あの手順、Chatのどこかで共有されたはず」と探して、結局見つからない。スペースが増えるほど、決定事項や手順書へのリンクはメッセージの流れに埋もれます。Google Chatの画面で検索やピン留めはできますが、社内ツールやApps Scriptから同じことをするAPIは、これまで限られていました。

Chat APIのリリースノートによると、メッセージ検索のAPI（spaces.messages.search）は2026年7月30日に、ピン留めのAPI（spaces.messagePins）は9月18日に一般提供（GA）になりました。どちらもそれ以前はDeveloper Preview（申し込んだ開発者向けの先行提供）でした。本記事では、2026年10月6日にChat APIのリリースノートと開発者ガイド、Googleが公開している定義ファイル（googleapis/googleapis）の履歴、Chat APIのDiscovery文書（v1、revision 20261001）を直接開いて確認した内容をもとに、社内ツールに組み込む前に知っておきたい条件を整理します。資料調査と編集部の提案で、認証情報がないためAPIの実際の呼び出しは行っていません。

増えたのは「横断検索」と「ピン留めの読み書き」

今回の対象は2つのAPIです。

どちらもユーザー認証（利用者本人としてAPIを呼ぶ方式）だけが書かれており、Chatアプリ自身として呼ぶアプリ認証は対象外です。つまり、APIで見えるのは呼び出した人がChatで見られる範囲だけです。会社全体のメッセージを管理者として横断する用途には使えません。

ピン留めのAPIは、Discovery文書には8月下旬（revision 20260820）から載っており、googleapis/googleapis の2026年9月16日のコミット（4bcbf04、「Graduate MessagePin APIs to General Availability (GA)」）で一般提供として定義ファイルに入り、リリースノートでは9月18日付けで「Developer Previewの限定ではなくなった」と告知されています。ピン留め用に chat.spaces.pins（「See, add, and remove pins in your Google Chat spaces」）と chat.spaces.pins.readonly（「See pins in your Google Chat spaces」）の2つのスコープが新設されています。ピン留めの名前は spaces/{space}/messagePins/{message_pin} で、末尾のIDは元のメッセージのIDと同じだと説明されています。一覧は1回に最大100件です。

メッセージ検索は、リリースノートでは2026年5月12日にDeveloper Preview、7月30日にGAとなっています。定義ファイルには7月30日のコミット（36d9a9b、「Addition of the Search Messages API」）で追加され、9月18日のコミット（a557eba）でスペースの種類による絞り込みが加わりました。Discovery文書でも、検索そのものに「Developer Preview」の表示はありません。ただし、関連度順の並べ替え（relevance）だけはDeveloper Previewと書かれています。

対象エディションについては、開発者ガイド（検索・ピン留めとも）の前提条件に「Business または Enterprise の Google Workspace アカウント」と書かれています。Workspace Updates（管理者向けの更新情報ブログ）では、この2つのAPIを扱った告知は見つけられませんでした。

検索で絞り込める条件

検索の filter には、キーワードに加えて次の条件を書けます。Discovery文書の説明をまとめると次のとおりです。

• 期間: create_time（< と >=）
• 送信者: sender.name = "users/{user}"。{user} の代わりにメールアドレスも使える
• スペース: space.name = "spaces/..."、または表示名の部分一致 space.display_name:Project（一致上位5スペースまで）
• スペースの種類: space.space_type = "DIRECT_MESSAGE"（ほかに GROUP_CHAT・SPACE）
• 添付ファイルあり: attachment:*
• メンション: annotations.user_mentions.user.name:users/me（自分宛て）
• 関数: has_link()（リンクを含む）、is_unread()（未読のみ）

異なる項目どうしは AND だけで組み合わせられ、同じ項目の中で OR を使える項目が決まっています。クエリは最大1,000文字です。結果は既定で作成日時の新しい順に25件、最大100件ずつ返ります。

parent は必ず spaces/- を指定し、それ以外は INVALID_ARGUMENT になります。特定のスペースだけを探すときも、parent ではなく filter の space.name で絞ります。また、表示名・種類での絞り込みには chat.spaces.readonly などのスコープ、is_unread() には既読状態のスコープ（chat.users.readstate.readonly など）が追加で必要です。

たとえば「自分宛てのメンションで、まだ読んでいないもの」を1週間分探すなら、filter は次のようになります（日時は例です）。

annotations.user_mentions.user.name:users/me AND is_unread() AND create_time >= "2026-09-29T00:00:00+09:00"

検索に入らないメッセージが5種類ある

組み込みでいちばん注意したいのは、検索の説明文に「This API doesn’t return all message types」とあり、次の5種類が結果に含まれないことです。

1. 呼び出した人にだけ見えるプライベートメッセージ
2. Chatアプリがスペースやグループチャットに投稿したメッセージ
3. ChatアプリとのDMのメッセージ
4. ブロックしたユーザーのメッセージ
5. 呼び出した人がミュートしたスペースのメッセージ

2番目は、通知の集約に使う場合に影響します。監視ツールやフォームの通知、日報ボットなど、Chatアプリが投稿したメッセージは検索に出てきません。「アラートの履歴を検索APIで集める」という設計は成り立たないため、その場合は説明文が案内しているとおり、スペースごとに spaces.messages.list で取得します。5番目にも注意が必要です。同じ検索でも、実行する人がどのスペースをミュートしているかで結果が変わります。

検索結果には、view に SEARCH_MESSAGES_VIEW_FULL を指定し、対応するスコープがあれば、既読かどうか（read）とスペースのミュート設定（spaceMuteSetting）も付きます。結果を他人と共有する一覧に転記する場合は、これらが「実行した人から見た状態」である点に注意してください。

社内ツールでの使い方（編集部の提案）

定義から読み取れる範囲で、次のような使い方が考えられます。いずれも、実行する本人の権限で動く「個人用・チーム用の補助ツール」としての使い方です。

• ピン留めを手順書の目次にする: プロジェクトのスペースで、決定事項や手順へのリンクをピン留めしておき、週に一度 messagePins.list で一覧を取り、元のメッセージを spaces.messages.get で引いてスプレッドシートやドキュメントにまとめる。ピン留めのIDとメッセージのIDが同じなので、突き合わせは簡単です
• 自分宛ての未読メンションをまとめる: 上の filter で、朝に未読のメンションを一覧にしてメールやタスクに送る
• 添付ファイル付きのメッセージを棚卸しする: attachment:* と期間で絞り、どのスペースでファイルがやり取りされているかを確認する

スプレッドシートを台帳にする構成は、GASによる自動化の基本の考え方をそのまま使えます。送信者の表示名やメールが返る条件は、Chat APIで送信者のメールが取れるようにで整理したとおり、相手との関係で変わります。

管理者が先に確かめること

検索に必要な chat.messages.readonly は、利用者が見られるChatのメッセージを読むスコープです。検索に限らず、DMを含めて読めるため、社内ツールに付与する前に次の点を確かめるのが安全です。

1. 誰のアカウントで動かすか: 個人のアカウントで動かすと、その人のDMも検索の対象になります。チームの共有ツールにするなら、専用のアカウントを用意し、参加するスペースを限るのが無難です
2. どのスコープを求めるか: ピン留めの一覧だけなら chat.spaces.pins.readonly で足ります。必要以上に chat.messages や chat.spaces を求めていないかを確認します
3. アプリの許可: Chatアプリや外部アプリのアクセスを管理コンソールで制限している場合は、Chatアプリの許可リストなどの設定と合わせて確認します
4. 結果の保存先: 検索結果をスプレッドシートに書き出すと、元のスペースのメンバー以外にも内容が見える場合があります。共有範囲を元のスペースと揃えます

組み込む前の落とし穴

• ボットの通知を検索で集めようとする: Chatアプリの投稿は検索の対象外です。一覧で取得します
• parent にスペースを指定する: spaces/- 以外はエラーになります。スペースは filter で絞ります
• 関連度順を本番で使う: relevance の並べ替えはDeveloper Previewです。既定の新しい順で組みます
• 対象エディションを確かめずに配る: 開発者ガイドの前提条件はBusinessまたはEnterpriseのアカウントです。ほかのエディションで動くかは確認していません

まずは、Chatに埋もれがちな情報が「ピン留めしておけば足りるもの」か「検索で拾う必要があるもの」かを分けてください。ピン留めで足りるなら、chat.spaces.pins.readonly だけの小さなツールから始めるのが、権限の面でもいちばん安全です。

2026年10月6日に、Chat APIのリリースノート、開発者ガイド（メッセージの検索、ピン留め）、googleapis/googleapis のChat API定義ファイル（google/chat/v1/chat_service.proto・message_pin.proto、commit 4bcbf04・36d9a9b・a557eba）、Chat APIのDiscovery文書（v1、revision 20261001）、google-api-go-client の履歴、npmの @googleapis/chat 51.2.0 の型定義を直接取得して照合しました（資料調査）。社内ツールでの使い方と管理者の確認点は編集部の提案です。認証情報がないためAPIの呼び出しは実施しておらず、実際の応答、Business・Enterprise以外のエディションでの動作は未確認です。検索のガイドにあるApps Scriptの例は、高度なChatサービスではなく UrlFetchApp でRESTを直接呼ぶ形でした。Workspace Updatesでは該当する告知を見つけられませんでした。

Google Chatを使った情報共有の整理や、社内ツールの権限の見直しは、グリームハブのIT・Google Workspace 無料相談で承っています。扱う情報やスペースの使い方によって進め方が変わるため、お問い合わせからご相談ください。

参考資料

• Google Chat API release notes
• Search messages（Google Chat API ガイド）
• Pin or unpin messages in Google Chat spaces（Google Chat API ガイド）
• googleapis/googleapis — commit 4bcbf04（Graduate MessagePin APIs to General Availability (GA)）
• googleapis/googleapis — google/chat/v1/message_pin.proto（4bcbf04）
• googleapis/googleapis — commit 36d9a9b（Addition of the Search Messages API）
• googleapis/googleapis — commit a557eba（space.space_type filter for SearchMessages）
• Google Chat API Discovery document (v1)
• npm registry — @googleapis/chat