アウトバウンドコール

1 回の API リクエストでアウトバウンド通話を発信できます。エージェント、発信元の番号、そして E.164 形式（例：+14155559876）の宛先番号を 1 件以上指定します。 from_number_id には、アカウント上の任意の電話番号を指定できます。エージェントへの割り当ては不要で、どのエージェントでもその番号から発信できます。

このエンドポイントはすべての番号を即座にダイヤルするため、エージェント通話の同時実行数上限を超える宛先はキューに入らず拒否されます。件数が多いリストにはバッチコールを使用してください。最大 5,000 件の宛先をキューに入れ、キャパシティが空き次第ダイヤルします。

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

curl -X POST "https://api.cartesia.ai/agents/calls" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "ringing_timeout_seconds": 30,
    "outbound_calls": [
      {
        "to_number": "+14155559876",
        "dynamic_variables": { "customer_name": "Jordan" }
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.cartesia.ai/agents/calls",
    headers={
        "X-API-Key": "YOUR_CARTESIA_API_KEY",
        "Cartesia-Version": "2026-08-14",
        "Content-Type": "application/json",
    },
    json={
        "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
        "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
        "ringing_timeout_seconds": 30,
        "outbound_calls": [
            {"to_number": "+14155559876", "dynamic_variables": {"customer_name": "Jordan"}}
        ],
    },
)
response.raise_for_status()
call = response.json()["calls"][0]
if "error" in call:
    print("Call could not start:", call["error"])
else:
    print(call["agent_call_id"])

Response

{
  "calls": [
    {
      "number": "+14155559876",
      "agent_call_id": "ac_3kF9mN2pQ8rT1vX6"
    }
  ]
}

リクエストが受け付けられると、API は 200 を返します。calls 配列には宛先ごとに 1 件ずつのエントリが同じ順序で含まれます。各エントリには agent_call_id または error のいずれかが入るため、レスポンスのステータスだけでなく、すべてのエントリを確認してください。通話を追跡するには、agent_call_id を Get Call で使用してください。 ringing_timeout_seconds は、各宛先で発信試行がタイムアウトするまでの呼び出し時間を 5〜80 秒の範囲で設定します。デフォルトは 60 です。マネージドエージェントをパーソナライズするには、outbound_calls[].dynamic_variables に { "customer_name": "Jordan" } のような値を設定します。例は動的変数を参照してください。

Cartesia の電話番号では、アウトバウンド通話は 1 秒あたり最大 1 件です。それを超えるリクエストはキューに入れられます。