Skip to main content

​
Conversational Calls

Anima supports three voice-call modes. Pick the mode based on who should drive the live conversation: Anima’s hosted loop, the realtime voice pipeline, or your own agent over WebSocket.

​
Modes

ModeHow to startWho drives the conversationBest for
REST hosted, Basic/PremiumPOST /v1/voice/calls with tier: "basic" or tier: "premium"Anima attaches a server-side conversation loop after dialing”Call me now” demos, scripted follow-up calls, quick production calls
REST realtimePOST /v1/voice/calls with tier: "realtime"The realtime pipeline drives STT, LLM, TTS, tools, and barge-inLow-latency calls with a custom per-call systemPrompt
WebSocket BYO agentVoice WebSocket / SDK connectionYour agent runtime accepts calls, streams events, and sends speech/control messagesCustom agents, complex routing, external memory, custom tool orchestration
All modes still use the same phone identity, call records, transcripts, guardrails, and plan caps.

​
REST hosted calls

Use REST when you want one HTTP request to start a call and let Anima handle the live response loop. 
curl -X POST https://api.useanima.sh/v1/voice/calls \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_...",
    "to": "+15551234567",
    "tier": "basic",
    "greeting": "Hi, this is my Anima agent. I am calling from my own number."
  }'
For basic and premium, Anima attaches the hosted conversation loop. The first spoken line comes from greeting. Deeper behavior comes from the agent configuration and the hosted voice loop.

​
Realtime calls

Use realtime when you want the low-latency realtime pipeline. This mode accepts an optional per-call systemPrompt. 
curl -X POST https://api.useanima.sh/v1/voice/calls \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_...",
    "to": "+15551234567",
    "tier": "realtime",
    "greeting": "Hi, I can help with your appointment.",
    "systemPrompt": "You are a concise scheduling assistant. Confirm the caller identity before discussing appointment details."
  }'
systemPrompt is for the realtime tier. Basic and Premium use the hosted conversation loop and agent configuration instead.

​
WebSocket-controlled calls

Use the Voice WebSocket when your own agent runtime needs full control over the call. 
const conn = anima.calls.connect({ agentId: "agt_..." });

conn.on("message", (message) => {
  if (message.type === "call.transcription") {
    console.log(message.data?.text);
  }
});

conn.createCall("+15551234567", {
  tier: "basic",
  greeting: "Hi, this is my Anima agent.",
});
The WebSocket path is the right choice when you need custom memory, custom tool routing, multi-agent handoff, or external application state during the live call.

​
What Anima handles

  • Number ownership and call placement
  • Voice pipeline selection
  • TCPA, RND, time-of-day, and plan-cap gates
  • Call lifecycle records
  • Transcripts and post-call artifacts
  • Webhooks for call lifecycle events

​
What your app still owns

  • The lawful basis and consent record for contacting the recipient
  • Agent behavior and escalation policy
  • Any business-specific data used during the call
  • Follow-up workflows after the call ends