アカウント

アカウント更新

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

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

対応チャネル

all

呼び出す前に

対象ワークスペースの 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 は無効です。TikTok の provider_data.enable_comment は Boolean のみでデフォルトは false。文字列、数値、null は 400 invalid_request です。オンライン中の変更には reconnect が必要で、start 成功は適用の証明ではありません。無効化しても待機中のイベントは取り消されません。Telegram の code、qrcode、session では api_id と api_hash は任意。独自の認証情報は同じアプリの文字列のペアで指定します。作成時に独自認証情報がない場合と、空でない設定への置換時に認証情報が省略された場合はプラットフォームのデフォルトを使用し、必要なデフォルトが利用できなければ失敗します。デフォルト変更は既存アカウントの認証情報を置換しません。秘密情報をログに出さないでください。

proxy

object

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

結果の確認

この API に記載された応答項目と HTTP 状態で結果を判断し、関連操作から次の手順を選びます。

レスポンス 200 OK

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

レスポンスボディ

provider_profile

object

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

id

string

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

device_id

integer

現在のセッションを識別できる場合に、WhatsApp アカウント詳細で任意に返されるログイン端末番号。再認証で変わる場合があり、恒久的な端末識別子ではありません。

minimum: 0 · maximum: 65535

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

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

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

レスポンス

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

502

Bad Gateway

プロバイダアダプタまたは上流サービスが操作を完了できませんでした。

失敗時の対応

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

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