India — Primary Provider Webhook-based

Vobiz Setup Guide

Vobiz is the primary telephony provider for Indian numbers. KaiVox uses Vobiz via webhooks — no API key required for call handling. This guide shows exactly how to connect your Vobiz number to KaiVox.

How it works: When someone calls your Vobiz number, Vobiz sends a POST request to KaiVox (Answer URL). KaiVox responds with instructions for the AI to speak. The caller speaks back, Vobiz sends their speech to KaiVox (Input URL), and KaiVox responds with the AI's next message. When the call ends, Vobiz notifies KaiVox (Hangup URL) to log the call and run automations.

Your Webhook URLs

These URLs are unique to your account slug. Replace {slug} with your actual tenant slug shown on your dashboard.

Webhook	Method	URL
Answer URL	POST	`https://kaivoxai.com/api/vobiz/{slug}/answer`
Input URL	POST	`https://kaivoxai.com/api/vobiz/{slug}/input`
Hangup URL	POST	`https://kaivoxai.com/api/vobiz/{slug}/hangup`

Local development: Vobiz cannot reach http://kaivox-ai.test. Use ngrok to create a public tunnel, or test on the staging server (kaivox-test.omajestic.com).

Step-by-Step: Configure in Vobiz Dashboard

Log in to your Vobiz portal Visit your Vobiz dashboard and sign in with your credentials. Each business has their own Vobiz account with their own numbers.
Go to Phone Numbers / DID Management Find the section for managing your virtual numbers (DIDs). This is usually called "My Numbers", "DIDs", or "Phone Numbers".
Click your number to open settings Find the number you want to connect (e.g. +917971543252) and click on it to open its configuration.
Set the Answer URL Look for a field called "Answer URL", "Webhook URL", or "Call Handler URL". Paste:
```
https://kaivoxai.com/api/vobiz/your-slug/answer
```
Make sure the method is set to POST.
Set the Hangup URL Look for "Hangup URL" or "Status Callback". Paste:
```
https://kaivoxai.com/api/vobiz/your-slug/hangup
```
Save and test Save the settings. Call your number. The KaiVox AI should answer within 2–3 seconds.

What KaiVox Receives from Vobiz

When Vobiz sends a webhook, it includes these fields which KaiVox reads:

Field	Used For
`call_id` or `uuid`	Unique call identifier — used to track the conversation across all webhooks
`from` or `cli`	Caller's phone number — used to identify or create the customer in CRM
`to` or `did`	Your Vobiz number that was called
`speech_result` or `speech`	What the caller said (sent on Input URL webhook)
`duration` or `call_duration`	Call length in seconds (sent on Hangup URL webhook)

What KaiVox Returns to Vobiz

KaiVox responds with XML (similar to TwiML) that tells Vobiz what to say and do:

Example Response — AI Speaks and Listens

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather input="speech" action="https://kaivoxai.com/api/vobiz/{slug}/input"
            method="POST" timeout="5" speechTimeout="auto" language="en-IN">
        <Say>Hello! Welcome to Pragati Women's Hospital. How can I help you today?</Say>
    </Gather>
    <Say>I didn't hear anything. Please call back if you need help. Goodbye.</Say>
    <Hangup/>
</Response>

Call Flow Diagram

Caller dials +917971543252
        ↓
Vobiz receives call
        ↓
Vobiz POST → /api/vobiz/{slug}/answer
        ↓
KaiVox: finds tenant by slug, loads AI persona, greets caller
        ↓
Caller speaks
        ↓
Vobiz POST → /api/vobiz/{slug}/input  (with speech_result)
        ↓
KaiVox: sends to OpenAI GPT-4o → gets response → speaks back
        ↓
[Conversation continues...]
        ↓
Caller hangs up
        ↓
Vobiz POST → /api/vobiz/{slug}/hangup  (with duration)
        ↓
KaiVox: saves call log, runs sentiment analysis, triggers automations

Vobiz API Keys (Stored in DB — Not in .env)

Vobiz platform credentials are stored in Super Admin → Platform Settings (in the platform_settings DB table), not in .env. This supports multi-tenancy — each installation has one platform Vobiz account used for the DID marketplace, while per-call authentication uses per-tenant credentials.

Credential	Where Stored	Used For
Vobiz App ID	Super Admin → Platform Settings	DID marketplace: browse, purchase, release numbers
Vobiz API Key	Super Admin → Platform Settings	DID marketplace: browse, purchase, release numbers
`phone_numbers.provider_api_key`	DB per tenant number	Recording download auth (X-Auth-Token header) during live calls
Webhook `ParentAuthID`	Injected by Vobiz on every webhook	Recording download auth (X-Auth-ID header) during live calls
Webhook URLs	Configured in Vobiz portal per number	Receiving all voice call events

To configure: Go to Super Admin → Platform Settings → scroll to the Vobiz API Credentials section. If not configured, the DID marketplace will show mock/demo numbers.

Troubleshooting Vobiz

Problem	Cause	Fix
AI doesn't answer	Answer URL not set or wrong slug	Check URL in Vobiz dashboard matches your exact tenant slug
AI answers but doesn't respond	OpenAI API key missing or invalid	Check `OPENAI_API_KEY` in `.env`
Call ends after greeting	Input URL not set or unreachable	Set Input URL in Vobiz or check server is publicly accessible
Call log not saved	Hangup URL not set	Set Hangup URL in Vobiz dashboard
Works locally but not live	ngrok not running or wrong URL	Start ngrok and update Vobiz with the ngrok URL