← API リファレンス
アカウントPOST

アカウント作成

プロバイダアカウントを作成します。auth_mode は必須で qrcode、code、session のいずれかです。電話番号が必要な組み合わせでは provider_data.phone を指定し、後続認証でも再利用します。

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

ヘッダー

X-Api-Key
string必須

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

Content-Type
string必須

JSON のリクエストボディを送る場合は application/json を使用します。

パスパラメータ

このエンドポイントにパスパラメータはありません。

リクエストボディ

name
string

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

provider
string必須

顧客向けプロバイダ識別子: telegram、whatsapp、line、twitter、zalo、tiktok。

enum: telegram, whatsapp, line, twitter, zalo, tiktok, x, x_client, twitter_client

region
string必須

割り当てに使用するプロバイダのリージョン。プロバイダのリージョン一覧 で allocatable: true と報告されたリージョンを選んでください。

minLength: 1

status
string

active や inactive などのアカウント業務状態。

runtime_status
string

プロバイダがアカウント設定からの変更に対応する場合に指定するランタイム状態。

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

auth_mode
string必須

アカウント作成時に必須: qrcode、code、または session。

enum: qrcode, code, session

capabilities[]
string[]

PATCH では省略で保持、[] でクリアします。null は無効です。

metadata
object

PATCH では省略で保持、{} でクリアします。null は無効です。

provider_account_ref
string

プロバイダ側のアカウント識別子。通常は認証後に設定されます。

provider_data
object

PATCH では省略で保持、{} でクリアします。null は無効です。秘匿値をログに出さないでください。

proxy
object

このアカウント用の任意の送信プロキシ設定。

レスポンスボディ

id
string

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

name
string

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

provider
string

telegram、whatsapp、line、twitter、zalo、tiktok などのプロバイダ識別子。

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

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

レスポンス

201
201 Created

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

400
Bad Request

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

401
Unauthorized

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

409
Conflict

要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。

500
Internal Server Error

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

503
Service Unavailable

必要なバックエンドサービスが一時的に利用できません。

リクエスト

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Telegram Production",
  "provider": "telegram",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": {},
  "metadata": {
    "env": "production"
  },
  "provider_account_ref": "provider-side-identifier"
}'

レスポンス

{
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": ["send_message", "receive_message"],
    "provider_account_ref": "provider-side-identifier"
  }
}