アカウント

アカウント更新

アカウントを部分更新します。省略フィールドは保持、null は無効、空配列や空オブジェクトは該当フィールドをクリアします。identity 重複時は 409 duplicate_provider_account です。

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

呼び出す前に

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

パラメーターの取得元

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

リクエスト

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

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

Content-Type

string必須

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

パスパラメータ

account_id

string必須

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

リクエストボディ

name

string

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

provider

string

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

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol, 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 は無効です。秘匿値をログに出さないでください。Telegram アカウントの作成時、api_id と api_hash は任意です。独自のアプリ認証情報を指定しない場合は、プラットフォームのデフォルトのアプリ認証情報が使用されます。独自のアプリを使う場合は、同じ Telegram アプリの両方の認証情報を文字列で指定してください。

proxy

object

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

結果の確認

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

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "status": "active",
    "auth_mode": "code"
  }
}

レスポンスボディ

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

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

失敗時の対応

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

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