Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Billing (₹)

Vocobase bills usage in Indian Rupees (₹). Your partner account holds a ₹ balance that is drawn down as your agents handle voice calls or chat sessions.
Unit change (May 2026): Vocobase previously used an abstract “credits” unit. The wallet now stores rupees directly. The JSON field name credits on billing endpoints is unchanged for backward compatibility, but the numeric value now represents ₹ instead of credits.

​
How voice calls are billed

Voice calls are billed in 15-second buckets at a per-tier per-minute rate. Any call duration > 0 is rounded up to the next 15-second bucket.

​
Per-tier default rates

TierDefault rate
VA 1₹3.60 / min
VA 1 Pro₹4.60 / min
The tier of a call is determined by the voice configuration assigned to the agent. Agents without a voice configuration assigned default to VA 1.

​
15-second rounding examples

Actual durationBilled durationBucket count
1 second15 seconds1
14 seconds15 seconds1
19 seconds30 seconds2
1 minute 1 sec1 minute 15 sec5

​
Cost examples (VA 1 default, ₹3.60/min)

Actual durationCost
1 second₹0.90
30 seconds₹1.80
60 seconds₹3.60
1 minute 1 sec₹4.50
5 minutes₹18.00
A 0-second / never-connected call bills ₹0.

​
Pricing overrides

Vocobase supports per-tier rate overrides at three scopes. At call end, the system walks the override chain and uses the first match for the call’s tier; if no override matches, the default rate applies. 
Agent → Project (Workspace) → Account → Default
This means you can negotiate a custom rate at the Account level, then optionally tighten or relax it for a specific Project or Agent. Overrides are managed by the Vocobase team — contact support@vocobase.com to set up custom pricing.

​
How chat is billed

Chat messages cost ₹0.035 per message. Each user message and each agent response is counted.
Chat messagesCost
10 messages (5 user + 5 bot)₹0.35
100 messages₹3.50
1,000 messages₹35.00

​
When ₹ is deducted

₹ is deducted automatically when a session ends — not when the call starts:
  1. A call is placed to the recipient
  2. The agent handles the conversation
  3. The call ends (hang up, timeout, or disconnect)
  4. Vocobase rounds the duration up to the next 15-second bucket, resolves the tier and rate, and deducts ₹
  5. A session.completed webhook fires with credits_used in the payload (note: value is in ₹)
{
  "event": "session.completed",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "duration_seconds": 127,
    "credits_used": 8.10,
    "...": "..."
  }
}
The credits_used value of 8.10 above means ₹8.10 — the call was 127s actual → 135s billed (9 buckets) at the VA 1 default ₹3.60/min = 135 × 3.60 / 60 = ₹8.10 after rounding (worked example; check your transaction for exact rate at session time, since overrides may apply).
If a call fails to connect (e.g., no answer, busy), no ₹ is deducted.

​
Initial balance

When your partner account is approved by the Vocobase team, an initial ₹ balance is assigned. The amount depends on your plan and agreement. There is no self-service top-up via the API. To add more balance, contact the Vocobase team at support@vocobase.com.

​
Checking your balance

​
Via the Dashboard

Log in to the Vocobase Dashboard and navigate to Settings. Your current ₹ balance is displayed on the account overview.

​
Via the API

​
Get current balance

curl -X GET https://api.vocobase.com/api/v2/billing/balance \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "credits": 1250.50
  }
}
The value 1250.50 represents ₹1,250.50.

​
Get transaction history

curl -X GET "https://api.vocobase.com/api/v2/billing/transactions?limit=20&type=usage" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
ParameterTypeDescription
limitintegerMax results (default 50, max 100)
offsetintegerPagination offset (default 0)
typestringFilter by type: purchase, usage, refund, bonus
start_datestringISO date, filter from this date
end_datestringISO date, filter until this date
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "t1234567-abcd-1234-abcd-123456789012",
        "amount": -8.55,
        "type": "usage",
        "description": "Voice session",
        "created_at": "2026-05-15T10:30:00.000Z"
      }
    ],
    "total": 156,
    "limit": 20,
    "offset": 0
  }
}
amount is in ₹. A USAGE row with amount: -8.55 means ₹8.55 was deducted. If you need a detailed billing audit for a call, contact Vocobase support with the session_id.

​
Get usage summary

curl -X GET "https://api.vocobase.com/api/v2/billing/usage-summary?start_date=2026-05-01&end_date=2026-05-31" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "period": {
      "start": "2026-05-01T00:00:00.000Z",
      "end": "2026-05-31T23:59:59.000Z"
    },
    "summary": {
      "usage": { "count": 142, "total": -1085.50 },
      "purchase": { "count": 1, "total": 5000.00 }
    },
    "totals": {
      "transaction_count": 143,
      "credits_added": 5000.00,
      "credits_used": 1085.50,
      "net_change": 3914.50
    }
  }
}
All numeric values are in ₹.

​
Insufficient balance

If your ₹ balance reaches zero, API calls that start new sessions will fail with: 
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient balance to start a new session"
  }
}
Calls that are already in progress will not be interrupted. However, you will not be able to start new calls until balance is replenished.

​
Monitoring usage

​
Webhook tracking

The most reliable way to track usage is through webhooks. Every session.completed event includes the credits_used field (₹). Accumulate these values in your system to track spend in real time.

​
Campaign-level tracking

If you use campaigns to batch outbound calls, the campaign status endpoint returns aggregate ₹ usage across all calls in the campaign.

​
Frequently asked questions

​
Can I set a per-agent or per-workspace pricing?

Yes. Pricing overrides can be set at Account, Project (Workspace), or Agent scope. Overrides are managed by the Vocobase team — contact support@vocobase.com.

​
What happens if balance runs out mid-call?

Active calls are never interrupted. The deduction happens after the call ends, so your balance may temporarily go negative. Contact the Vocobase team promptly to replenish balance if this occurs.

​
Can I get a refund for failed calls?

Calls that fail to connect (no answer, busy, provider error) do not consume ₹. If you believe ₹ was incorrectly deducted, contact support@vocobase.com with the session_id.

​
Why does the API return the field as credits if it’s now in ₹?

To keep partner integrations working without changes. The JSON field name credits (and credits_used, credits_added) is kept verbatim; only its numeric meaning shifted from abstract credits to Indian Rupees in May 2026.

​
Next steps

Webhook Payloads

See the full session.completed payload including credits_used.

Quick Start

Make your first API call and start using ₹.