アカウント

アカウント取得

単一アカウントの設定を返します。provider_data に含まれる機密のプロバイダ資格情報は、セキュリティのためこのレスポンスから意図的に除外されます。保留中の QR コードや認証コードなどの認証状態は、Authentication エンドポイントで別途公開されます。

GEThttps://api.unifyport.ai/v1/accounts/{account_id}

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

パスパラメータ

account_id

string必須

accounts ルートで使用される識別子。

リクエストボディ

このエンドポイントは JSON ボディを必要としません。

結果の確認

記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "running",
    "auth_mode": "qrcode",
    "capabilities": [
      "send_message",
      "receive_message"
    ],
    "metadata": {
      "env": "production"
    },
    "provider_account_ref": "provider-side-identifier",
    "provider_profile": {
      "id": "778899",
      "phone": "8600000000000",
      "username": "production_bot",
      "display_name": "Production Bot",
      "first_name": "Production",
      "last_name": "Bot",
      "avatar_url": "https://example.com/avatar.jpg",
      "bio": "Customer support"
    }
  }
}

レスポンスボディ

id

string

一意のアカウント識別子（acc_...）。アカウントスコープのルートで使用します。

name

string

人が読みやすいアカウント名。

provider

string

チャネルの識別子です。後続の呼び出しでは返された値をそのまま使ってください。この API の値は以下の enum を参照してください。

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

region

string

アカウントが割り当てられているプロバイダリージョン。

status

string

アカウントのライフサイクル状態（例: active）。

runtime_status

string

正規化されたランタイム状態。unknown、starting、running、stopping、stopped、reconnecting、disconnected、error のいずれか。

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

auth_mode

string

アカウントが使用する認証フロー: code、qrcode、または session。

capabilities[]

string[]

send_message や receive_message など、アカウントで有効化されている機能。

metadata

object

アカウントに保存された自分の環境ラベル。

provider_account_ref

string

自社システムとアカウントを紐付けるために付与できる、プロバイダ側の識別子。

proxy

object

設定されている場合に返されるアカウントの送信プロキシ設定。

provider_profile

object

display_name などプロバイダが報告するプロフィール。アカウントが認証される前は省略されます。

id

string

チャネル側アカウント識別子。WhatsApp は LID を返し、プロフィール同期前は省略されることがあります。

phone

string

空白、ハイフン、先頭の + を除去した正規化電話番号。

username

string

プロバイダが報告した username（存在する場合）。

display_name

string

アカウントの表示名。WhatsApp では BusinessName を優先し、なければ PushName にフォールバックして生成されます。

push_name

string

WhatsApp アカウントで現在設定されている PushName。他のプロバイダではこのフィールドの意味を定義しません。

business_name

string

WhatsApp BusinessName。プロバイダが返さない場合は省略されます。

first_name

string

プロバイダが報告した名（存在する場合）。

last_name

string

プロバイダが報告した姓（存在する場合）。

avatar_url

string

プロバイダが報告したアカウントのアバター URL。

bio

string

プロバイダが報告した自己紹介またはステータス文。

platform

string

WhatsApp がペアリング時に報告するログインプラットフォーム識別子。不透明な文字列として扱い、未知の値も受け入れてください。他のプロバイダではこのフィールドの意味を定義しません。device_platform とは別のフィールドです。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。