Outbound calls

Your backend can ask your agent to call someone: a lead who just filled in a form, a customer whose order is ready. You send one request with the number and anything the agent should know; the agent calls from your KugelAudio number and starts the conversation. During any phone call, the agent can also forward the caller to another number.

What you need

• An agent that is live, with a number bought through KugelAudio routed to it. The call comes from that number, and calling it back reaches the same agent. Numbers from your own Twilio or Telnyx account cannot place calls yet.
• An API key of your organization, from API keys in the dashboard. A key acts for the whole organization: it can place calls from any of its agents and read or cancel any of its calls, so keep it on your server.
• The agent's API ID: open the agent in the dashboard, go to Settings, and copy API ID.

Place a call

curl -X POST https://api.agents.eu.kugelaudio.com/v1/agents/projects/AGENT_API_ID/outbound-calls \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-L-1042" \
  -d '{
    "to": "+49 176 12345678",
    "metadata": { "lead": "L-1042", "name": "Erika", "topic": "Solar offer" },
    "maxAttempts": 2
  }'

The answer is 202 with the call:

{
  "callId": "6f1c2b9e-1d4a-4c3e-9a51-2f0d7b8e4a10",
  "source": "api",
  "state": "queued",
  "to": "+4917612345678",
  "from": "+15752600676",
  "attempts": 0,
  "maxAttempts": 2,
  "createdAt": "2026-10-25T14:00:00Z",
  "updatedAt": "2026-10-25T14:00:00Z"
}

Follow the call

curl https://api.agents.eu.kugelaudio.com/v1/agents/outbound-calls/CALL_ID \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

sessionId names the conversation once the call started: its transcript and recording are in Calls like any other call. Cancel a call that is still queued:

curl -X POST https://api.agents.eu.kugelaudio.com/v1/agents/outbound-calls/CALL_ID/cancel \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Idempotency-Key: cancel-CALL_ID"

Greet like a caller

The agent reads call.direction: outbound when it placed the call. Open with who is calling and why, and say that an AI speaks:

import { Text, useAgentInfo, useClient } from "curb";

export function OutboundOpening() {
  const direction = useAgentInfo((info) => info["call.direction"]);
  const { name, topic } = useClient();
  if (direction !== "outbound") return null;
  return (
    <Text>
      You are calling {name ?? "the customer"} about {topic ?? "their request"}. Open with:
      "Hallo, hier ist die digitale Assistenz von Example." Then explain why you call.
    </Text>
  );
}

Forward a call to a person

The agent can connect the caller to another number during any phone call, inbound or outbound. Give the model a tool, or call it from your own code:

import { Instruction, TransferCallTool, useTransferCall } from "curb";

export function Handover() {
  return (
    <>
      <Instruction>When the caller asks for a person, call transfer_call.</Instruction>
      <TransferCallTool to="+493012345678" ringTimeoutSeconds={25} />
    </>
  );
}

// Or in your own tool: const transfer = useTransferCall();
// const result = await transfer({ to: "+493098765432" });

The number rings from your number. When someone answers, the caller and that person talk, and the agent goes quiet; if the person hangs up while the caller is still there, the agent picks up again. When nobody answers or the line is busy, the agent stays on the call and learns the outcome (no_answer, busy, failed), so it can tell the caller. A refused transfer comes back as outcome: "refused" with a code:

The whole call, the forwarded part included, counts against your plan's agent minutes.

Limits

• One number gets at most three calls a day from your organization (and ten from all KugelAudio customers together); more answer 429 with callback_number_limited.
• At most 500 calls a day per number of yours (callback_endpoint_limited).
• Calls run within your plan's concurrent calls and are held against your balance like any call.
• You are responsible for having the callee's consent to be called.

Errors

Next steps

• Callback requests let website visitors ask for the call themselves.
• Phone numbers to buy the number your agent calls from.