アウトバウンドコール

エージェントは API リクエストでアウトバウンド通話を発信できます。E.164 形式（例：+14155559876）で対象の電話番号と、エージェント ID を指定して通話を開始します。

一度に多数の通話を発信しますか？このエンドポイントはすべての番号を即座に発信するため、エージェント通話の同時実行数上限を超える宛先はキューに入らず拒否されます。件数が多いリストには Batch Calling を使用してください。最大 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-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "ringing_timeout_seconds": 30,
    "outbound_calls": [
      {
        "to_number": "+14155559876",
        "metadata": {
          "customer_id": "cust_123"
        }
      }
    ]
  }'

# Response (200)
# {
#   "calls": [
#     {
#       "number": "+14155559876",
#       "agent_call_id": "ac_3kF9mN2pQ8rT1vX6"
#     }
#   ]
# }

import requests

url = "https://api.cartesia.ai/agents/calls"

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

payload = {
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "ringing_timeout_seconds": 30,
    "outbound_calls": [
        {
            "to_number": "+14155559876",
            "metadata": {
                "customer_id": "cust_123",
            },
        }
    ],
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
body = response.json()

# Response (200)
# {
#   "calls": [
#     {
#       "number": "+14155559876",
#       "agent_call_id": "ac_3kF9mN2pQ8rT1vX6",
#     }
#   ]
# }
print(body["calls"][0]["agent_call_id"])

# Trigger an outbound call from a deployed agent to a specific number
cartesia call <phone_number> <agent_id>

リクエストが受け付けられると、API は 200 を返します。calls 配列には outbound_calls の各エントリに対応する 1 件ずつのエントリが、同じ順序で含まれます。宛先ごとに個別に成功／失敗するため、各エントリには agent_call_id または error のいずれかが入ります。レスポンスのステータスだけでなく、すべてのエントリを確認してください。通話ごとの情報を取得するには、agent_call_id を Get Call に渡してください。 ringing_timeout_seconds（5〜80）を設定して、各宛先で通話がタイムアウトするまでの呼び出し時間を制御できます。省略するとデフォルトの 60 秒が使用されます。 metadata フィールドは JSON オブジェクトを受け付けます。このデータはエージェントコードのデプロイメントに渡され、通話ごとにエージェントの動作をカスタマイズするために利用できます。エージェントコード内では、get_agent 関数の call_request.metadata オブジェクト経由でメタデータにアクセスできます。

async def get_agent(env, call_request):
    if call_request.metadata:
        logger.info(f"Received metadata: {call_request.metadata}")
    # Use metadata to customize agent behavior
    return LlmAgent(...)

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