Chatwork APIは、ChatworkのチャットルームへのメッセージやタスクをHTTPで操作できる公式のAPIです。APIトークンを1つ発行すれば、curlの1行で業務システムからチャットへ通知を送れます。この記事では、v2のエンドポイントと回数制限の仕様、APIトークンとOAuth 2.0の使い分け、curlとPythonでのメッセージ送信、Webhookでメッセージを受け取って署名を検証する実装を、公式ドキュメントの記載に沿って手順で説明します。
まとめ:送信はAPIトークンとPOST1本、受信はWebhookの署名検証から組み立てる
Chatwork APIでメッセージを送るには、https://api.chatwork.com/v2/rooms/{room_id}/messages に、x-chatworktoken ヘッダーを付けてPOSTします。本文はフォーム形式の body パラメーターに入れます。
業務システムに組み込むときに先に決めるのは、回数制限への対処とトークンの管理です。API全体で5分あたり300回、メッセージとタスクの投稿はルームごとに10秒あたり10回までで、超えると429が返ります。一斉に通知を出す処理は、送信の間隔を空ける作りにします。
Chatworkからの受信にはWebhookを使います。再送が無く、10秒以内に応答しないと失敗になるため、署名を確かめたらすぐ200を返し、重い処理は後ろに回します。
Chatwork APIでできることと、v2のエンドポイント・認証・回数制限の仕様
実装に入る前に、URI、認証、回数制限の3点を公式ドキュメントで押さえます。ここを外すと、動いたあとで運用が止まります。
ベースURIのapi.chatwork.com/v2と主なエンドポイントで操作できる範囲
Chatwork APIのエンドポイント仕様によると、ベースURIは https://api.chatwork.com/v2 で、通信はHTTPSが必須です。バージョンが上がるとURIの v2 の部分が変わり、旧バージョンは一定の移行期間は維持されると書かれています。
操作の対象は、自分の情報、コンタクト、チャットルーム、メッセージ、タスク、ファイルです。業務システムの連携で使う頻度が高いのは次の4つです。
| やりたいこと | メソッドとパス |
|---|---|
| メッセージを投稿する | POST /rooms/{id}/messages |
| タスクを追加する | POST /rooms/{id}/tasks |
| 参加ルームの一覧を取る | GET /rooms |
| 未読数を確かめる | GET /my/status |
表の {id} にはチャットルームのIDが入ります。POSTとPUTのリクエストボディは application/x-www-form-urlencoded で送る決まりです。JSONで送ると受け付けられないので、ほかのAPIの書き方をそのまま流用しないよう注意してください。
APIトークンとOAuth 2.0の2つの認証方式と、業務システムでの使い分け
選べる認証方式は2通りです。1つはAPIトークンで、HTTPヘッダーの x-chatworktoken に入れて送ります。トークンに有効期限は無く、クエリ文字列ではなくヘッダーで送るよう公式に注意書きがあります。
もう1つはOAuth 2.0です。アクセストークンは authorization: Bearer で送り、有効期間は30分、リフレッシュトークンは14日(offline_access スコープを含めると無期限)です。PKCEに対応しており、code_challenge_method は S256 のみに対応しています。
使い分けは、誰の名前で投稿するかで決めます。システムからの通知を決まったアカウントで出すなら、通知専用のアカウントでAPIトークンを発行するのが手軽です。利用者それぞれのアカウントで投稿させるアプリを作るなら、OAuth 2.0を使い、必要なスコープ(投稿だけなら rooms.messages:write)に絞って許可をもらいます。
5分300回と1ルーム10秒10回の回数制限と、429エラーの返り方
回数制限は2段あります。API全体では5分あたり300回まで、メッセージとタスクの投稿はチャットルームごとに10秒あたり10回まで(2つの合算)です。超えるとHTTPステータス429が返り、ルーム単位の超過では Rate limit for message posting per room exceeded. というメッセージが付きます。公式は10秒ほど待ってからの再試行を案内しています。
残りの回数は、レスポンスヘッダーの x-ratelimit-limit、x-ratelimit-remaining、x-ratelimit-reset(制限が戻る時刻のUnix秒)で分かります。夜間バッチの結果を担当者ごとに何十通も送るような処理では、ルーム単位の10秒10回に先に当たります。1ルームに送る通知はまとめて1通にするのが、制限への一番確実な対策です。
APIトークンを発行し、curlでチャットルームへメッセージを送信する手順
ここからは、通知専用アカウントでトークンを発行し、curlで1通送るところまでを進めます。
サービス連携画面でのAPIトークン発行と、組織管理者への利用申請
公式のはじめかたによると、APIトークンはChatwork画面右上の利用者名をクリックし、メニューの「サービス連携」から左側メニューの「APIトークン」を選ぶと確認できます。パーソナルプラン以外では、APIを使うために組織管理者への申請が必要です。申請は、APIを使いたいアカウントでログインして行います。
トークンは、そのアカウントでできる操作をすべて実行できる鍵です。個人のアカウントで発行すると、退職や異動で通知が止まり、トークンの持ち主の権限で全ルームが読める状態も生まれます。業務システム用には通知専用のアカウントを作り、通知先のルームにだけ参加させます。
ルームIDを調べ、curlでメッセージ投稿のAPIを実行して返り値を確かめる
ルームIDは、ブラウザでチャットルームを開いたときのURLの #!rid に続く数字です。メッセージ投稿のAPIリファレンスでは、body が必須で1〜65535文字、self_unread は任意で、0(既定)なら自分から見て既読、1なら未読になります。
# 環境変数にトークンとルームIDを入れておく
export CHATWORK_API_TOKEN="発行したAPIトークン"
export ROOM_ID="123456789"
curl -i -X POST "https://api.chatwork.com/v2/rooms/${ROOM_ID}/messages" \
-H "x-chatworktoken: ${CHATWORK_API_TOKEN}" \
--data-urlencode "body=[info][title]受注登録[/title]受注番号 A-1024 が登録されました[/info]" \
-d "self_unread=0"
成功すると {"message_id": "1234"} の形で、投稿したメッセージのIDが返ります。-i を付けているのは、レスポンスヘッダーの x-ratelimit-remaining を見て、残りの回数を確かめるためです。本文には日本語や角かっこが入るので、-d ではなく --data-urlencode で送ると、エンコードの漏れで本文が崩れる事故を防げます。
To・info・title記法で業務通知のメッセージを読みやすく整える
本文には、Chatworkのメッセージ記法が使えます。業務通知でよく使うのは次の4つです。
[To:{account_id}]:指名した相手に通知が届く。名前を後ろに書くと読みやすい[info][title]件名[/title]本文[/info]:枠線で囲み、件名を付ける[rp aid={account_id} to={room_id}-{message_id}]:特定のメッセージへの返信にする[hr]:横線で内容を区切る
承認依頼のように担当者に必ず見てほしい通知は [To:] で指名し、日次の集計のように流し読みされる通知は [info] の枠で件名を立てます。全員宛ての通知を毎回Toで出すと、未読の通知が埋もれて肝心の依頼が読まれなくなります。
PythonでChatwork APIを呼び出し、業務システムの通知処理に組み込む
業務システムから送るときは、送信の関数を1つにまとめ、回数制限の再試行をその中に閉じ込めます。
標準ライブラリのurllibだけで書く送信関数と、429の再試行
次のコードは、Pythonの標準ライブラリだけでメッセージを投稿し、429が返ったら10秒待って最大3回まで送り直します。外部のパッケージを入れられないサーバーでもそのまま動きます。
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
API = "https://api.chatwork.com/v2"
TOKEN = os.environ["CHATWORK_API_TOKEN"]
def post_message(room_id: int, body: str, retries: int = 3) -> str:
"""チャットルームにメッセージを投稿し、message_id を返す"""
data = urllib.parse.urlencode({"body": body, "self_unread": 0}).encode()
req = urllib.request.Request(
f"{API}/rooms/{room_id}/messages",
data=data, # urllib が application/x-www-form-urlencoded で送る
headers={"x-chatworktoken": TOKEN},
method="POST",
)
for attempt in range(retries):
try:
with urllib.request.urlopen(req, timeout=10) as res:
return json.load(res)["message_id"]
except urllib.error.HTTPError as e:
# 429 は回数制限。ルーム単位の制限は10秒待てば解ける
if e.code == 429 and attempt < retries - 1:
time.sleep(10)
continue
raise
raise RuntimeError("再試行の上限に達しました")
if __name__ == "__main__":
mid = post_message(123456789, "[To:1234567]山田さん\n請求書の承認依頼が1件あります")
print(mid)
urllib.parse.urlencode でフォーム形式に変換し、data を渡すと、urllibがContent-Typeを application/x-www-form-urlencoded にして送ります。429以外の400番台(トークンの誤り、ルームへの未参加など)は再試行しても直らないので、例外としてそのまま上へ返し、ログに残します。
通知の送信元を業務システムに置くときのトークン管理と送信量の設計
トークンはソースコードに書かず、環境変数やクラウドのシークレット管理に置きます。上のコードが os.environ から読んでいるのはそのためです。トークンに期限が無いぶん、漏えいしたときの被害が続くので、担当者の交代時と年1回を目安に再発行の手順を決めておきます。
送信量の見積もりは、通知の発生源ごとに行う作業です。受注1件ごとに1通送る設計で、セールの日に1時間で500件の受注が入ると、5分あたり300回の上限に届きます。件数が多い通知は5分ごとにまとめて1通にする、送信をキューに積んで1件ずつ間隔を空けて送る、のどちらかを最初から組み込みます。複数のSaaSと業務システムをつなぐ通知の設計は、API開発・システム連携として請け負っている領域です。
Chatwork Webhookでメッセージを受け取り、署名を検証するサーバーの実装
Chatworkで書かれたメッセージを業務システムで受け取るには、Webhookを使います。Webhookの仕組み自体はWebhookの仕組みとAPIとの違いで説明しています。
API管理画面でのWebhookの登録手順と、3種類のイベントの使い分け
Chatwork Webhookの仕様によると、Webhook URLはAPI管理画面から設定し、1アカウントにつき5件まで登録できます。イベントは3種類です。
mention_to_me:自分宛てのメンションが付いたときmessage_created:指定したルームにメッセージが書かれたときmessage_updated:メッセージが編集されたとき
通知専用アカウントへの「Toで依頼」を受けて処理を動かすボットなら mention_to_me、特定のルームの書き込みをすべて記録する用途なら message_created を選びます。送られてくるJSONには、webhook_setting_id、webhook_event_type、webhook_event_time と、message_id・room_id・body などを持つ webhook_event が入ります。
Webhookの署名ヘッダーをHMAC-SHA256で計算してPythonで検証する
Webhookのリクエストには、ヘッダー x-chatworkwebhooksignature に署名が付きます。検証の手順は、Webhook編集画面に表示されるトークンをBase64デコードして鍵にし、リクエストボディの生の文字列からHMAC-SHA256のダイジェストを作り、それをBase64エンコードした値がヘッダーと一致するかを比べる、というものです。次はFlask 2.0以降で書いた受信側の例です。
import base64
import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
# Webhook 編集画面に表示されるトークン(Base64 文字列)
WEBHOOK_TOKEN = os.environ["CHATWORK_WEBHOOK_TOKEN"]
def verify(raw_body: bytes, signature: str) -> bool:
"""トークンを Base64 デコードした値を鍵に HMAC-SHA256 を計算して比べる"""
key = base64.b64decode(WEBHOOK_TOKEN)
digest = hmac.new(key, raw_body, hashlib.sha256).digest()
expected = base64.b64encode(digest).decode()
return hmac.compare_digest(expected, signature)
def enqueue(event: dict) -> None:
"""重い処理はジョブキューへ渡す(ここでは省略)"""
print(event["webhook_event_type"], event["webhook_event"]["message_id"])
@app.post("/chatwork/webhook")
def receive():
signature = request.headers.get("x-chatworkwebhooksignature", "")
if not verify(request.get_data(), signature):
abort(401)
enqueue(request.get_json())
return "", 200 # 10秒以内に200を返す
署名は、JSONを読み直した値ではなく request.get_data() の生のバイト列で計算します。読み直すと空白やキーの順番が変わり、正しいリクエストでも一致しなくなります。比較には hmac.compare_digest を使い、文字列の比較にかかる時間から署名を推測される余地を残しません。署名検証の考え方をほかのサービスと比べたい場合は、Webhookの受信側の署名検証と冪等性の実装が参考になります。
再送なし・10秒以内の応答・自動無効化を前提にした受信処理の作り方
公式の仕様には、運用で効いてくる制約が4つ書かれています。失敗しても再送されないこと、10秒以内に応答が必要なこと(値は変わる可能性あり)、レスポンスボディは2,048バイトまでであること、通知のエラー率が高いとWebhookの設定が自動で「無効」になり、利用者が手で有効に戻すまで止まることです。
このため、受信側は署名を確かめたらすぐ200を返し、AIでの要約や基幹システムへの登録のような時間のかかる処理はジョブキューに回します。再送が無いので、受信サーバーが止まっていた間のメッセージは届きません。取りこぼしが許されない用途では、定期的に GET /rooms/{room_id}/messages で直近のメッセージを取り、message_id で重複を除いて突き合わせる仕組みを併用します。
Chatwork APIを自社で実装するか、既製の連携ツールで済ますかの判断
Chatworkへの通知だけが目的なら、コードを書かずに済む場合も多くあります。判断の分かれ目は、通知の元になるデータがどこにあるかです。
既製の連携ツールやiPaaSで足りる条件と、自前の実装を見送る場面
次の条件にすべて当てはまるなら、自前の実装は見送り、各SaaSに用意されたChatwork連携やiPaaS(Zapier、Makeなど複数のサービスをつなぐクラウドの連携基盤)の設定で始めます。
- 通知の元になるのが、kintoneやGoogleフォームのように連携の部品がそろったSaaSである
- 通知は1件ずつで、件数が1日に数十件程度に収まる
- Chatworkからの返信を受けて業務システムを動かす必要がない
この範囲でAPIの送信関数やWebhookの受信サーバーを自前で持つのは過剰です。サーバーの保守、トークンの管理、障害時の調査を自社で抱えることになり、連携ツールの月額費用より高くつきます。
業務システムに組み込んで開発すべき条件と、外注時に決める要件
自社で実装するのは、通知の元が自社開発の業務システムや基幹システムにあり、連携ツールからデータに届かない場合です。Webhookで受けたメッセージから承認や登録を動かす双方向の連携、件数が多くて送信の間隔やまとめ方を制御したい通知も、実装の対象になります。
外注するときは、次の4点を要件に書いておきます。
- 投稿に使うアカウントと認証方式(通知専用アカウントのAPIトークンか、OAuth 2.0か)
- 通知の種類ごとの宛先ルーム、件数の見込み、まとめて送る単位
- 429とWebhookの受信失敗が起きたときの再試行と取りこぼしの補い方
- トークンの保管場所と、再発行の手順を誰が持つか
ほかのチャットツールへの通知も同じ業務システムから出すなら、Slack Incoming Webhookの実装手順やLINE WORKS Incoming Webhookの送信仕様と並べ、送信の関数を宛先ごとに差し替えられる形にしておくと、ツールの乗り換えにも耐えられます。
Chatwork APIの使い方と制限・Webhookについてよくある質問
Chatwork APIの導入でよく出る質問に、公式ドキュメントの記載をもとに答えます。
Chatwork APIは無料で使えますか?
参照した公式ドキュメント(はじめかた・エンドポイント仕様)にはAPIの利用料金の記載はなく、APIトークンを発行すれば使い始められます。ただし、パーソナルプラン以外のプランでは、APIを使うために組織管理者への申請が必要です。また、5分あたり300回、メッセージとタスクの投稿はルームごとに10秒あたり10回という回数制限があり、プランによる上限の違いは公式のエンドポイント仕様には書かれていません。
Chatwork APIのトークンはどこで発行しますか?
Chatwork画面右上の利用者名をクリックし、メニューの「サービス連携」を開いて、左側メニューの「APIトークン」を選ぶと確認できます。組織のアカウントでは、先に組織管理者へのAPI利用申請が要ります。トークンに有効期限は無く、そのアカウントの権限で操作できる鍵なので、業務システムで使うときは通知専用のアカウントで発行し、環境変数などに保管してください。
Chatwork APIでメッセージを送ると429エラーになるのはなぜですか?
回数制限を超えたためです。API全体では5分あたり300回、メッセージとタスクの投稿はルームごとに10秒あたり10回(合算)までで、どちらかを超えると429が返ります。ルーム単位の制限なら、再送できるまでの待ち時間は10秒ほどです。同じルームへの通知が続く処理では、複数の通知を1通にまとめるか、送信の間隔を空けて超えないようにします。
Chatwork APIでメンションや改行はどう書きますか?
メンションは本文の先頭に [To:{account_id}] を書き、後ろに相手の名前を添えます。相手のアカウントIDは、コンタクト一覧を取るAPIやWebhookの受信データで確かめられます。改行を反映させるには、本文の文字列に改行文字を入れてください。curlで送るときは --data-urlencode を使い、日本語や記号をエンコードして送ってください。
Chatwork Webhookが届かなくなったときは何を確認しますか?
まずAPI管理画面でWebhookの状態が「無効」になっていないかを見ます。通知のエラー率が高いと自動で無効になり、手で有効に戻すまで再開しません。受信サーバーが10秒以内に200を返しているか、レスポンスボディが2,048バイトを超えていないかも確かめます。失敗した通知は再送されないので、止まっていた間のメッセージはAPIで取り直します。
関連記事
- Webhookの作り方と実装方法|受信側の署名検証・冪等性と送信側の再送をNode.jsで解説:署名検証と冪等な受信処理の一般的な作り方
- Webhookとは?読み方・仕組み・APIとの違いを実際のHTTPリクエストで解説:Chatwork Webhookの前提になる仕組み
- Incoming Webhookとは?仕組みとSlack・Discordでの使い方を解説:URLだけで送れる通知方式との違い
- Slack Incoming Webhookの実装手順:URL発行・Block Kit整形・SDK送信と429対策:Slackへ同じ通知を出すときの実装
- LINE WORKS Incoming Webhookの設定手順とJSON送信仕様|5URL・120req/minの上限:LINE WORKSへの通知の送信仕様