API リファレンス

はじめに

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

WhatsApp メッセージアカウントを接続し、テキストを送信して Webhook で返信を受信します。電話番号によるペアリングを使用します。

はじめる

  1. 1

    API キーを用意する

    ワークスペースの API Key、WhatsApp アカウント、公開 HTTPS Webhook を準備します。API Key と署名シークレットはサーバーで保管し、次のリクエストでキーを確認します。

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

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

    最初に登録してください。認証の進行状況とリアルタイム受信メッセージは webhook で届き、取り逃した配信の再送は保証されません。["*"] は公開標準イベントをすべて購読します。WhatsApp HistorySync は限定的な直近の連続性に留まり、永続履歴ではありません。

    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",
  "status": "active",
  "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 アカウントを作成する

    選択した割り当て可能なリージョンにメッセージ用アカウントを作成します。WhatsApp の電話番号ペアリングでは auth_mode=code を指定し、provider_data.phone に数字のみの完全な国際電話番号を設定します。返された data.id を後続の account_id として保存してください。

    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": "<REGION>",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8600000000000" }
}'
    アカウント作成
  5. 5

    電話をペアリングする

    保存済みの電話番号を使い、POST /auth/start に {} を送信します。data.verify_code を表示し、利用者が電話の WhatsApp に入力します。/auth/code への送信は不要です。送信前に認証状態と接続状態を確認してください。

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

    送信できる状態を確認

    同じ account_id で /auth とアカウント情報を取得し、認証が authorized、runtime_status が running であることを確認します。認証待ちなら続行し、認証済みでオフラインなら実行状態を確認・更新します。

    curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth" \
  -H "X-Api-Key: <YOUR_API_KEY>"

curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>"
    認証ステータス取得
  7. 7

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

    作成時の account_id を使います。この WhatsApp 例では国際電話番号に @s.whatsapp.net を付けます。返信にはイベントの data.conversation.id を再利用します。他チャネルにこの形式を適用しないでください。

    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": "8600000000000@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'
    テキストメッセージ送信
  8. 8

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

    テスト受信者から返信します。受信側で署名を検証し、イベントを保存して受信確認を返します。通常のイベントはイベント ID で重複を除外し、順序の逆転に対応します。conversation.history は provider + account_id + conversation.id + messages[].id でメッセージを統合し、イベント ID だけでバッチ全体を捨てないでください。届かない場合は購読設定、受信 URL、配信応答を確認します。

    Webhook delivery & signature verification