Account connection

Refresh runtime state

Synchronizes the latest provider runtime state for an account. runtime_status takes one of the platform-standard values: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error. Provider-specific labels are normalised into this set before being returned.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/runtime/refresh

Supported channels

all

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Check the current authorization and runtime state, then choose the action for your goal. Start, stop, refresh and reconnect have different purposes; an offline account does not by itself mean authorization must be restarted.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

account_id

stringrequired

Identifier used in the runtime route.

Request body

This endpoint accepts an empty JSON object; send {} exactly as shown in the request example.

Understand the result

Read the refreshed runtime_status as the current connection state. A successful refresh does not mean the account is online; choose the next action from the returned state and any authorization hint.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "runtime_status": "running"
  }
}

Response body

account_id

string

Provider account this response refers to.

provider

string

Channel identifier. Use the API value unchanged in later calls; see the enum below for the values returned by this endpoint.

enum: telegram, whatsapp, line, twitter, facebook, zalo, tiktok, whatsapp-protocol

action

string

Action requested by this call.

enum: refresh_status, start, stop, reconnect

operation_status

string

Whether the runtime action was accepted or completed.

runtime_status

string

Normalized runtime state: one of unknown, starting, running, stopping, stopped, reconnecting, disconnected, or error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

runtime_error

string

Provider runtime error when the action could not complete.

auth_required

boolean

When true, continue the channel authorization flow. Returned only when the channel provides authorization material or a previously confirmed authorization flow is still in progress. Absence or false does not mean online; check runtime_status. A disconnected state alone does not imply authorization is required. Runtime routes omit code, qrcode, auth_payload and provider_data; use the channel authorization endpoints to obtain authorization material.

auth_status

string

Optional authorization status, such as pending, awaiting_qr_scan or passkey_required. Returned when authorization material or a confirmed in-progress flow is available. Follow the channel guide for the next step; query the authorization endpoint for complete status and payload, and runtime_status for connection state.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested resource was not found. Check error.code and the current operation.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status, error.code/numeric_code and the current state; keep request_id. Check the requested action and channel support. Continue authorization only when an explicit authorization hint requires it, and confirm the state before retrying. Error reference

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

Check the channel-specific fields and formats.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

unsupported_action · 30005 · 400

This account action is not recognized; use a documented action.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

Illustrative JSON; message varies with the actual cause · 400 · 30005

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}

invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_binding_not_found · 30006 · 409

The account has no active channel connection binding; check its status.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Illustrative JSON; message varies with the actual cause · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

provider_not_ready · 30009 · 409

The connection is not ready. Check authorization and runtime_status before retrying.

Illustrative JSON; message varies with the actual cause · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

provider_not_ready · 30014 · 409

The provider instance needed by this account is missing. This is a runtime availability problem, not proof that authorization expired.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 409 · 30014

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

provider_not_ready · 30015 · 409

The provider runtime is stopped. Confirm whether that is intentional before starting it; a stopped runtime does not itself mean logout.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 409 · 30015

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

run_runtime_action_failed · 20008 · 500

Change runtime state: the runtime action failed; this response alone does not establish the final connection state.

Illustrative JSON; message varies with the actual cause · 500 · 20008

{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20008",
    "message": "Failed to run runtime action"
  }
}

run_runtime_action_failed · 20020 · 500

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

When it occurs: Applies when the account is not found; the existing HTTP status and operation code are preserved, while numeric_code identifies the missing account.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

run_runtime_action_failed · 30010 · 500

The provider could not complete the operation. message can include the original cause after “Provider operation failed:”; the reason text varies and is not a stable program interface.

When it occurs: Applies when the channel supplies no more specific failure classification; the current operation’s error is preserved.

Channels: WhatsApp

Illustrative JSON; message varies with the actual cause · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

provider_adapter_not_found · 30004 · 502

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

Illustrative JSON; message varies with the actual cause · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

Example · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

provider_unavailable · 30010 · 502

The provider could not complete the operation. message can include the original cause after “Provider operation failed:”; the reason text varies and is not a stable program interface.

Channels: WhatsApp

Example · 502 · 30010

{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30020 · 502

A synchronous request using whatsapp-protocol identified an account login restriction with numeric_code=30020. This can affect session import, runtime, sending and contact queries while retaining the current operation’s HTTP status and code. Do not substitute the WhatsApp 20102 event contract for this channel.

What to do: Stop automatic sends and retries, and ask the user to inspect and resolve the restriction in the official WhatsApp app. Resume only after resolution and any required reauthorization. A previously running connection does not prove the restriction has cleared.

Channels: WhatsApp Protocol

Example · 502 · 30020

{
  "request_id": "req_example_account_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30020",
    "message": "Account login is restricted. Check the official WhatsApp app for details."
  }
}

provider_unavailable · 30021 · 502

The account was not connected to the messaging platform for this request. WhatsApp contact creation can return 500 / create_contact_failed / 30021. This does not prove logout or that the current runtime status is still disconnected; query the current status before choosing a recovery action.

What to do: Pause operations that require the connection. First call POST /v1/accounts/{account_id}/runtime/refresh, recover according to the latest state and confirm runtime_status=running before business requests. Confirm the previous write result before resending.

Channels: WhatsApp

Example · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}