アカウント

アカウント一覧

現在の Workspace のプロバイダアカウントを一覧表示します。アカウントの認証状態は Authentication エンドポイントで取得します。

GEThttps://api.unifyport.ai/v1/accounts

呼び出す前に

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

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

クエリパラメータ

limit

integer

1 ページあたりの最大アカウント数。1〜100 で、省略時は 20 です。無効な値や limit の重複指定は 400 invalid_request（numeric_code=10000）を返します。次ページでは値を変更できます。

minimum: 1 · maximum: 100

cursor

string

アカウント一覧の不透明なカーソル。省略または空文字列で最初のページを取得し、次ページでは前の応答の data.next_cursor をそのまま渡します。発行時の workspace でのみ有効です。無効な cursor、重複指定、別の workspace での使用は 400 invalid_request（numeric_code=10000）を返します。

リクエストボディ

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

結果の確認

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

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "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"
        }
      }
    ],
    "has_more": false
  }
}

レスポンスボディ

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 とは別のフィールドです。

has_more

boolean

アカウント一覧に次のページがあるかどうか。

next_cursor

string

アカウント一覧の次ページ用の不透明なカーソル。has_more=true の場合のみ返します。次ページでは cursor としてそのまま渡してください。最終ページでは省略されます。

レスポンス

200

200 OK

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

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

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 とワークスペースの有効性を確認します。