アカウント認可

コード認証を開始

保存済みの電話番号で認証を開始します。WhatsApp は data.verify_code を電話側で入力し、/auth/code には送信しません。Telegram は受信したコードを /auth/code に送信し、二段階認証が必要な場合のみ /auth/password を呼び出します。awaiting_code は認証完了ではありません。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/start

対応チャネル

TelegramWhatsApp

呼び出す前に

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

パラメーターの取得元

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

リクエスト

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/auth/start" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

Content-Type

string必須

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

パスパラメータ

account_id

string必須

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

リクエストボディ

このエンドポイントは空の JSON オブジェクトを受け取ります。リクエスト例どおり {} を送信してください。

結果の確認

今回の認証操作について status/auth_status と返された auth_payload を確認します。利用者の操作が必要ならチャネルガイドに従います。authorized は認証完了を意味し、送信前には runtime_status の確認も必要です。

レスポンス 200 · WhatsApp

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "verify_code": "ABCD-EFGH"
  }
}

レスポンス 200 · Telegram

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "telegram",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "auth_payload": {
      "type": "code"
    }
  }
}

レスポンスボディ

provider

string

この認証操作のチャネル。

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

action

string

要求した認証操作。値は start_auth です。

enum: start_auth

status

string

現在の認証状態。awaiting_code は操作待ち、authorized は認証完了です。

auth_status

string

現在の認証手順の標準状態。通常は status と同じです。

verify_code

string

WhatsApp 電話番号ペアリングコード。data 直下にあり、電話側で入力します。/auth/code への送信は不要で、有効期限の時刻は保証されません。

auth_payload

object

チャネル固有の認証案内。Telegram は type=code を返す場合がありますが、利用者が受信したコードは含みません。

type

string

認証案内の種類。Telegram の検証コード手順では code です。

レスポンス

200

200 · WhatsApp

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

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 とワークスペースの有効性を確認します。
account_already_authorized · 20016 · 409: 認可済みです。そのアカウントを使うか、新しい認可の前に現在の認可を解除してください。