API Reference

Account authorization

Start code authentication

Start authorization using the saved phone number. For WhatsApp, enter data.verify_code on the phone; do not submit it to /auth/code. For Telegram, submit the code received by the user to /auth/code and use /auth/password only if requested. awaiting_code does not mean authorization has succeeded.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/start

Supported channels

TelegramWhatsApp

Before you call

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

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 authentication route.

Request body

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

Understand the result

Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.

Response 200 · WhatsApp

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "verify_code": "ABCD-EFGH"
  }
}

Response 200 · Telegram

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "telegram",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "auth_payload": {
      "type": "code"
    }
  }
}

Response body

provider
string

Provider for this authorization action.

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

action
string

Requested authorization action: start_auth.

enum: start_auth

status
string

Current authorization status. awaiting_code is waiting for user action; authorized means authorization is complete.

auth_status
string

Standard authorization step status, usually the same as status.

verify_code
string

WhatsApp phone pairing code, directly under data. Enter it on the phone; do not submit it to /auth/code. No expiry timestamp is guaranteed.

auth_payload
object

Provider-specific authorization prompt. Telegram may return type=code; the code received by the user is not included.

type
string

Authorization prompt type; code for the Telegram verification-code step.

Responses

200

200 · WhatsApp

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.