業務システム

Chatwork APIの使い方:APIトークン発行からメッセージ送信・Webhook受信までの実装手順

AIチャットボット開発の応用分野

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点を要件に書いておきます。

  1. 投稿に使うアカウントと認証方式(通知専用アカウントのAPIトークンか、OAuth 2.0か)
  2. 通知の種類ごとの宛先ルーム、件数の見込み、まとめて送る単位
  3. 429とWebhookの受信失敗が起きたときの再試行と取りこぼしの補い方
  4. トークンの保管場所と、再発行の手順を誰が持つか

ほかのチャットツールへの通知も同じ業務システムから出すなら、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で取り直します。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.09 テックブログ teket不正アクセス:ログインできない理由と再開見通し、入場・退会・偽メールの確認【11月16日時点】

RELATED POSTS 関連記事

目次