Chat APIのreplaceCards 投稿のカードを後から更新（先行提供）

社内のチケット管理や案件管理のURLをGoogle Chatに貼ると、番号と状況をカードで表示する。そんなChatアプリ（リンクのプレビュー）を作ると、困ることが1つあります。カードに出るのは貼った時点の状況で、その後に「対応完了」になっても、スペースには「受付」のカードが残り続けます。カードを見て判断した人が、すでに片付いた件に手を出してしまうこともあり得ます。

これまでのChat APIの定義を読む限り、ユーザーが投稿したメッセージのカードをアプリが変えられるのは、リンクが投稿されたときやカードのボタンが押されたときの「応答」に限られていました。ところが、10月20日に取得したChat APIのDiscovery文書（Googleが各APIのメソッドと型を機械可読の形で公開しているもの）の新しい版（revision 20261015）に、メッセージのカードを差し替えるメソッド spaces.messages.replaceCards が加わっています。リファレンスにも同じメソッドのページがあり、冒頭に「Developer Preview: Available as part of the Google Workspace Developer Preview Program」と書かれています。参加を申し込んだ開発者向けの先行提供で、一般提供（GA）ではありません。

本記事では、リファレンスとDiscovery文書の原文から、できることと条件を整理します（資料調査と編集部の提案）。Chat APIのリリースノートには10月20日時点でまだ載っておらず、一般提供の時期や対象のエディションは分かりません。実際の呼び出しも行っていません。

これまで、ユーザーの投稿のカードを変えられたのはいつか

Chatアプリがメッセージのカードを変える方法は、定義の上では次の3つです。上の2つは前の版（revision 20261013）からあるもので、3つ目が新しい版で加わったものです。

patch の説明には「When using app authentication, requests can only update messages created by the calling Chat app.」とあり、ユーザーの投稿に付けたリンクのプレビューは patch では変えられません。

もう1つの応答 UPDATE_USER_MESSAGE_CARDS は「This is only permitted as a response to a MESSAGE event with a matched url, or a CARD_CLICKED event where the message sender type is HUMAN.」と定義されています。つまり、リンクが投稿された瞬間か、ユーザーの投稿に付いたカードのボタンが押された瞬間にしか使えません。外のシステムで状況が変わったときに、アプリの側から変える手段は、前の版の定義には見当たりませんでした。

replaceCards の定義に書かれていること

リファレンスとDiscovery文書で、replaceCards の説明は次のとおりです（リファレンスでは、この前に上のDeveloper Previewの一文が付いています）。

Replaces the cards included in a message. A Chat app can only replace cards on a human-created message if the message already contains cards, and the cards were created by the app. If the app replaces the cards with an empty list, the cards are removed. After removing the cards, the app cannot add cards back to the message.

読み取れる条件を、実装の観点で並べます。

1. ユーザーの投稿では、自分のカードがあるときだけ: すでにカードが付いていて、そのカードを付けたのが呼び出すアプリであることが条件です。リンクのプレビューで付けたカードは、この条件に当てはまる形です。カードの付いていない投稿に、後からカードを足すことはできません
2. 空にすると消え、二度と付けられない: 空の配列で呼ぶとカードが消え、そのメッセージにはカードを戻せなくなります。「表示を一度消して描き直す」使い方は避けます
3. アプリの認証のみ: 認証はアプリの認証で、スコープは https://www.googleapis.com/auth/chat.bot だけが挙がっています。ユーザーの認証で呼ぶことは想定されていません
4. 差し替えは全体: 要求の cardsV2 について「These cards will replace the existing cards of the message.」とあり、渡したカードの配列で既存のカードが置き換わります。応答（ReplaceMessageCardsResponse）には項目がなく、リファレンスでも「If successful, the response body is empty.」です

カードの型 CardWithId には、新しい版で ownerUser（「Output only. The app that owns the card.」）が加わりました。cardId は「Required if the message contains multiple cards.」、カード1枚の上限は「Maximum size is 32 KB.」です。アプリ自身の投稿に replaceCards を使えるかは説明に書かれておらず、その用途はこれまでどおり patch（updateMask に cards_v2）で足ります。

状況が変わったらカードを差し替える流れ

リンクのプレビューと組み合わせる場合、流れは2段階になります。

1. リンクが投稿されたとき: MESSAGE イベントの message.matchedUrl に、プレビューの対象になったURLが入ります。応答で UPDATE_USER_MESSAGE_CARDS とカードを返し、同時にメッセージの名前（spaces/…/messages/…）を、問い合わせ番号などと一緒に保存しておきます
2. 状況が変わったとき: 保存したメッセージの名前に対して replaceCards を呼び、新しい状況のカードを渡します

次のコードは、問い合わせ番号のURLを想定した例です。replaceCards は10月20日時点でNode.js用のクライアントライブラリ（@googleapis/chat 51.2.0、googleapis 186.0.0）に入っていないため、Discovery文書のパス v1/{+name}:replaceCards を直接呼んでいます。カードとイベントの型は @googleapis/chat 51.2.0 の型定義を使い、TypeScriptの型チェックを通しました。

import { auth, chat_v1 } from '@googleapis/chat';

type CardWithId = chat_v1.Schema$CardWithId;

// 問い合わせ番号のリンクに付けるカード（cardId は同じ値を使い続ける）
export function ticketCard(ticketId: string, status: string): CardWithId {
  return {
    cardId: `ticket-${ticketId}`,
    card: {
      header: { title: `問い合わせ ${ticketId}`, subtitle: `状況: ${status}` },
      sections: [{ widgets: [{ textParagraph: { text: `最終更新: ${new Date().toISOString()}` } }] }],
    },
  };
}

// 1) リンクが投稿されたとき（MESSAGE イベントの応答）。
//    カードを付けたメッセージの名前を、問い合わせ番号と一緒に保存しておく
export function onLinkPosted(event: chat_v1.Schema$DeprecatedEvent, save: (ticketId: string, messageName: string) => void) {
  const url = event.message?.matchedUrl?.url;
  const messageName = event.message?.name;
  const ticketId = url?.match(/tickets\/(\d+)/)?.[1];
  if (!ticketId || !messageName) return {};
  save(ticketId, messageName);
  return {
    actionResponse: { type: 'UPDATE_USER_MESSAGE_CARDS' },
    cardsV2: [ticketCard(ticketId, '受付')],
  };
}

// 2) 後から状況が変わったとき。replaceCards は 10月20日時点でクライアントライブラリに
//    入っていないため、Discovery 文書のパス（v1/{+name}:replaceCards）を直接呼ぶ
const googleAuth = new auth.GoogleAuth({
  keyFile: process.env.CHAT_APP_KEY_FILE, // Chat アプリのサービスアカウントの鍵
  scopes: ['https://www.googleapis.com/auth/chat.bot'],
});

export async function replaceCards(messageName: string, cardsV2: CardWithId[]) {
  const client = await googleAuth.getClient();
  await client.request({
    url: `https://chat.googleapis.com/v1/${messageName}:replaceCards`,
    method: 'POST',
    data: { cardsV2 },
  });
}

// 例: await replaceCards(saved.messageName, [ticketCard('1234', '対応完了')]);

設計のうえで決めておきたい点が3つあります（編集部の提案）。

• 保存するのはメッセージの名前: 後から差し替えるには、カードを付けたメッセージの名前が必要です。同じ問い合わせのURLが複数のスペースに貼られることもあるため、問い合わせ番号1つに対して複数の名前を持てる形で保存します
• 消すのではなく「終了」のカードに替える: 空の配列で消すと付け直せません。対応が終わった件は、「対応完了」や「この件はクローズ済み」と書いたカードに差し替えるほうが、後から状況を戻す必要が出たときにも困りません
• カードに載せる情報の範囲: カードはスペースの全員が見ます。顧客名などを載せるかは、URLを貼る人任せにせずアプリの側で決めます

上の例は、Discovery文書で DeprecatedEvent という型の操作イベントを受け取る、アドオンではないChatアプリを想定しています。Googleのリンクのプレビューのガイドでも、アドオンではないChatアプリは UPDATE_USER_MESSAGE_CARDS の応答でカードを付けると説明されています。Google Workspaceのアドオンとして作ったChatアプリは別のイベントの形式（updateInlinePreviewAction など）を使い、その場合の replaceCards の使い方は確認していません。

提供段階と、まだ分からないこと

一番の注意点は、replaceCards がDeveloper Preview（先行提供）の段階にあることです。Google WorkspaceのDeveloper Preview Programの案内によると、参加にはGoogle WorkspaceのアカウントとGoogle Cloudのプロジェクトを登録して申し込む必要があります。また「features in Developer Preview may not be included in public applications prior to the General Availability announcement」とあり、一般提供の告知までは、公開するアプリに組み込めない前提で考えます。同じ案内では、先行提供の期間は通常3〜6か月とされています。

ほかの資料の状況は次のとおりです（10月20日時点）。

• Chat APIのリリースノートの最新の項目は10月16日で、replaceCards の告知はありません
• Node.js用の googleapis 186.0.0（10月14日公開）と @googleapis/chat 51.2.0（10月3日公開）の型定義、Python用のgoogle-api-python-clientのリポジトリ（mainの同梱定義はrevision 20260927）、googleapis/googleapis のChat APIの定義（chat_service.proto）のいずれにも replaceCards はありません
• Discovery文書は、10月20日の午前（UTC）には replaceCards のある revision 20261015 と、ない revision 20261013 が混ざって返りました。同じ日の照合時には、chat.googleapis.com と www.googleapis.com のどちらも revision 20261015 でした

認証情報を付けずに https://chat.googleapis.com/v1/spaces/AAAA/messages/BBBB:replaceCards へPOSTすると、401のエラーの詳細に "method": "google.chat.v1.ChatService.ReplaceMessageCards" とありました（存在しないメソッド名では404）。受け口はありますが、Developer Previewに参加していないプロジェクトから認証して呼んだときの応答、対象のエディション、クォータ（利用の上限）は確認していません。

Developer Previewに参加して試す場合は、テスト用のスペースで次の点を確かめてください。

1. リンクのプレビューで付けたカードに対して、replaceCards が成功するか。差し替えたカードが、ほかのメンバーの画面ですぐに変わるか
2. cardId を、最初に付けたカードと同じにする必要があるか
3. ユーザーがメッセージを編集・削除した後に呼ぶと、どんなエラーになるか

Chat APIの定義の変化は、ほかの記事でも追っています。本文をMarkdownで送る markupSyntax はChat APIでMarkdownのまま投稿する記事、案件ごとのスペースの自動作成はスペース作成の二重作成を防ぐ記事で整理しています。

まとめ

リンクのプレビューを出すChatアプリを運用しているなら、まず、カードを付けたメッセージの名前を保存しているかを確認してください。保存していなければ、replaceCards が一般提供になっても、過去に付けたカードは差し替えられません。replaceCards は10月20日時点でDeveloper Preview（先行提供）の段階です。本番のアプリに組み込むのは、リリースノートで一般提供が告知されてからにし、それまではDeveloper Previewに参加したうえで、テスト用のスペースで上の3点を確かめておくと安全です。

2026年10月20日に、Google Chat API のリファレンス（spaces.messages.replaceCards のページ）、リリースノート、リンクのプレビューのガイド、Developer Preview Programの案内、Discovery文書（chat.googleapis.com と www.googleapis.com、revision 20261013 と 20261015）、google-api-python-client 2.200.0・2.201.0の同梱定義とリポジトリのmainの定義、npmの googleapis 186.0.0 と @googleapis/chat 51.2.0の型定義、googleapis/googleapis の google/chat/v1/chat_service.proto・message.proto を直接取得して確認しました（資料調査）。認証情報を付けずに replaceCards のURLへ送った要求の応答（401、メソッド名 google.chat.v1.ChatService.ReplaceMessageCards）も確認しています。コード例は @googleapis/chat 51.2.0に対してTypeScriptの型チェックを通したものです。リファレンスでは replaceCards はDeveloper Previewの扱いで、一般提供の時期・対象のエディション・クォータは未確認です。認証したうえでのAPIの呼び出しと、Chatの画面での表示も確認していません。

Google Chatと社内のシステムをつなぐ仕組みづくりや、Chatアプリの設計は、グリームハブのIT・Google Workspace 無料相談で承っています。扱う情報やスペースの使い方によって構成が変わるため、お問い合わせからご相談ください。

参考資料

• Method: spaces.messages.replaceCards（Google Chat API リファレンス）
• Google Chat API release notes
• Developer Preview Program（Google Workspace）
• Google Chat API Discovery document（chat v1）
• Google Chat API Discovery document（www.googleapis.com, chat v1）
• Preview links（Google Chat）
• googleapis/googleapis — google/chat/v1/chat_service.proto
• npm registry — @googleapis/chat
• PyPI — google-api-python-client