Google Chat メッセージ

Incoming webhooks を使用して Google Chat スペースにメッセージを送信します。テキストメッセージ、リッチカード (cardsV2)、スレッド返信を生成します。

生成内容

• Google Chat フォーマット対応のテキストメッセージ
• ヘッダー、セクション、ウィジェット付きのリッチカードメッセージ (cardsV2)
• スレッド付き会話
• 再利用可能な webhook 送信ユーティリティ

ワークフロー

ステップ 1: Webhook URL を取得

Google Chat で:

1. スペースを開く > スペース名をクリック > Manage webhooks
2. webhook を作成 (名前を付け、必要に応じてアバター URL を追加)
3. webhook URL をコピー

URL を環境変数またはシークレットマネージャーに保存してください。ハードコーディングは避けてください。

ステップ 2: メッセージタイプを選択

用途	タイプ	複雑度
シンプルな通知	テキストメッセージ	低
構造化された情報 (ステータス、ダイジェスト)	カードメッセージ (cardsV2)	中
継続的な更新	スレッド返信	中
アクションボタン (URL を開く)	ボタン付きカード	中

ステップ 3: メッセージを送信

assets/webhook-sender.ts を使用して送信ユーティリティを利用してください。構造化されたカード構成には assets/card-builder.ts を使用してください。

テキストフォーマット

Google Chat は標準の Markdown を使用しません。

フォーマット	構文	例
太字	*text*	*important*
イタリック	_text_	_emphasis_
打消し線	~text~	~removed~
等幅フォント	`text`	`code`
コードブロック	```text```	複数行コード
リンク	<url|text>	<https://example.com|Click here>
ユーザーをメンション	<users/USER_ID>	<users/123456>
全員をメンション	<users/all>	<users/all>

非対応: **二重アスタリスク**、見出し (###)、ブロッククォート、テーブル、インライン画像。

テキストメッセージの例

await sendText(webhookUrl, '*Build Complete*\n\nBranch: `main`\nStatus: Passed\n<https://ci.example.com/123|View Build>');

cardsV2 構造

カードは cardsV2 フォーマットを使用します (従来のカードより推奨)。

const message = {
  cardsV2: [{
    cardId: 'unique-id',
    card: {
      header: {
        title: 'Card Title',
        subtitle: 'Optional subtitle',
        imageUrl: 'https://example.com/icon.png',
        imageType: 'CIRCLE'  // or 'SQUARE'
      },
      sections: [{
        header: 'Section Title',  // optional
        widgets: [
          // widgets go here
        ]
      }]
    }
  }]
};

ウィジェットリファレンス

cardsV2 セクション内で利用可能なすべてのウィジェットタイプ。

textParagraph

フォーマット済みテキストブロック。Google Chat フォーマット (*bold*, _italic_, <url|text>) に対応。

{
  textParagraph: {
    text: '*Status*: All systems operational\n_Last checked_: 5 minutes ago'
  }
}

decoratedText

ラベル付き値とオプションアイコン。キー値データに最も汎用的なウィジェット。

基本:

{
  decoratedText: {
    topLabel: 'Environment',
    text: 'Production',
    bottomLabel: 'Last deployed 2h ago'
  }
}

開始アイコン付き:

{
  decoratedText: {
    topLabel: 'Status',
    text: 'Healthy',
    startIcon: { knownIcon: 'STAR' }
  }
}

カスタムアイコン URL 付き:

{
  decoratedText: {
    topLabel: 'GitHub',
    text: 'PR #142 merged',
    startIcon: {
      iconUrl: 'https://github.githubassets.com/favicons/favicon.svg',
      altText: 'GitHub'
    }
  }
}

ボタン付き:

{
  decoratedText: {
    topLabel: 'Alert',
    text: 'CPU at 95%',
    button: {
      text: 'View',
      onClick: { openLink: { url: 'https://monitoring.example.com' } }
    }
  }
}

クリック可能 (ウィジェット全体):

{
  decoratedText: {
    text: 'View full report',
    wrapText: true,
    onClick: { openLink: { url: 'https://reports.example.com' } }
  }
}

テキストラップ付き:

{
  decoratedText: {
    topLabel: 'Description',
    text: 'This is a longer description that should wrap to multiple lines instead of being truncated',
    wrapText: true
  }
}

buttonList

1 つ以上のアクションボタン。ボタンは URL を開くか、アクションをトリガーします。

シングルボタン:

{
  buttonList: {
    buttons: [{
      text: 'Open Dashboard',
      onClick: { openLink: { url: 'https://dashboard.example.com' } }
    }]
  }
}

複数ボタン:

{
  buttonList: {
    buttons: [
      {
        text: 'Approve',
        onClick: { openLink: { url: 'https://app.example.com/approve/123' } },
        color: { red: 0, green: 0.5, blue: 0, alpha: 1 }
      },
      {
        text: 'Reject',
        onClick: { openLink: { url: 'https://app.example.com/reject/123' } }
      }
    ]
  }
}

アイコン付きボタン:

{
  buttonList: {
    buttons: [{
      text: 'View on GitHub',
      icon: { knownIcon: 'BOOKMARK' },
      onClick: { openLink: { url: 'https://github.com/org/repo/pull/42' } }
    }]
  }
}

image

スタンドアロン画像ウィジェット。

{
  image: {
    imageUrl: 'https://example.com/chart.png',
    altText: 'Monthly usage chart'
  }
}

divider

ウィジェット間の水平線区切り線。

{ divider: {} }

折りたたみ可能なセクション

セクションは折りたたみ可能で、最初の N 個のウィジェットのみが表示されます:

{
  header: 'Details',
  collapsible: true,
  uncollapsibleWidgetsCount: 2,  // 最初の 2 個を表示、残りを折りたたみ
  widgets: [
    { decoratedText: { topLabel: 'Status', text: 'Active' } },
    { decoratedText: { topLabel: 'Region', text: 'AU' } },
    // これらは最初は折りたたまれています
    { decoratedText: { topLabel: 'Instance', text: 'prod-01' } },
    { decoratedText: { topLabel: 'Memory', text: '2.1 GB' } },
    { decoratedText: { topLabel: 'CPU', text: '45%' } }
  ]
}

既知のアイコン

decoratedText とボタンウィジェットの knownIcon を介して利用可能なアイコン。

{ startIcon: { knownIcon: 'STAR' } }
// または
{ icon: { knownIcon: 'EMAIL' } }

アイコン名	用途
AIRPLANE	旅行、フライト
BOOKMARK	保存、参照、リンク
BUS	輸送、トランジット
CAR	運転、輸送
CLOCK	時間、期間、スケジュール
CONFIRMATION_NUMBER_ICON	チケット、予約
DESCRIPTION	ドキュメント、ファイル
DOLLAR	金銭、価格、コスト
EMAIL	メール、メッセージ
INVITE	招待
MAP_PIN	位置情報、住所
MEMBERSHIP	メンバー、ユーザー
MULTIPLE_PEOPLE	チーム、グループ
OFFER	取引、プロモーション
PERSON	個別ユーザー
PHONE	電話番号、通話
SHOPPING_CART	商取引、購入
STAR	評価、お気に入り、重要
STORE	ショップ、小売
TICKET	チケット、イベント
VIDEO_CAMERA	ビデオ、ミーティング

リストにないアイコンの場合、公開アクセス可能な画像 (正方形、理想的には 24x24 または 48x48 ピクセル) を使用して iconUrl を使用してください。

スレッド処理

threadKey を使用してメッセージをスレッドでまとめます:

// 最初のメッセージ — スレッドを作成
const response = await sendCard(webhookUrl, card, {
  threadKey: 'deploy-2026-02-16'
});

// スレッドに返信 — &messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD を追加
const threadUrl = `${webhookUrl}&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD`;
await sendCard(threadUrl, replyCard, {
  threadKey: 'deploy-2026-02-16'
});

threadKey はクライアントが割り当てた文字列です。関連メッセージには一貫したキーを使用してください (例: deploy-{date}、alert-{id})。

一般的なパターン

通知カード

import { buildCard, sendCard } from './assets/card-builder';
import { sendWebhook } from './assets/webhook-sender';

const card = buildCard({
  cardId: 'deploy-notification',
  title: 'Deployment Complete',
  subtitle: 'production - v2.1.0',
  imageUrl: 'https://example.com/your-icon.png',
  sections: [{
    widgets: [
      { decoratedText: { topLabel: 'Environment', text: 'Production' } },
      { decoratedText: { topLabel: 'Version', text: 'v2.1.0' } },
      { decoratedText: { topLabel: 'Status', text: '*Healthy*', startIcon: { knownIcon: 'STAR' } } },
      { buttonList: { buttons: [{ text: 'View Deployment', onClick: { openLink: { url: 'https://dash.example.com' } } }] } }
    ]
  }]
});

ダイジェストカード (週間サマリー)

const digest = buildCard({
  cardId: 'weekly-digest',
  title: 'Weekly Summary',
  subtitle: `${count} updates this week`,
  sections: [
    {
      header: 'Highlights',
      widgets: items.map(item => ({
        decoratedText: { text: item.title, bottomLabel: item.date }
      }))
    },
    {
      widgets: [{
        buttonList: {
          buttons: [{ text: 'View All', onClick: { openLink: { url: dashboardUrl } } }]
        }
      }]
    }
  ]
});

エラー防止

間違い	修正
テキストの **bold**	*bold* (シングルアスタリスク) を使用
[text](url) リンク	<url|text> フォーマットを使用
cardsV2 ラッパーなし	カードを { cardsV2: [{ cardId, card }] } でラップ
スレッド返信がスレッドでない	webhook URL に &messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD を追加
Webhook が 400 を返す	JSON 構造をチェック — 一般的な問題はトップレベルで text または cardsV2 が欠落している
カードが表示されない	sections に少なくとも 1 つのウィジェットがあることを確認

アセットファイル

ファイル	用途
assets/types.ts	cardsV2 の TypeScript 型定義
assets/card-builder.ts	カードメッセージを構築するユーティリティ
assets/webhook-sender.ts	エラーハンドリング付きで webhook に POST