アウトバウンドコール

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

コンプライアンス電話発信に関連する現地の規制（米国の 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": "call_3kF9mN2pQ8rT1vX6"
#     }
#   ]
# }

リクエストが受け付けられると、API は 200 を返します。calls 配列には outbound_calls の各エントリに対応する 1 件ずつのエントリが、同じ順序で含まれます。通話ごとの情報を取得するには、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 件を超えるリクエストはキューに入れられます。