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

Before you call

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

Complete the selected authorization flow and check runtime_status. Authorization and connection state are separate; HTTP success alone does not establish readiness.

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 runtime_status in the response. starting or reconnecting needs another state check. If auth_required is true, continue authorization; absence of this hint does not prove the account is online.

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, zalo, tiktok, whatsapp-protocol

action

string

Runtime action that was requested.

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.

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 and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.
provider_not_ready · 30009 · 409: Check authorization and runtime. Restore the connection and confirm the previous result before retrying.