> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversational Calls

> Understand Anima's REST-hosted, realtime, and WebSocket-controlled voice-call modes.

# 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

| Mode                       | How to start                                                     | Who drives the conversation                                                         | Best for                                                                   |
| -------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| REST hosted, Basic/Premium | `POST /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 realtime              | `POST /v1/voice/calls` with `tier: "realtime"`                   | The realtime pipeline drives STT, LLM, TTS, tools, and barge-in                     | Low-latency calls with a custom per-call `systemPrompt`                    |
| WebSocket BYO agent        | Voice WebSocket / SDK connection                                 | Your agent runtime accepts calls, streams events, and sends speech/control messages | Custom 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.

```bash theme={null}
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`.

```bash theme={null}
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.

```ts theme={null}
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

## Related docs

* [Quickstart: Voice Calls](/quickstart-voice)
* [Voice WebSocket Protocol](/protocols/voice-websocket)
* [Call Intelligence](/call-intelligence)
* [Pricing & Limits](/pricing-and-limits)