Tutorial August 12, 2026

Messaging Account Runtime Recovery: Refresh, Reconnect, Start, or Reauthenticate?

When a UnifyPort messaging account stops receiving messages, do not begin with a new login. First read its authentication state and runtime_status. Refresh an unknown or stale state, reconnect an authorized account whose live connection is unhealthy, start a deliberately stopped runtime, and reauthenticate only when the authentication state or an account.auth.required event says user action is required.

Key takeaways

status, authentication state, and runtime_status describe three different things.
A successful authorization normally starts the runtime automatically.
POST /runtime/refresh observes and normalizes the latest provider state; it is not a restart.
POST /runtime/reconnect rebuilds an unhealthy live connection without replacing authentication.
Webhook state is useful, but requested transitions should be reconciled with an account read or runtime refresh.

The three states you must separate

The account lifecycle reference defines three independent state layers:

status is the business switch controlled by your workspace.
Authentication state comes from GET /v1/accounts/{account_id}/auth. It can be pending_auth, awaiting_qr_scan, awaiting_code, awaiting_password, authorized, or failed.
runtime_status is the live connection state exposed on the account object. Its normalized values are unknown, starting, running, stopping, stopped, reconnecting, disconnected, and error.

This separation prevents the most common wrong action: asking a user to scan a new QR code when the account is still authorized and only its connection needs attention. It also prevents repeatedly reconnecting a runtime when the provider has invalidated the session and authentication is genuinely required.

If you are diagnosing a platform incident rather than building lifecycle automation, use the broader WhatsApp account-under-review incident checklist first. It separates provider incidents, policy enforcement, runtime faults, and webhook consumer faults.

Decision table: refresh, reconnect, start, or reauthenticate

What you observe	First action	Why
`runtime_status: unknown`	Refresh	The platform has no fresh provider report. Synchronize state before changing it.
`runtime_status: running`, but the connection is demonstrably unhealthy	Reconnect	Rebuild the provider connection while preserving current authentication.
`runtime_status: disconnected` and auth is `authorized`	Reconnect, then reconcile	Authentication is intact; the live connection is offline.
`runtime_status: stopped` and the account should be online	Start	A stopped runtime needs an explicit start.
`starting`, `stopping`, or `reconnecting`	Reconcile before issuing another action	An operation is already in progress.
Auth is `pending_auth`, `awaiting_*`, or `failed`	Continue or restart the appropriate auth flow	Runtime controls cannot complete missing user authentication.
`account.auth.required` arrives	Reauthenticate using the material in `auth_payload`	The provider has invalidated the existing session.
`runtime_status: error`	Refresh, inspect the exposed error context, then choose reconnect or auth recovery	Do not assume every error has the same cause.

The reconnect endpoint is specifically for an account that is online at the account level but has an unhealthy runtime connection. The start endpoint is runtime control, not authentication. Keeping those meanings distinct makes recovery logic predictable across WhatsApp, Telegram, LINE, TikTok, Zalo, and X.

Implement the recovery sequence

1. Read both account and authentication state

Read the account object for runtime_status, then read the authentication resource for its status and any auth_payload or last_error. Do not infer authentication from runtime_status alone.

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"

2. Refresh before acting on an unknown state

POST /v1/accounts/{account_id}/runtime/refresh synchronizes the latest provider state and returns a normalized runtime_status.

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 '{}'

A refresh is also the right reconciliation step after a requested transition when your local state is uncertain. It does not replace your webhook consumer or message store.

3. Reconnect only when authentication remains valid

For an authorized account in disconnected, or one whose connection is known to be unhealthy despite a running state, call the documented reconnect action:

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 '{}'

The immediate result can report reconnecting. Treat that as an in-progress state, not proof that message delivery has resumed. Reconcile it before declaring recovery complete.

4. Start a stopped runtime

Use POST /runtime/start when the runtime is stopped and should be online. Authorization success normally starts the runtime automatically, so a fresh login should not be your routine precondition for calling 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 '{}'

5. Reauthenticate only on authentication evidence

An account.auth.required event can carry auth_status, runtime_status, and provider-dependent material such as a QR code, URL, PIN, or verification code in auth_payload. Present the required step to the account owner, then follow the matching authentication flow. Do not send session material to logs.

Use webhooks as signals, not the only source of truth

Subscribe to account.status.updated, account.started, account.auth.required, account.auth.succeeded, and account.auth.failed, or use subscribed_events: ["*"]. The standard event catalogue documents their public payloads.

account.status.updated reports provider-observed authentication or runtime changes, but it is not guaranteed for every requested transition. After a reconnect, start, or auth action, reconcile with GET /v1/accounts/{account_id} or runtime refresh. Verify every delivery before trusting it; the HMAC, replay-protection, and retry guide covers the signed raw-body contract.

A compact worker can apply this order:

read auth state + runtime_status
if authentication needs user action: run the matching auth flow
else if runtime_status is unknown: refresh
else if runtime_status is disconnected: reconnect
else if runtime_status is stopped: start
else if an operation is in progress: reconcile
else if runtime_status is running: leave it alone
else: refresh and escalate with error context

Limitations and trade-offs

Runtime recovery does not prove that your webhook endpoint, queue, database, or downstream automation is healthy. If the account is running but messages still do not reach the application, inspect webhook delivery and consumer processing separately.

A reconnect also does not guarantee historical replay. UnifyPort has no REST message-history read API or guaranteed replay. WhatsApp can emit limited best-effort history synchronization after bootstrap or reconnect, but it is not a complete archive. Store inbound events when they arrive.

FAQ

Does `runtime_status: disconnected` mean I must scan a new QR code?

No. Check authentication first. If auth remains authorized, reconnect the runtime. Start a new auth flow only when authentication state or account.auth.required requires it.

What is the difference between refresh and reconnect?

Refresh reads and normalizes the latest provider runtime state. Reconnect actively rebuilds an unhealthy provider connection.

Normally no. Successful authorization usually starts the runtime automatically. Call start only when the observed runtime state still requires it.

Can I trust `account.status.updated` as the final state?

Treat it as a signal. Reconcile requested transitions with the account resource or runtime refresh because the event is not guaranteed for every transition.

What should I check when the runtime is running but no message arrives?

Check webhook endpoint status, signature verification, acknowledgements, retries, queue processing, and storage. A running provider connection and a healthy event consumer are separate conditions.

Next step

Implement the decision table against the Account lifecycle guide, then keep the Refresh runtime state reference beside your operational runbook.

Sources

Official UnifyPort documentation, checked August 12, 2026: