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

# Phone & Voice Billing

> Understand phone number charges, per-minute voice rates, auto-renewal, grace periods, and billing records for voice features.

# Phone & Voice Billing

Voice is one of the most powerful features in thinnestAI. This page covers exactly how phone numbers and voice calls are billed so there are no surprises.

## Phone Number Charges

To make and receive voice calls, you need at least one phone number. There are two ways to get numbers:

1. **Buy from platform** — Purchase Vobiz Indian numbers directly through thinnestAI
2. **Import your own (BYOK)** — Bring numbers from Twilio, Vobiz, Exotel, Plivo, or Telnyx

### Vobiz Indian Numbers (Buy from Platform)

| Number Type       | Setup Fee | Monthly Rent        | First Month Total |
| ----------------- | --------- | ------------------- | ----------------- |
| Regular DID       | ₹100      | ₹590/mo (incl. GST) | ₹690              |
| Gujarat DID       | ₹100      | ₹708/mo (incl. GST) | ₹808              |
| 92/140/160 Series | ₹100      | ₹1,000/mo           | ₹1,100            |
| 1800 Toll-Free    | ₹100      | ₹1,500/mo           | ₹1,600            |

* **Setup fee** is one-time (first month only)
* **Renewals** are monthly at the rent rate (no setup fee)
* **Billing is INR-native** — no USD conversion
* Voice call charges: **₹0.50/min** (telephony usage)

### How Billing Works

1. When you **purchase a number**, the setup fee + first month's rent is charged immediately from your ₹ wallet balance.
2. Every **30 days**, the monthly rent is automatically deducted.
3. If your balance is insufficient, a grace period begins (see below).

### Purchasing a Number

1. Go to **Phone Numbers** in the dashboard.
2. Click **Buy Number → Vobiz Indian Numbers**.
3. Search by region or series.
4. Select a number and confirm — the first month total is deducted.

### Releasing a Number

Delete the number from your dashboard to stop future charges. The number is released back to Vobiz and cannot be recovered.

## BYOK Phone Numbers (Bring Your Own)

Import phone numbers from your own provider account at **zero monthly cost** from thinnestAI.

### How BYOK Billing Works

| Item               | Cost                                        |
| ------------------ | ------------------------------------------- |
| Monthly number fee | **₹0** (you pay your provider directly)     |
| AI agent minutes   | **₹1.50/min** platform fee + provider costs |
| SIP trunk setup    | Free                                        |

### BYOK vs Platform Numbers

| Feature          | Platform (Vobiz)          | BYOK (Any Provider)          |
| ---------------- | ------------------------- | ---------------------------- |
| Monthly charge   | ₹590-1,500/mo from wallet | ₹0 (pay provider)            |
| Agent minutes    | ₹1.50/min + provider      | ₹1.50/min + provider         |
| Auto-renewal     | Yes (monthly)             | N/A                          |
| Number ownership | Platform manages          | You manage                   |
| On delete        | Number released           | Number stays in your account |

### Supported BYOK Providers

| Provider   | Credentials Needed                            | Status |
| ---------- | --------------------------------------------- | ------ |
| **Twilio** | Account SID + Auth Token                      | Live   |
| **Vobiz**  | Auth ID + Auth Token                          | Live   |
| **Exotel** | API Key + API Token + Account SID + Subdomain | Beta   |
| **Plivo**  | Auth ID + Auth Token                          | Beta   |
| **Telnyx** | API Key                                       | Beta   |

To set up BYOK: **Phone Numbers → \[Provider Tab] → Enter credentials → Validate → Import**.

## Per-Minute Voice Call Rates

Voice calls are billed per minute of active call time, rounded up to the nearest 60-second pulse.

### Voice Call Cost Breakdown

Every voice call has two cost components:

| Component          | Rate      | Description                                                 |
| ------------------ | --------- | ----------------------------------------------------------- |
| **Platform fee**   | ₹1.50/min | thinnestAI infrastructure (LiveKit, SIP, bot orchestration) |
| **Provider costs** | Varies    | STT + TTS + LLM token costs (see below)                     |

### Provider Costs (on top of platform fee)

| Provider           | Type | Rate                            |
| ------------------ | ---- | ------------------------------- |
| Deepgram Nova-2    | STT  | \~\$0.0043/min                  |
| Sarvam Saarika     | STT  | ₹0.50/min (INR-native)          |
| Cartesia Sonic-3   | TTS  | \~\$0.01/1K chars               |
| Sarvam Bulbul      | TTS  | ₹0.10/1K chars (INR-native)     |
| GPT-OSS 20B (Groq) | LLM  | Free (ThinnestAI Stack)         |
| GPT-4o-mini        | LLM  | $0.15/1M input, $0.60/1M output |

**BYOK:** If you bring your own API keys for STT/TTS/LLM, provider costs are ₹0 — you pay the provider directly.

### What Counts as Call Time

| Event                   | Billed?              |
| ----------------------- | -------------------- |
| Ringing (before pickup) | No                   |
| Connected call          | Yes                  |
| On hold                 | Yes                  |
| Agent processing time   | Yes                  |
| Call recording          | No additional charge |

### Telephony Charges (SIP/PSTN)

Telephony charges depend on the phone provider:

| Provider             | Inbound          | Outbound         |
| -------------------- | ---------------- | ---------------- |
| **Vobiz (platform)** | ₹0.50/min        | ₹0.50/min        |
| **Twilio BYOK**      | You pay Twilio   | You pay Twilio   |
| **Other BYOK**       | You pay provider | You pay provider |

## Auto-Renewal for Phone Numbers

Phone numbers renew automatically each month. Here's how the process works:

### Renewal Flow

1. **7 days before renewal**: A reminder notification is sent (dashboard and email).
2. **On renewal date**: The monthly fee is deducted from your balance.
3. **Successful renewal**: Number remains active for another month.
4. **Insufficient balance**: Grace period begins (see below).

### Managing Auto-Renewal

You can view all your numbers and their renewal dates:

```bash theme={null}
curl https://api.thinnest.ai/voice/phone-numbers \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "numbers": [
    {
      "id": "pn_abc123",
      "number": "+14155551234",
      "type": "local",
      "monthly_cost": 1.50,
      "provisioned_at": "2026-01-15T00:00:00Z",
      "next_renewal": "2026-04-15T00:00:00Z",
      "status": "active"
    }
  ]
}
```

## Grace Period for Insufficient Funds

If your balance is too low to cover a phone number renewal, thinnestAI doesn't immediately release your number. Instead, a grace period applies.

### How the Grace Period Works

| Day             | What Happens                                                                   |
| --------------- | ------------------------------------------------------------------------------ |
| **Renewal day** | Renewal attempt fails. Number enters grace period. Warning notification sent.  |
| **Day 1-3**     | Number remains active. Daily retry of renewal charge.                          |
| **Day 4-7**     | Number remains active but inbound calls show a warning. Daily retry continues. |
| **Day 7**       | If still unpaid, the number is released and may be reassigned.                 |

### Avoiding Grace Period Issues

* **Enable auto-topup**: Automatically add funds when your balance is low.
* **Set spending alerts**: Get notified before your balance drops too low.
* **Monitor renewal dates**: Check **Settings > Phone Numbers** regularly.

If your number enters the grace period:

1. Add funds to your account immediately.
2. The next daily retry will succeed and the number stays active.
3. No additional penalty fees are charged.

## Billing Records and History

Every phone-related charge is recorded and accessible.

### Viewing Phone Billing Records

**From the Dashboard:**

Go to **Settings > Billing > Records** and filter by type "Voice" or "Phone Number".

**Via the API:**

```bash theme={null}
curl "https://api.thinnest.ai/billing/history/{user_id}?type=voice&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Record Types

| Type                     | Description                   |
| ------------------------ | ----------------------------- |
| `phone_number_provision` | Initial phone number purchase |
| `phone_number_renewal`   | Monthly renewal charge        |
| `voice_call_outbound`    | Outbound call charges         |
| `voice_call_inbound`     | Inbound call charges          |
| `voice_ai_processing`    | AI token usage during calls   |

### Example Billing Record

```json theme={null}
{
  "id": "bill_voice_123",
  "type": "voice_call_outbound",
  "phone_number": "+14155551234",
  "destination": "+14155559876",
  "duration_seconds": 185,
  "duration_billed_minutes": 4,
  "telephony_cost": 0.08,
  "ai_processing_cost": 0.12,
  "total_cost": 0.20,
  "timestamp": "2026-03-05T14:30:00Z",
  "call_id": "call_abc123"
}
```

### Monthly Statement

Download a monthly statement with all charges:

```bash theme={null}
curl "https://api.thinnest.ai/billing/statement?month=2026-03" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o statement-march-2026.pdf
```

## Cost Optimization Tips

* **Use shorter prompts**: Concise agent instructions reduce per-call AI costs.
* **Set call duration limits**: Prevent unexpectedly long calls.
* **Choose efficient models**: Faster models (like GPT-4o-mini) work well for voice and cost less.
* **Release unused numbers**: Don't pay for numbers you're not using.
* **Monitor call patterns**: Check which agents or campaigns generate the most call minutes.

## Next Steps

* [Billing Overview](/docs/billing) — General billing and token pricing.
* [Campaigns](/docs/campaigns) — Run voice outreach campaigns.
* [Deployment](/docs/deployment) — Self-host for custom voice infrastructure.