← API リファレンス
はじめに

クイックスタート：WhatsApp で最初のメッセージ

空のワークスペースから、WhatsApp メッセージの送信と最初の受信 webhook イベントまでを 6 ステップで進めます。各ステップから完全なエンドポイントリファレンスへリンクしています。

はじめる

  1. 1

    API キーを用意する

    UnifyPort は現在、限定されたお客様に提供しています — ワークスペースへのアクセスはチームまでお問い合わせください。以下のリクエストはすべて X-Api-Key ヘッダで認証します。

    curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: <YOUR_API_KEY>"
    現在の Workspace を取得
  2. 2

    Webhook エンドポイントを登録する

    最初にこれを行ってください：認証の進行状況とすべての受信メッセージは webhook イベントとしてのみ届き、取り逃したイベントは再送されません。["*"] で購読すると標準カタログ全体を受信できます。

    curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'
    Webhook エンドポイント作成
  3. 3

    利用可能なリージョンを確認する

    アカウントはリージョンに紐づき、すべてのプロバイダがどこでも稼働するわけではありません。まずプロバイダのリージョン一覧を取得し、allocatable: true のリージョンを選んでください — 割り当てできないリージョンでアカウントを作成すると 409 no_allocatable_server で失敗します。

    curl https://api.unifyport.ai/v1/providers/whatsapp/regions \
  -H "X-Api-Key: <YOUR_API_KEY>"
    プロバイダのリージョン一覧
  4. 4

    WhatsApp アカウントを作成する

    1 アカウント = 1 台の仮想デバイスです。前のステップで allocatable と確認したリージョンを使用してください。WhatsApp の電話番号ペアリングでは auth_mode=code を使い、provider_data.phone に E.164 純数字（+ なし）の電話番号を設定します — 電話番号はアカウントに保存され、次のステップで再利用されます。

    curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support",
  "provider": "whatsapp",
  "region": "global",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8613800138000" }
}'
    アカウント作成
  5. 5

    電話をペアリングする

    空のボディでフローを開始すると、保存済みの電話番号が再利用され、レスポンスの auth_payload に 8 桁の verify_code が含まれます。電話側で WhatsApp →「リンク済みデバイス」→「電話番号でリンク」を開き、約 3 分以内に入力してください。成功すると account.auth.succeeded、続いて account.started が webhook に届きます。ランタイムは自動で起動するため、/runtime/start の呼び出しは不要です。

    curl -X POST https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start \
  -H "X-Api-Key: <YOUR_API_KEY>"
    コード認証を開始
  6. 6

    最初のメッセージを送信する

    正規化された JSON を送るだけで、UnifyPort がプロバイダ向けに変換します。WhatsApp の宛先 id は <E.164>@s.whatsapp.net です。

    curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "<ACCOUNT_ID>",
  "to": { "id": "8613912345678@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'
    テキストメッセージ送信
  7. 7

    最初のイベントを受信する

    もう一方の電話から返信してみてください：数秒以内に message.received イベントが webhook エンドポイントに届きます。ここから先は、配信署名の検証と標準イベントカタログの処理に進みましょう。

    Webhook delivery & signature verification