バッチコール

1 回のリクエストで多数のアウトバウンド通話をキューに入れられます。バッチはすべての受信者を検証して保存し、その後 Cartesia が設定した同時実行数上限までバックグラウンドでダイヤルします。

Telephone Consumer Protection Act（TCPA）をはじめ、通話に適用される規制を遵守する責任はお客様にあります。Cartesia の Acceptable Use Policy をご覧ください。

受信者リストを指定してバッチを作成し、通話がダイヤルされる間の進捗を追跡します。通話が失敗した受信者を再試行したり、バッチをキャンセルしてキューに残っている通話を停止したりできます。

バッチの作成

エージェントと発信元の電話番号とともに、最大 5,000 件の受信者を送信します。すべてのフィールドは Create Call Batch を参照してください。通話をパーソナライズするには、受信者ごとに dynamic_variables を含めます。動的変数を参照してください。

curl -X POST "https://api.cartesia.ai/agents/calls/batches" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March outreach",
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "target_concurrency_limit": 10,
    "recipients": [
      { "to_number": "+14155559876", "dynamic_variables": { "customer_name": "Jordan" } },
      { "to_number": "+14155550101", "dynamic_variables": { "customer_name": "Alex" } }
    ]
  }'

import requests

headers = {
    "X-API-Key": "YOUR_CARTESIA_API_KEY",
    "Cartesia-Version": "2026-08-14",
    "Content-Type": "application/json",
}

payload = {
    "name": "March outreach",
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "target_concurrency_limit": 10,
    "recipients": [
        {"to_number": "+14155559876", "dynamic_variables": {"customer_name": "Jordan"}},
        {"to_number": "+14155550101", "dynamic_variables": {"customer_name": "Alex"}},
    ],
}

response = requests.post(
    "https://api.cartesia.ai/agents/calls/batches", headers=headers, json=payload
)
response.raise_for_status()
batch = response.json()
print(batch["id"])  # バッチの追跡やキャンセルのために保存する

Response

{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "pending",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 0,
  "total_calls_finished": 0,
  "retry_count": 0,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:00:00Z"
}

API は 201 を返し、バッチとそこから導出される進捗カウンターが含まれます。バッチの追跡やキャンセルのために id を保存してください。 target_concurrency_limit は、そのバッチで同時にダイヤルされる通話数の上限です。未指定の場合、デフォルトは組織のエージェント通話同時実行数上限の半分になり、他の通話のための余裕を残します。この上限を超える値を指定するとリクエストは拒否されます。バッチコールはエージェント通話の同時実行数上限に対してのみカウントされ、TTS や STT の上限にはカウントされません。各バッチは、組織で共有されるエージェント通話同時実行数上限に対して target_concurrency_limit 分を予約します。バッチの実行準備が整った時点で十分なキャパシティがない場合、バッチは pending のままとなり、実行中のバッチがキャパシティを解放し次第、古いバッチから順に自動的にダイヤルを開始します。バッチを後で実行するには、scheduled_at にタイムゾーンオフセット付きの RFC 3339 形式の時刻（例：2026-06-15T16:00:00Z）を設定してください。

進捗の追跡

Get Call Batch でバッチを取得すると、ステータスと受信者ごとの詳細を確認できます。

curl "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14"

import requests

headers = {
    "X-API-Key": "YOUR_CARTESIA_API_KEY",
    "Cartesia-Version": "2026-08-14",
}

response = requests.get(
    "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2",
    headers=headers,
)
response.raise_for_status()
batch = response.json()

print(batch["status"])
for recipient in batch["recipients"]:
    print(recipient["to_number"], recipient["status"])

Response

{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "in_progress",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 1,
  "total_calls_finished": 1,
  "retry_count": 0,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:05:00Z",
  "recipients": [
    {
      "id": "abcr_295cx2ZMPitmqQtBtWUxSR",
      "to_number": "+14155559876",
      "status": "completed",
      "agent_call_id": "ac_2u7rspBaHJ7bQ7TiR3mK2n",
      "end_reason": "agent_hangup",
      "created_at": "2026-03-01T12:00:00Z"
    },
    {
      "id": "abcr_TD5XMc9uNw6mJfhFbcvQTm",
      "to_number": "+14155550101",
      "status": "queued",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}

バッチの status はディスパッチの進捗を追跡し、各受信者の status はその受信者自身の通話を追跡します。各受信者の agent_call_id を使用して、Get Call で通話ごとの情報を取得できます。通話が発信される前に失敗した受信者には agent_call_id がありません。詳細はその error_message を確認してください。バッチの通話を直接取得するには、List Calls に batch_id を渡します。試行ごとに 1 件のエントリが返されるため、リトライされた受信者は複数回表示され、発信前に失敗した受信者は通話が存在しないためまったく表示されません。アカウント上のすべてのバッチを一覧表示するには（エージェントによるフィルタリングも可能）、List Call Batches を使用してください。

バッチの再試行

Retry Call Batch は、直近の試行が失敗した、または応答がなかった受信者を再度キューに入れます。通話が完了した受信者はそのまま変更されません。キャンセル済みのバッチは再試行できません。

curl -X POST "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/retry" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14"

import requests

headers = {
    "X-API-Key": "YOUR_CARTESIA_API_KEY",
    "Cartesia-Version": "2026-08-14",
}

response = requests.post(
    "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/retry",
    headers=headers,
)
response.raise_for_status()
batch = response.json()
print(batch["retry_count"])  # 失敗した受信者が再キューされるとインクリメントされる

レスポンスは、retry_count がインクリメントされたバッチです。

バッチのキャンセル

Cancel Call Batch は、バッチのキューに入っている通話のダイヤルを停止します。すでに進行中の通話は通常どおり終了します。

curl -X POST "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/cancel" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14"

import requests

headers = {
    "X-API-Key": "YOUR_CARTESIA_API_KEY",
    "Cartesia-Version": "2026-08-14",
}

response = requests.post(
    "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/cancel",
    headers=headers,
)
response.raise_for_status()
batch = response.json()
print(batch["status"])  # "cancelled"

レスポンスは、status が cancelled に設定されたバッチです。

はじめに

エージェント管理

ツール

オーディオ統合

テレフォニー

評価

移行

バッチの作成

進捗の追跡

バッチの再試行

バッチのキャンセル

​バッチの作成

​進捗の追跡

​バッチの再試行

​バッチのキャンセル

バッチの作成

進捗の追跡

バッチの再試行

バッチのキャンセル