チュートリアル August 12, 2026

メッセージングアカウントの復旧手順：Refresh・Reconnect・Start・再認証の使い分け

UnifyPort のメッセージングアカウントで受信が止まっても、最初から再ログインさせる必要はありません。まず認証状態と runtime_status を確認します。状態が不明・古いなら refresh、認証済みのまま接続だけが不調なら reconnect、停止済みなら start、認証状態または account.auth.required がユーザー操作を求めている場合だけ再認証します。

要点

status、認証状態、runtime_status は別々の状態です。
認証成功後、ランタイムは通常、自動で起動します。
POST /runtime/refresh は状態の同期であり、再起動ではありません。
POST /runtime/reconnect は現在の認証を維持したまま接続を再構築します。
Webhook は通知として使い、操作後はアカウント取得または refresh で整合を確認します。

3つの状態を分けて考える

アカウントライフサイクルでは、次の3層が定義されています。

status：ワークスペースが管理する業務上のオン・オフ設定。
認証状態：GET /v1/accounts/{account_id}/auth から取得し、pending_auth、awaiting_qr_scan、awaiting_code、awaiting_password、authorized、failed のいずれか。
runtime_status：実際の接続状態。unknown、starting、running、stopping、stopped、reconnecting、disconnected、error に正規化されます。

この区別は、LINE の QR ログインを運用する日本チームにも重要です。アカウントがまだ authorized なら、QR コードを再表示する前に接続状態を調べます。逆に認証が失効している場合は、reconnect を繰り返しても必要なユーザー操作は完了しません。

プラットフォーム障害や審査状態も疑われる場合は、先にWhatsApp アカウント審査中のインシデント対応チェックリストで、プラットフォーム、ポリシー、ランタイム、Webhook コンシューマーの問題を切り分けてください。

判断表：refresh、reconnect、start、再認証

観測した状態	最初の操作	理由
`runtime_status: unknown`	Refresh	プロバイダーの最新状態を同期してから変更を判断します。
`running` だが接続不調を確認済み	Reconnect	認証を残したままライブ接続を再構築します。
`disconnected` かつ認証は `authorized`	Reconnect 後に再確認	認証ではなくランタイムがオフラインです。
`stopped` でオンラインに戻す必要がある	Start	停止済みランタイムには明示的な起動が必要です。
`starting`、`stopping`、`reconnecting`	先に再確認	すでに操作が進行中です。
認証が `pending_auth`、`awaiting_*`、`failed`	対応する認証フローへ進む	ランタイム操作ではユーザー認証を完了できません。
`account.auth.required` を受信	`auth_payload` に従って再認証	既存セッションにユーザー操作が必要です。
`runtime_status: error`	Refresh とエラー情報の確認	すべてのエラーを同じ操作で処理しないためです。

Reconnect APIは、アカウント自体は有効でも接続が不健全な場合に使います。Start APIはランタイム制御であり、認証 API ではありません。

復旧シーケンスを実装する

1. アカウントと認証状態を両方読む

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0 \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0/auth \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

アカウントオブジェクトから runtime_status、認証リソースから独自の status と、存在する場合は auth_payload、last_error を取得します。ランタイム状態だけで認証状態を推測しないでください。

2. unknown なら先に refresh

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/refresh \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Refresh はプロバイダーの最新状態を同期し、正規化した runtime_status を返します。start、reconnect、認証操作の後にローカル状態を照合する用途にも使えます。

3. 認証が有効な場合だけ reconnect

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/reconnect \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

直後の結果が reconnecting でも、受信復旧の完了を意味しません。進行中として扱い、後で状態を照合します。

4. stopped なら start

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/start \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

認証成功時は通常、自動起動されます。したがって、毎回の start 前に再ログインを要求しないでください。

5. 認証の根拠がある場合だけ再認証

account.auth.required には auth_status、runtime_status と、プロバイダーや認証方式に応じた QR コード、URL、PIN、確認コードなどの auth_payload が含まれることがあります。必要な手順だけをアカウント所有者に提示し、セッション情報はログに残さないでください。

Webhook はシグナル、API 読み取りは照合

account.status.updated、account.started、account.auth.required、account.auth.succeeded、account.auth.failed を購読するか、subscribed_events: ["*"] を使います。公開ペイロードは標準イベント一覧で確認できます。

account.status.updated はプロバイダーから観測された変化を通知しますが、要求したすべての遷移で必ず発生するとは限りません。reconnect、start、認証操作の後は、アカウント取得または refresh で確認します。また、イベントを信頼する前に署名を検証してください。Webhook HMAC・リプレイ対策・再試行ガイドに raw body の署名契約があります。

認証状態と runtime_status を読む
認証にユーザー操作が必要なら、対応する認証フロー
それ以外で unknown なら refresh
それ以外で disconnected なら reconnect
それ以外で stopped なら start
操作中なら照合
running なら変更しない
その他は refresh し、エラー情報を付けて対応を上げる

制限と注意点

ランタイムが復旧しても、Webhook エンドポイント、キュー、データベース、後続処理が正常とは限りません。running なのにアプリへ届かない場合は、Webhook 配信とコンシューマーを別に調査します。

Reconnect は履歴の再配信も保証しません。UnifyPort にはメッセージ履歴を読む REST API や、欠落イベントの保証付き再送はありません。WhatsApp は起動・再接続後に限定的なベストエフォート履歴同期を行う場合がありますが、完全なアーカイブではありません。受信時に保存してください。

FAQ

`runtime_status: disconnected` なら QR コードを再スキャンしますか？

必ずしも必要ではありません。認証が authorized なら reconnect を選びます。認証状態または account.auth.required が要求した場合だけ、新しい認証フローを開始します。

refresh と reconnect の違いは何ですか？

Refresh は最新状態を読み取り正規化します。Reconnect は不調な接続を能動的に再構築します。

認証成功後は毎回 start が必要ですか？

通常は不要です。認証成功後は自動起動されるため、観測状態が必要性を示す場合だけ start します。

running なのにメッセージが届かない場合は？

Webhook の状態、署名検証、HTTP 応答、再試行、キュー処理、保存を確認します。接続の正常性とイベント処理の正常性は別です。

次のステップ

アカウントライフサイクルに沿って判断表を実装し、Refresh runtime stateを運用手順に追加してください。

公式情報源

以下の UnifyPort 公式ドキュメントを 2026年8月12日に確認しました。