> ## 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.

# Phone & Voice

> Provision phone numbers, send SMS, receive replies, and place voice calls from an AI agent identity.

# Phone & Voice

Give your AI agents real phone numbers for SMS and voice. The phone number belongs to the same agent identity as its email inbox, vault, addresses, and DID, so cross-channel workflows stay tied to one actor and one audit trail.

## Overview

Anima Phone lets you:

* Search for available US numbers by area code and capability
* Provision a dedicated number for an agent
* Send a real "text me now" SMS from that agent
* Receive inbound SMS through webhooks
* Place outbound voice calls with server-side TCPA, RND, and time-of-day gates
* Read call records and transcripts from the same identity surface

Use this page when you already have an `agent_id`. If you are starting from zero, create an agent first in the console or through the agent API, then come back here with the agent ID.

## 1. Search for a number

Find available numbers by area code and requested capability:

```python theme={null}
from anima import Anima

anima = Anima(api_key="ak_...")

numbers = anima.phones.search(
    country_code="US",
    area_code="415",
    capabilities=["sms", "voice"],
    limit=3,
)

for number in numbers["items"]:
    print(number["phoneNumber"], number.get("region"))
```

```ts theme={null}
import { Anima } from "@anima-labs/sdk";

const anima = new Anima({ apiKey: "ak_..." });

const numbers = await anima.phones.search({
  countryCode: "US",
  areaCode: "415",
  capabilities: ["sms", "voice"],
  limit: 3,
});

for (const number of numbers.items) {
  console.log(number.phoneNumber, number.region);
}
```

## 2. Provision a phone identity

Provisioning assigns one number to one agent. Request both `sms` and `voice` when you want the number to support the full demo path.

```python theme={null}
agent_id = "AGENT_ID"

phone = anima.phones.provision(
    agent_id=agent_id,
    country_code="US",
    area_code="415",
    capabilities=["sms", "voice"],
)

print(f"Provisioned: {phone.phone_number}")
```

```ts theme={null}
const agentId = "AGENT_ID";

const phone = await anima.phones.provision({
  agentId,
  countryCode: "US",
  areaCode: "415",
  capabilities: ["sms", "voice"],
});

console.log(`Provisioned: ${phone.phoneNumber}`);
```

## 3. Text your human now

Send the first SMS to a number you control. This is the fastest way to prove the agent has a real, reachable phone path.

```python theme={null}
message = anima.messages.send_sms(
    agent_id=agent_id,
    to="+15551234567",  # your phone number
    body="Hi - this is my Anima agent texting from its own number.",
)

print(f"SMS sent: {message.id} ({message.status})")
```

```ts theme={null}
const message = await anima.messages.sendSms({
  agentId,
  to: "+15551234567", // your phone number
  body: "Hi - this is my Anima agent texting from its own number.",
});

console.log(`SMS sent: ${message.id} (${message.status})`);
```

## 4. Receive replies

Inbound SMS is delivered as a message event. Subscribe to `message.received`, then inspect the message channel/payload to distinguish SMS from email.

```bash theme={null}
curl -X POST https://api.useanima.sh/v1/webhooks \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/anima",
    "events": ["message.received", "phone.provisioned", "call.ended"]
  }'
```

See [Webhooks](/webhooks) for signature verification and delivery retries.

## 5. Call your human now

Outbound voice calls run through the voice gate before dialing. Use a number you control for the first call, and only call recipients where you have the required consent.

```python theme={null}
call = anima.calls.create(
    agent_id=agent_id,
    to="+15551234567",  # your phone number
    tier="basic",
    greeting="Hi, this is my Anima agent. I am calling from my own phone number.",
)

print(f"Call started: {call.call_id} ({call.state})")
```

```ts theme={null}
const call = await anima.calls.create({
  agentId,
  to: "+15551234567", // your phone number
  tier: "basic",
  greeting: "Hi, this is my Anima agent. I am calling from my own phone number.",
});

console.log(`Call started: ${call.callId} (${call.state})`);
```

Voice behavior comes from the configured agent and selected tier. Use `greeting` for the first spoken line; use the agent configuration and voice pipeline for deeper call behavior.

## 6. Read the transcript

After the call ends, fetch the transcript:

```python theme={null}
transcript = anima.calls.get_transcript(call.call_id)

for segment in transcript.segments:
    print(f"{segment.speaker}: {segment.text}")
```

```ts theme={null}
const transcript = await anima.calls.getTranscript(call.callId);

for (const segment of transcript.segments) {
  console.log(`${segment.speaker}: ${segment.text}`);
}
```

For live call events and bidirectional voice control, see the [Voice WebSocket Protocol](/protocols/voice-websocket).

## Phone, mail, and vault together

The useful Anima pattern is not "a phone API in isolation." It is one agent identity using the right channel at each step:

1. Email the human or customer with context.
2. Text them if the workflow needs an immediate response.
3. Place a voice call when the situation needs synchronous confirmation.
4. Store credentials and tokens in the vault so the agent can act without exposing secrets to the LLM.
5. Tie the full workflow together in audit logs and webhooks through the same agent ID.

## Compliance guardrails

For US outbound calls, Anima enforces guardrails server-side before the dial reaches the telephony provider. These include TCPA consent attestation, Reassigned Numbers Database checks, time-of-day windows, and per-tier call caps. The platform can reject a call before dialing when those requirements are not satisfied.

For SMS, keep the same standard: do not send spam, honor opt-outs, and only contact recipients where you have a lawful basis to do so.

## List or release numbers

List numbers assigned to an agent:

```python theme={null}
numbers = anima.phones.list(agent_id=agent_id)
for phone in numbers:
    print(phone.phone_number, phone.ten_dlc_status)
```

```ts theme={null}
const numbers = await anima.phones.list({ agentId });
for (const phone of numbers.items) {
  console.log(phone.phoneNumber, phone.tenDlcStatus);
}
```

Release a number when the agent no longer needs it:

```python theme={null}
anima.phones.release(
    agent_id=agent_id,
    phone_number="+14155551234",
)
```

```ts theme={null}
await anima.phones.release({
  agentId,
  phoneNumber: "+14155551234",
});
```

## Next steps

* [Quickstart: Voice Calls](/quickstart-voice) - Run the SMS-then-call demo end to end
* [Conversational Calls](/conversational-calls) - Choose REST hosted, realtime, or WebSocket-controlled calls
* [Voice Catalog](/voice-catalog) - Browse voice tiers and options
* [Call Intelligence](/call-intelligence) - Summaries, scoring, transcripts, and recordings
* [Pricing & Limits](/pricing-and-limits) - Check included phone, SMS, and voice quotas
* [Vault](/vault) - Store credentials without exposing raw secrets to the model