テキストとカードの使い分け
テキストメッセージは手軽だが、項目が5つを超えたあたりから読みにくくなる。カードメッセージは 見出し・ラベル付きの値・区切り線・ボタン を部品として並べられるので、通知を「書式の決まった報告書」にできる。
テキスト(text) | カード(cardsV2) | |
|---|---|---|
| 向いている内容 | 一言の通知、会話的な連絡、メンション | 結果の報告(状態・件数・所要時間)、複数の項目、リンク先がある通知 |
| 書式 | Chat の記法(*太字* など) | HTML タグの一部(<b>、<font color> など) |
| ボタン | なし | リンクを開くボタンを置ける |
| 作る手間 | 少ない | JSON が長くなるので、関数で部品化する(この記事の後半) |
1つのメッセージに text と cardsV2 の両方を入れることもできる。メンションはテキスト側で行い、詳細はカードで見せる、という組み合わせが実務では使いやすい。
cardsV2 の構造
カードは「カード → セクション → ウィジェット」の3階層でできている。
図1: カードの見た目(左)と JSON の構造(右)
| 階層 | キー | 役割 |
|---|---|---|
| カードの配列 | cardsV2 | 1メッセージに複数のカードを並べられる。各要素に cardId(任意の識別子)と card を持つ |
| ヘッダー | card.header | title・subtitle・imageUrl(アイコン画像)。省略もできる |
| セクション | card.sections[] | 区切られたまとまり。header で小見出しを付けられる |
| ウィジェット | sections[].widgets[] | 実際に表示される部品(次の表) |
💡 古い cards ではなく cardsV2 を使う
ネット上の古い記事には "cards" というキーで書かれた例が残っているが、これは旧形式だ。新しく作るなら cardsV2 で書く。ウィジェットの名前や入れ子の形が違うので、古い例を混ぜて使うと 400 エラーになる。
最初のカードを送る
図1のカードを JSON で書くと次のようになる。PART 02 の post_message() にこの辞書を渡せば、そのまま送れる。
{
"fallbackText": "夜間バッチ:成功(12,480件)",
"cardsV2": [
{
"cardId": "batch-result",
"card": {
"header": {
"title": "夜間バッチ結果",
"subtitle": "2026-10-31 02:15 / prod"
},
"sections": [
{
"header": "サマリー",
"widgets": [
{
"decoratedText": {
"topLabel": "ステータス",
"text": "<font color=\"#16a34a\"><b>成功</b></font>",
"startIcon": { "knownIcon": "STAR" }
}
},
{
"decoratedText": {
"topLabel": "処理件数",
"text": "12,480 件(所要 6分12秒)",
"startIcon": { "knownIcon": "DESCRIPTION" }
}
},
{ "divider": {} },
{
"textParagraph": { "text": "警告 2 件はログを確認してください。" }
},
{
"buttonList": {
"buttons": [
{ "text": "ログを開く", "onClick": { "openLink": { "url": "https://example.com/jobs/nightly/logs" } } },
{ "text": "手順書", "onClick": { "openLink": { "url": "https://example.com/runbook/nightly" } } }
]
}
}
]
}
]
}
}
]
}curl -sS -X POST "$GCHAT_WEBHOOK_URL" \
-H 'Content-Type: application/json; charset=UTF-8' \
--data-binary @batch-card.jsonfallbackText は、カードを表示できない場面(スマートフォンの通知など)で代わりに使われる短い説明だ。省略もできるが、通知のプレビューで内容がわかる ように入れておくことをおすすめする。
よく使うウィジェット
通知用途で使うウィジェットは、ほぼ次の表で足りる。
| ウィジェット | 表示 | 主なフィールド |
|---|---|---|
decoratedText | ラベル付きの値。アイコンや右端のボタンも付けられる | topLabel・text・bottomLabel・startIcon・wrapText |
textParagraph | 文章のかたまり | text |
buttonList | 横に並んだボタン | buttons[].text・buttons[].onClick.openLink.url |
divider | 区切り線 | なし({}) |
image | 画像(グラフの PNG など) | imageUrl・altText |
columns | 2列のレイアウト | columnItems[].widgets |
値が長くて途中で切れる場合は、decoratedText に "wrapText": true を付けると折り返して表示される。項目が多いセクションは "collapsible": true と "uncollapsibleWidgetsCount": 3 を指定すると、最初の3つだけ見せて残りを「もっと見る」で開く形にできる。
アイコンは、knownIcon に組み込みの名前(STAR・DESCRIPTION・CLOCK・EMAIL・PERSON・MULTIPLE_PEOPLE・BOOKMARK など)を指定するのが手軽だ。Google の Material アイコンを使う場合は {"materialIcon": {"name": "check_circle"}} のように書く。
カード内で使える書式
カードの中のテキストは、テキストメッセージの記法ではなく HTML タグの一部 で装飾する。*太字* と書いてもカードの中では太字にならない。
| 表示 | タグ |
|---|---|
| 太字・斜体・下線・取り消し線 | <b>・<i>・<u>・<s> |
| 文字の色 | <font color="#dc2626">失敗</font> |
| リンク | <a href="https://...">表示文字</a> |
| 改行 | <br> |
JSON の文字列の中に HTML を書くので、属性の " は \" とエスケープする。Python で辞書から json= で送れば、エスケープは自動で行われる。
⚠️ 色だけで状態を伝えない
赤・緑の色分けは見やすいが、ダークテーマや色の見分けにくい人には伝わりにくい。「成功」「失敗」の文字も必ず入れ、色は補助として使う。
Python でカードを部品化する
カードの JSON は長いので、毎回手で書くとすぐ間違える。よく使う形を関数にしておき、通知ごとには中身だけを渡すようにする。
"""Google Chat の cardsV2 を組み立てる小さな部品集"""
from html import escape
STATUS_STYLE = {
"success": ("成功", "#16a34a"),
"warning": ("警告", "#d97706"),
"failure": ("失敗", "#dc2626"),
}
def kv(label: str, value: str, icon: str | None = None) -> dict:
"""ラベル付きの値(decoratedText)"""
w = {"topLabel": label, "text": escape(value), "wrapText": True}
if icon:
w["startIcon"] = {"knownIcon": icon}
return {"decoratedText": w}
def paragraph(text: str) -> dict:
return {"textParagraph": {"text": escape(text).replace("\n", "<br>")}}
def buttons(*links: tuple[str, str]) -> dict:
"""("表示文字", "URL") の組を受け取り、リンクを開くボタンを並べる"""
return {"buttonList": {"buttons": [
{"text": text, "onClick": {"openLink": {"url": url}}} for text, url in links
]}}
def status_card(title: str, subtitle: str, status: str, items: list[dict],
note: str | None = None, links: list[tuple[str, str]] | None = None,
card_id: str = "status") -> dict:
"""状態(success / warning / failure)付きの通知カードを、メッセージの辞書として返す"""
label, color = STATUS_STYLE[status]
widgets = [{"decoratedText": {
"topLabel": "ステータス",
"text": f'<font color="{color}"><b>{label}</b></font>',
}}]
widgets += items
if note:
widgets += [{"divider": {}}, paragraph(note)]
if links:
widgets.append(buttons(*links))
return {
"fallbackText": f"{title}:{label}",
"cardsV2": [{
"cardId": card_id,
"card": {
"header": {"title": title, "subtitle": subtitle},
"sections": [{"widgets": widgets}],
},
}],
}値に < や & が含まれるとカードの HTML として解釈されてしまうので、html.escape() を通している。ログの一部やファイルパスを載せるときに効いてくる。
使う側は、通知したい項目を並べるだけになる。
from datetime import datetime
from gchat_cards import kv, status_card
from gchat_webhook import post_message
msg = status_card(
title="夜間バッチ結果",
subtitle=f"{datetime.now():%Y-%m-%d %H:%M} / prod",
status="failure",
items=[
kv("ジョブ", "daily-aggregate", icon="DESCRIPTION"),
kv("終了コード", "2"),
kv("所要時間", "3分48秒", icon="CLOCK"),
],
note="入力ファイル s3://example-bucket/in/2026-10-31.csv が見つかりませんでした。",
links=[("ログを開く", "https://example.com/jobs/daily-aggregate/logs")],
)
# メンションはテキスト側で付ける(カードの中ではメンションできない)
msg["text"] = "<users/all> 夜間バッチが失敗しました"
post_message(msg, thread_key="batch-2026-10-31")カードの見た目を試行錯誤するときは、Google の Card Builder が便利だ。部品を画面上で並べるとプレビューと JSON が表示されるので、それを見ながら関数を調整すると早い。
Webhook のカードでできないこと
カードには、押すと Chat アプリ側の処理を呼び出すボタンや、入力欄・選択肢などのウィジェットもある。しかし Webhook は送信専用で、ユーザーの操作を受け取る仕組みがないため、次のものは使えない(あるいは置いても意味がない)。
- 押すと処理が動くボタン(
onClick.action)――「再実行」「承認」ボタンなど - 入力欄・チェックボックス・選択肢(
textInput・selectionInputなど) - 送ったカードの後からの書き換え(「実行中」→「完了」の更新)
Webhook で置けるボタンは リンクを開く(openLink)ものだけ と考えておくとよい。「再実行」をボタン1つで済ませたい場合は、再実行用の URL(ジョブ管理画面や、認証付きの API の画面)を openLink で開かせるのが現実的だ。メッセージの書き換えは、PART 05 の Chat API でできるようになる。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
400 Unknown name "..." | キー名の綴り違い、または旧形式(cards)の書き方が混ざっている。エラーに出たキー名を cardsV2 のリファレンスで確認する |
| 画像が表示されない | imageUrl がインターネットから見えない(社内サーバー、認証付きの S3 など)。公開されている HTTPS の URL が必要 |
カードの中で *太字* が効かない | カードは HTML タグで装飾する。<b>太字</b> と書く |
| カードの中でメンションできない | メンションはテキスト(text)側に書く |
| 値の一部が消える・崩れる | 値に含まれる <・& が HTML として解釈されている。html.escape() を通す |
✅ 次の記事では…
PART 04 では、ここまでの部品を「毎朝9時に送る」「アラームが鳴ったら送る」形に組み込む。Apps Script・Windows のタスクスケジューラ・AWS Lambda の3つの実行場所を扱う。