Contents
はじめに
このドキュメントは、2026 年時点で提供されている Chatwork API（最新版 v3） の利用申請からアクセストークン取得、Python での実装例までを網羅したハンドブックです。管理画面の UI が大幅に刷新されたことに伴い、従来の「サービス連携」メニュー名や手順が変わっています。本稿では公式情報（2026 年 3 月リリースノート）と照らし合わせた最新手順を示すとともに、セキュリティ上必須となる環境変数管理や CI/CD への組み込み方 も解説します。
※ 本記事の UI 表記・メニュー名称は執筆時点での公式情報を元にしていますが、将来的な変更がある場合は必ず Chatwork の開発者向けドキュメントをご確認ください。
1. API 利用申請とアクセストークン取得手順（2026 年 UI）
Chatwork の API を利用するには、まず管理者権限で 「API 管理」 メニューから申請を行い、承認後にトークンを発行します。新しい UI では従来の「サービス連携」→「API 設定」の流れが統合され、操作画面がシンプル化されています。
1‑1. API 利用申請までの大まかな流れ
以下は管理者が実際に行う手順です。各ステップの目的と注意点を簡潔にまとめています。
- Chatwork にログイン → 右上のユーザーアイコンをクリックしてメニューを開く。
- 「API 管理」（旧称：サービス連携） を選択し、左側サイドバーの 「利用申請」 タブへ遷移する。
- 目的・担当者情報など必須項目を入力し、 「申請を送信」 ボタンでリクエストを提出する。
ポイント：申請内容は社内承認フローに合わせて記入すると、管理者側の承認がスムーズです。
1‑2. 承認完了後のトークン発行手順
管理者が承認を行うと 「API 設定」 ページが利用可能になります。この画面からアクセストークンを生成し、必要に応じて有効期限や権限を設定します。
| 手順 | 操作内容 | 補足 |
|---|---|---|
| 1 | 「API 設定」 タブ（左サイドメニュー）をクリック | トークン管理一覧が表示されます |
| 2 | 「新規トークン生成」 ボタンを押す | トークン名と有効期限（最大 365 日）を入力 |
| 3 | 必要な権限にチェック → 「メッセージ送信」「部屋情報取得」など | 権限は最小化することがベストプラクティス |
| 4 | 「作成」 をクリックし、生成されたトークンをコピー | トークンは表示される一度だけです。必ず安全な場所へ保管 |
重要：取得したトークンはコードにハードコーディングせず、環境変数やシークレット管理ツールで扱うよう徹底してください。
2. 環境変数による機密情報の安全な管理
API 呼び出しに必須となる CHATWORK_TOKEN と CHATWORK_ROOM_ID は、平文でリポジトリに残すと情報漏洩リスクが高まります。ここでは .env ファイルと python‑dotenv を組み合わせた安全な管理手順を示します。
2‑1. .env ファイルの作成と git 管理からの除外
プロジェクトルートに .env を作成し、機密情報だけを書き込みます。.gitignore に追加して Git の追跡対象から外すことが必須です。
|
1 2 3 4 |
# .env - ここに機密情報を格納します CHATWORK_TOKEN=xxxxxxxxxxxxxxxxxxxxxx # 実際のトークンに置き換えてください CHATWORK_ROOM_ID=12345678 # 使用するルーム ID を入力 |
|
1 2 3 4 5 6 |
# .gitignore .env # 機密情報が含まれるため除外 __pycache__/ venv/ *.pyc |
ポイント：CI 環境ではリポジトリに
.envを置かず、GitHub Secrets などのシークレット機能で環境変数を注入します。
2‑2. python‑dotenv のインストールとロード方法
以下のコマンドでパッケージを追加し、アプリ起動時に自動的に .env を読み込むコード例です。
|
1 2 |
pip install "python-dotenv>=1.0" |
|
1 2 3 4 5 6 7 8 9 |
# config.py import os from dotenv import load_dotenv load_dotenv() # .env の内容を環境変数へ展開 CHATWORK_TOKEN = os.getenv("CHATWORK_TOKEN") CHATWORK_ROOM_ID = os.getenv("CHATWORK_ROOM_ID") |
3. room_id の取得と自動化手順
room_id は固定値ではなく、組織内で部屋が増減するたびに変わる可能性があります。API を利用して 動的に取得し、スクリプトから .env へ書き込む方法を紹介します。
3‑1. GET /rooms エンドポイントの概要
2026 年版 API（v3）では GET https://api.chatwork.com/v3/rooms が部屋一覧取得用エンドポイントです。必要なヘッダーは X-ChatWorkToken のみで、レスポンスは JSON 配列として返ります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
import os, requests, re def fetch_room_id(target_name: str) -> int: """指定した部屋名に一致する room_id を取得します。""" url = "https://api.chatwork.com/v3/rooms" headers = {"X-ChatWorkToken": os.getenv("CHATWORK_TOKEN")} resp = requests.get(url, headers=headers, timeout=5) resp.raise_for_status() rooms = resp.json() # [{ "room_id": "...", "name": "..." }, ...] for room in rooms: if re.fullmatch(target_name, room["name"]): return int(room["room_id"]) raise ValueError(f"Room '{target_name}' not found.") |
3‑2. .env への自動追記例
取得した room_id をスクリプトで .env に書き込むと、手作業のミスを防げます。python-dotenv の set_key 関数を利用します。
|
1 2 3 4 5 6 7 8 9 10 11 |
from dotenv import set_key, find_dotenv def update_env_room_id(room_name: str): room_id = fetch_room_id(room_name) env_path = find_dotenv() set_key(env_path, "CHATWORK_ROOM_ID", str(room_id)) print(f"room_id ({room_name}) を .env に書き込みました: {room_id}") if __name__ == "__main__": update_env_room_id("業務通知") |
4. Python（requests）でのメッセージ送信実装
ここでは 認証ヘッダー作成 → POST /rooms/{room_id}/messages のフローを、エラーハンドリングとロギングを交えて解説します。コードは再利用しやすい関数形式にしています。
4‑1. 認証ヘッダーの生成
X-ChatWorkToken ヘッダーだけで認証が完了します。トークン取得失敗時には例外を投げて早期終了させます。
|
1 2 3 4 5 6 7 8 9 10 11 |
import os, logging logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") def auth_headers() -> dict: token = os.getenv("CHATWORK_TOKEN") if not token: raise EnvironmentError("CHATWORK_TOKEN が設定されていません。") return {"X-ChatWorkToken": token} |
4‑2. メッセージ送信用関数（リトライ付き）
公式ドキュメントでは 429 Too Many Requests が返された場合は指数バックオフで再試行することが推奨されています。以下の実装は最大 3 回までリトライし、最終的に例外を上げます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
import time, json, requests def send_message(room_id: int, body: str, max_retry: int = 3) -> str: """Chatwork にメッセージを送信し、メッセージ ID を返します。""" url = f"https://api.chatwork.com/v3/rooms/{room_id}/messages" payload = {"body": body} for attempt in range(1, max_retry + 2): # 初回＋リトライ回数 try: resp = requests.post(url, headers=auth_headers(), data=payload, timeout=10) if resp.status_code == 429: # レートリミット超過 wait = 2 ** attempt logging.warning(f"Rate limit exceeded. Retry after {wait}s.") time.sleep(wait) continue resp.raise_for_status() except requests.RequestException as e: logging.error(f"Request failed (attempt {attempt}): {e}") if attempt > max_retry: raise time.sleep(2 ** attempt) # ネットワーク障害時のリトライ待機 else: data = resp.json() message_id = data.get("message_id") logging.info(f"Message sent successfully (ID: {message_id})") return str(message_id) raise RuntimeError("Failed to send message after retries.") |
4‑3. 使用例（環境変数から取得）
|
1 2 3 4 |
if __name__ == "__main__": room_id = int(os.getenv("CHATWORK_ROOM_ID")) send_message(room_id, "✅ バッチ処理が正常に完了しました。") |
5. トークン有効性の事前チェックとデバッグ手法
本番環境へデプロイする前に、トークンが正しく機能しているか を確認すると、後続エラーの切り分けが格段に楽になります。ここでは curl と Python の両方で実装例を示します。
5‑1. curl での簡易チェック
公式ドキュメントが提供する GET /my/status エンドポイントはトークンの状態確認に最適です。
|
1 2 3 |
curl -s -H "X-ChatWorkToken: ${CHATWORK_TOKEN}" \ https://api.chatwork.com/v3/my/status | jq . |
- 200 が返り
{"status":"ok"}が出ればトークンは有効。 - 401 系エラー（例：
{"errors":["Invalid token"]}）の場合は再取得が必要です。
5‑2. Python 関数での自動検証
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
def validate_token() -> bool: """トークンの有効性を API で確認し、結果を真偽値で返す。""" url = "https://api.chatwork.com/v3/my/status" try: resp = requests.get(url, headers=auth_headers(), timeout=5) data = resp.json() except Exception as e: logging.error(f"Token validation request failed: {e}") return False if resp.status_code == 200 and data.get("status") == "ok": logging.info("Chatwork token is valid.") return True logging.warning(f"Invalid token response ({resp.status_code}): {data}") return False |
CI パイプラインの最初のステップとしてこの関数を呼び出すと、デプロイ前にトークンエラーで失敗するリスクを排除できます。
6. CI/CD（GitHub Actions）への組み込み例
実務で頻繁に使われる「バッチ完了通知」や「エラーアラート」のフローを、GitHub Actions に統合したサンプルです。シークレットは GitHub の Settings > Secrets から登録し、ジョブ内で環境変数として注入します。
6‑1. ワークフローファイル（.github/workflows/chatwork_notify.yml）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
name: Chatwork 通知 on: push: branches: [ main ] jobs: notify: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: Set up Python 3.11 uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install dependencies run: | python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt # requests, python-dotenv など - name: Export secrets as environment variables run: | echo "CHATWORK_TOKEN=${{ secrets.CHATWORK_TOKEN }}" >> $GITHUB_ENV echo "CHATWORK_ROOM_ID=${{ secrets.CHATWORK_ROOM_ID }}" >> $GITHUB_ENV - name: Validate token (optional) env: CHATWORK_TOKEN: ${{ secrets.CHATWORK_TOKEN }} run: | source .venv/bin/activate python -c "import utils; exit(0) if utils.validate_token() else exit(1)" - name: Run notification script env: CHATWORK_TOKEN: ${{ secrets.CHATWORK_TOKEN }} CHATWORK_ROOM_ID: ${{ secrets.CHATWORK_ROOM_ID }} run: | source .venv/bin/activate python notify_demo.py # 例：成功・失敗を判定して send_message を呼び出す |
6‑2. notify_demo.py の概要
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# notify_demo.py import os, logging from utils import send_message logging.basicConfig(level=logging.INFO) def main(): room_id = int(os.getenv("CHATWORK_ROOM_ID")) try: # 本来はビジネスロジックを呼び出す result = "処理結果サンプル" send_message(room_id, f"✅ ジョブが正常に完了しました。\n結果: {result}") except Exception as e: logging.exception("ジョブ実行中にエラー発生") send_message(room_id, f"❌ ジョブで例外が発生しました。\n```\n{e}\n```") if __name__ == "__main__": main() |
7. 注意点とベストプラクティス
| 項目 | 推奨内容・根拠 |
|---|---|
| API バージョン | 2026 年時点では v3 が最新（公式リリースノート参照）。古い v2 エンドポイントは非推奨です。 |
| レートリミット | 公式ドキュメントは「IP ベースで 1 分間に最大 120 リクエスト」と記載していますが、実際の上限はプランやトークン種別で変動する可能性があります。必ず最新の Rate Limit ページを確認してください。 |
| 同時接続数 | 同一アクセストークンでの同時接続は 最大 5 本 が目安です（公式 FAQ）。過剰な並列呼び出しは 429 エラーにつながります。 |
| 権限最小化 | 必要最低限のスコープだけを付与し、不要な権限は削除します。 |
| トークン保管 | 本番環境ではシークレット管理サービス（AWS Secrets Manager、GitHub Secrets 等）を使用し、平文保存を避けます。 |
| エラーハンドリング | 4xx/5xx 系は必ず raise_for_status または JSON エラー解析でログに残す。リトライは指数バックオフで実装。 |
| テスト環境の切り分け | 開発・ステージング用に別トークンを取得し、本番と混同しないようにする。 |
8. まとめ
- API 利用申請 → トークン取得 は新 UI の「API 管理」から行い、公式ドキュメントの手順に沿って実施してください。
- 機密情報は
.envとシークレット管理で徹底的に保護 し、コードベースには絶対にハードコーディングしないことが基本です。 - Python（requests）＋python‑dotenv の組み合わせ で認証ヘッダー作成・メッセージ送信を実装すれば、エラーハンドリングやリトライロジックも簡単に追加できます。
- トークン有効性チェック を CI の最初のステップとして組み込むことで、本番デプロイ前に問題を早期検知できます。
- CI/CD（GitHub Actions）への統合例 とベストプラクティスを参考に、バッチ完了通知やエラーアラートを自動化しましょう。
本稿の手順とコードを自社プロジェクトへ取り入れれば、Chatwork への通知機能が 安全・堅牢・自動化 された形で運用できるようになります。ぜひ早速試してみてください。