目次
「返信忘れを自動で見つけたい」——チャットの未読を手がかりに通知を出す仕組みは、中小企業でも作りたくなる自動化です。
私たちも社内の返信忘れ検出をChatwork APIで作ろうとして、ある仕様に足をすくわれました。メッセージを取得すると、その時点で未読が消えるという挙動です。素朴に巡回スクリプトを回すと、人が画面を見る前にバッジが消え、本人が見落とします。自動化のつもりが、業務を壊す側に回るパターンです。
この記事では、何が起きたのか、どう設計し直したのか、そしてそこから引き出せる判断の基準を整理します。
この記事の結論
- メッセージ取得APIは、未読分を返すと同時に既読化する
- 巡回はforce=1で行い、unread_numを前後で突合する
- 減っていたらPUTで未読に戻す復旧経路を先に用意する
Chatwork APIで未読が消える原因
Chatwork APIのメッセージ取得には、取得範囲を指定するforceというパラメータがあります。
force=0の場合、返されるのは未読分です。ここまでは想定どおりなのですが、問題はその副作用で、返した時点でサーバー側が既読になります。つまり取得は「読むだけ」の操作ではなく、状態を変える操作でした。
これが定期実行と組み合わさると事故になります。5分おきに巡回するスクリプトを置いた瞬間、社内の未読はほぼすべて、人間より先にスクリプトが消していきます。担当者の画面にはバッジが立たない。返信忘れを防ぐために作ったものが、返信忘れを増やす——という笑えない結果になります。
| forceの指定 | 返るもの | 未読への影響 | 巡回での扱い |
|---|---|---|---|
| force=0 | 未読分 | 取得した時点で既読になる | 巡回には不向き |
| force=1 | 未読状態に依存せず取得 | 未読状態を前提にしない | 巡回の基本形 |
なお、API仕様は変わることがあるため、最新の条件は必ず公式ドキュメントで確認してください。
既読化させない巡回設計の対策
対策は単発の工夫ではなく、3点セットで組みます。
1. 取得はforce=1で行う
未読分だけを取りに行く設計をやめ、未読状態に依存しない取り方に変えます。どこまで処理したかは、未読フラグではなく自分たちの側（最後に処理したメッセージIDなど）で持ちます。状態管理を相手のサーバーに預けないのが基本です。
2. 走査の前後でunread_numを突合する
それでも、取得の副作用を完全に読み切れているとは限りません。そこで走査の前に各ルームのunread_num（未読件数）を控え、走査後にもう一度取得して比べます。減っていれば、こちらの処理が既読にしてしまった証拠です。
3. 減っていたらPUTで未読に戻す
差分を検知したら、未読に戻す操作（PUT）で自動復旧します。ここまで用意して初めて、「触っても元に戻せる」状態になります。
figureとしては単純ですが、この「前後で測って、ズレたら戻す」という形は、外部サービスを叩く自動化のほぼ全てに応用できます。
判断の軸：完全検証してから作るのではなく、元に戻せる形で作る
この件で本当に迷ったのは、実装方法ではありません。仕様の確証が取れないまま、本番のチャットを触っていいのかという点でした。
慎重にやるなら、検証用の環境を用意して全パターンを確かめてから本番に入る、という進め方になります。ただ中小企業の社内改善で、そこまでの検証コストを先に払うと、たいてい着手前に止まります。
そこで私たちが採った軸は、「事前に完全検証してから作る」ではなく、触るなら必ず元に戻せる形で作るでした。仕様がグレーでも、復旧経路を先に用意しておけば、間違ったときの被害は「一瞬未読が消えて、すぐ戻る」で収まります。安全に前へ進むためのコストとして、これは十分に安い。
言い換えると、確認すべきは「このAPIは安全か」ではなく、このAPIは副作用を持つか、持つなら戻せるかの2点です。この順で確認すれば、未知の仕様の前でも判断が止まりません。
設計そのものの落とし穴：未読数はトリガーとして弱い
もう一つ、技術以前の問題がありました。未読数を検出のトリガーにする設計自体が、運用に依存するという点です。
メッセージが届いたらすぐ開いて内容を確認し、返信は後回しにする——こういう読み方をする人には、そもそも未読が残りません。未読を見ている限り、その人の返信忘れは永遠に検出されないわけです。技術的にどれだけ正しく作っても、指標が現場の行動と合っていなければ、仕組みは発火しません。
ここから引ける教訓はシンプルです。検出の指標を決める前に、社内の実際の読み方を確認する。全員が同じ運用をしていない前提で、指標がどこまでカバーできるかを見積もってから作り始めます。
同じ轍を踏まないためのチェックポイント
外部サービスのAPIを使った自動化を始めるとき、着手前に確認するのはこの3つです。
| 確認すること | 見るポイント |
|---|---|
| 副作用の有無 | 取得系のAPIでも状態を変えないか |
| 復旧経路 | 変えてしまったとき、戻す手段があるか |
| 指標の妥当性 | その指標は全員の運用で発火するか |
技術の難易度より、この3点の方が成否を分けます。特に2つ目の復旧経路は、動くものができた後では作りづらくなるため、最初の設計に含めておくのが得策です。
よくある質問
Q. Chatwork APIでメッセージを取得すると未読が消えるのはなぜ？ メッセージ取得APIは未読分を返す動作のときに、返した時点でサーバー側が既読として扱うためです。定期巡回のスクリプトを回すと、本人が画面を見る前に未読バッジが消えてしまいます。
Q. 巡回スクリプトで既読にしないためにはどうすればいい？ 取得時のforceを1にして未読状態に依存しない取り方をし、走査の前後でunread_numを突合します。減っていた場合はPUTで未読に戻す復旧処理を用意しておけば、影響を残さず巡回できます。
Q. 未読数を返信忘れ検出のトリガーにするのは有効ですか？ 運用に依存します。届いたら即開いて既読にする人には未読が残らず、検出が発火しません。指標を決める前に、社内の実際の読み方が全員に当てはまるかを確認する必要があります。
まとめ
- Chatworkのメッセージ取得は、未読を返すと同時に既読化する副作用を持つ
- 対策はforce=1での取得、unread_numの前後突合、PUTでの未読復旧の3点セット
- 判断軸は「完全に検証してから作る」ではなく「元に戻せる形で作る」
- 未読数のような運用依存の指標は、トリガーとして発火しないことがある
RENOYでは、GASや各種APIを使った社内自動化を、こうした副作用と復旧設計まで含めて組み立てています。「作ってはみたが、かえって現場が混乱した」というご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。