通話

通話を作成beta

この機能はクローズドベータ版です。ワークスペースでの利用を希望する場合は、テクニカルサポートにお問い合わせください。

現在は WhatsApp の1対1音声・ビデオ通話のみ対応しています。非公開の使い捨て join_url を準備します。リンクを開き、Start call を押して発信します。

POSThttps://api.unifyport.ai/v1/calls

対応チャネル

呼び出す前に

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

ワークスペースの非公開ベータ利用資格を確認します。通話作成前に WhatsApp の認証を完了し、runtime_status=running を確認してください。相手には現在のアカウントに属する個人会話の conversation_id を使います。

ブラウザーから発信するにはマイクの許可が必要です。カメラの許可は任意です。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得
to.id · to.type: 現在のアカウントに属する相手の個人会話の conversation_id を、API が返した値のまま to.id に指定し、to.type=user にします。電話番号文字列で代用しないでください。会話の詳細

リクエスト

curl -X POST 'https://api.unifyport.ai/v1/calls' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

Content-Type

string必須

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

リクエストボディ

account_id

string必須

現在のワークスペースのアカウント ID。

pattern: ^acc_[A-Za-z0-9][A-Za-z0-9_-]*$

to

object必須

1 対 1 通話の相手。

id

string必須

現在のアカウントに属する対象会話の conversation_id を、API が返した値のまま指定してください。

minLength: 1

type

string必須

現在は user のみ対応。group/channel は未対応エラーになります。

enum: user, group, channel

media_type

string必須

voice は音声、video はビデオ対応通話。

enum: voice, video

結果の確認

201 と state=preparing は通話の準備完了を表し、発信はまだ行われていません。call_id を保存し、返された expires_at より前に非公開の join_url を開いて Start call を押します。通話状態または call.answered で接続を確認します。

注記

WhatsApp の1対1音声・ビデオ通話を準備します（media_type: voice/video）。to.id は conversation_id、to.type は user。電話番号文字列とグループ通話は非対応です。準備期間は作成から既定で2分です。実際の期限は返された expires_at を確認し、期限前に join_url を開いて Start call を押してください。接続後の通話時間は制限しません。マイクは必須、カメラは任意です。使い捨てリンクを公開しないでください。

レスポンス 201 · 201

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "direction": "outbound",
    "media_type": "video",
    "state": "preparing",
    "join_url": "https://calls.example.com/call/call_example#ticket=example-only",
    "expires_at": "2026-09-07T12:02:00Z"
  }
}

レスポンスボディ

call_id

string

通話 ID。切断にも使用します。

direction

string

通話の方向。

enum: outbound

media_type

string

voice は音声、video はビデオ対応通話。

enum: voice, video

state

string

現在の通話状態。

enum: preparing

join_url

string

有効期間が短い一度限りの HTTPS リンク。記録・公開しないでください。

format: uri

expires_at

string

準備の有効期限（RFC3339）。

format: date-time

レスポンス

201

201 · 201

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

リクエストは識別されましたが、この操作は許可されていません。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

409

Conflict

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

500

Internal Server Error

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

501

Not Implemented

選択したプロバイダはこの操作を実装していません。

502

Bad Gateway

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

503

Service Unavailable

必要なバックエンドサービスが一時的に利用できません。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。ベータ資格、アカウント、call_id を確認します。作成が競合した場合は現在の通話を取得し、作成や切断の再試行前に状態を確認してください。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
missing_api_key · 11000 · 401: X-Api-Key とワークスペースの有効性を確認します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。
account_not_found · 20020 · 404: account_id を確認し、アカウントが属するワークスペースの X-Api-Key を使います。このワークスペースにないアカウントには現在のキーでアクセスできません。
unsupported_by_provider · 30003 · 501: チャネル能力ガイドを確認し、対応するチャネルまたは操作を選びます。再送しても対応範囲は変わりません。
beta_feature_not_enabled · 41002 · 403: 技術サポートにワークスペースの非公開ベータ利用を申請します。再送やリクエスト内の is_beta の変更では利用資格は得られません。
call_already_active · 38000 · 409: 現在の通話を取得して call_id を確認します。終了を待つか切断してから新しい通話を作成します。