Inbound Calls

Inbound agents answer incoming phone calls automatically. When someone calls your configured phone number, Vocobase routes the call to the assigned agent, which handles the conversation using its prompt, voice, and knowledge base.

How inbound calls work

Caller dials your number
        │
        ▼
Twilio receives the call
        │
        ▼
Twilio forwards to Vocobase
        │
        ▼
Vocobase routes to your inbound agent
        │
        ▼
Agent handles the conversation
        │
        ▼
Call ends → session.completed webhook fires

A caller dials your Twilio phone number
Twilio forwards the call to Vocobase using a TwiML webhook
Vocobase identifies the inbound agent associated with the phone number
The agent greets the caller and handles the conversation
When the call ends, a session.completed webhook is sent with the transcript, duration, and ₹ used

Prerequisites

An approved Vocobase partner account with an API key
One of the following providers configured in your Vocobase account:
- Twilio (Twilio Setup guide)
- Plivo (Plivo Setup guide)
- Vobiz (Vobiz Setup guide)
- Tata Smartflo (Tata Smartflo Setup guide)
A phone number with voice capabilities from your chosen provider

Inbound calling is supported with Twilio, Plivo, Vobiz, and Tata Smartflo. MCube inbound is not yet available. The flow below uses Twilio as the example; for Plivo, Vobiz, and Tata Smartflo, use the V2 phone-numbers API section at the bottom of this page to manage DIDs and agent assignment programmatically.

If you create telephony connections through the V2 API, use the returned connection_id when syncing DIDs or starting outbound calls. The same active DID can exist on multiple connections for outbound caller ID use, but only one active row can have inbound_enabled: true, which keeps inbound routing deterministic.

Set up inbound calling

Create an inbound agent

Create an agent with agent_type set to "inbound". This tells Vocobase that this agent should handle incoming calls rather than making outbound ones.

curl -X POST https://api.vocobase.com/api/v2/agent \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Support",
    "prompt": "You are a helpful customer support agent for Acme Corp. Greet the caller warmly, listen to their issue, and help resolve it. If you cannot resolve the issue, offer to transfer them to a human agent.",
    "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
    "agent_type": "inbound",
    "intro_message": "Thank you for calling Acme Corp. How can I help you today?"
  }'

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Customer Support",
    "prompt": "You are a helpful customer support agent for Acme Corp...",
    "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
    "language": "en",
    "agent_type": "inbound",
    "intro_message": "Thank you for calling Acme Corp. How can I help you today?",
    "enable_recording": false,
    "document_count": 0,
    "status": "active",
    "created_at": "2026-03-15T10:30:00.000Z",
    "updated_at": "2026-03-15T10:30:00.000Z"
  }
}

The intro_message is what the agent says immediately when answering the call. Keep it short and welcoming — the caller is waiting.

Configure your Twilio phone number

In the Twilio Console, navigate to Phone Numbers > Manage > Active Numbers and select the phone number you want to use for inbound calls.Under Voice Configuration, set the inbound webhook URL provided by Vocobase for your account:

Setting	Value
When a call comes in	Webhook
URL	Your Vocobase inbound webhook URL
HTTP Method	`POST`

Do not append your API key or any query parameters to the inbound webhook URL. Vocobase identifies your account from the telephony credentials you configured.

Link the agent to your phone number

After creating the inbound agent and configuring the Twilio webhook, Vocobase automatically routes incoming calls on your configured Twilio number to your inbound agent.If you have multiple inbound agents, the most recently created active inbound agent is used by default. Contact the Vocobase team if you need to route different phone numbers to different agents.

Test with a phone call

Call your Twilio phone number from any phone. You should hear your agent’s intro_message, and then you can have a conversation with it.After the call ends, check your webhook endpoint for the session.completed event:

{
  "event": "session.completed",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Customer Support",
    "duration_seconds": 95,
    "credits_used": 1.59,
    "transcript": [...],
    "call": {
      "call_id": "c1234567-abcd-1234-abcd-123456789012",
      "from_number": "+919876543210",
      "to_number": "+14155551234",
      "direction": "inbound",
      "status": "completed"
    }
  }
}

Notice the direction field is "inbound" in the webhook payload, making it easy to distinguish from outbound calls.

Inbound vs. outbound agents

Feature	Inbound	Outbound
`agent_type`	`"inbound"`	`"outbound"`
Who initiates	Caller dials your number	You call via API
Telephony trigger	Twilio webhook	`POST /calls/start`
`intro_message`	Spoken when agent answers	Spoken when callee picks up
Webhook `direction`	`"inbound"`	`"outbound"`
Billing	Same per-tier ₹/min, 15s buckets	Same per-tier ₹/min, 15s buckets

An agent’s type is set at creation and determines how it handles calls. You cannot use the same agent for both inbound and outbound calls. Create separate agents for each purpose.

Adding a knowledge base

Inbound agents benefit greatly from a knowledge base. Upload your FAQs, product documentation, and support articles so the agent can answer caller questions accurately.

# 1. Upload a document
curl -X POST https://api.vocobase.com/api/v2/documents/upload \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support FAQ.pdf", "file_size": 524288, "mime_type": "application/pdf"}'

# 2. Upload the file to the presigned URL (from step 1 response)

# 3. Confirm the upload
curl -X POST https://api.vocobase.com/api/v2/documents/{document_id}/confirm \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

# 4. Link to your inbound agent
curl -X POST https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["{document_id}"]}'

See the Knowledge Base guide for the full workflow.

Troubleshooting

Calls go to Twilio voicemail instead of the agent

Verify the webhook URL in Twilio matches the inbound webhook URL provided by Vocobase
Check that the HTTP method is POST
Ensure your Twilio credentials are configured in Vocobase (Twilio Setup)

Agent does not answer

Confirm you have an active inbound agent (agent_type: "inbound", status: "active")
Check that your ₹ balance is not zero
Review the Twilio Console error logs for any connection failures

Caller hears silence

Make sure the intro_message is set on your inbound agent
Verify the voice_id is valid — list available voices with GET /agent/voices

Webhook shows wrong direction

If direction shows "outbound" for an inbound call, ensure you created the agent with agent_type: "inbound", not "outbound"

Use the V2 phone-numbers API (Plivo + Vobiz + Tata Smartflo)

For Plivo, Vobiz, and Tata Smartflo, use the V2 phone-numbers endpoints to sync DIDs, list local inventory, and assign inbound agents. Plivo pulls inventory from the carrier, Vobiz accepts an explicit numbers array, and Tata Smartflo pulls DIDs from Smartflo GET /v1/my_number.

Tata Smartflo inbound DIDs must also be routed in the Smartflo panel to the Voice-Bot streaming app so Smartflo invokes Vocobase’s Dynamic Voice-Bot resolver for incoming calls.

API tester quickstart

Use this as a copy-paste runbook when testing the V2 inbound flow.

export BASE_URL="https://api.vocobase.com/api/v2"
export API_KEY="rg_live_..."
export PROVIDER="VOBIZ" # PLIVO, VOBIZ, or TATA_SMARTFLO
export CONNECTION_PROVIDER="vobiz" # plivo, vobiz, or tata_smartflo
export CONNECTION_ID="9b7f1c44-c87f-4f0c-9124-3c802a9c1a20" # optional when only one active connection exists
export DID="+918065480085"
export AGENT_ID="00000000-0000-0000-0000-000000000000"

Confirm the partner is active and the carrier is configured:

curl -sS "$BASE_URL/config" \
  -H "Authorization: Bearer $API_KEY"

Expected:

success is true
data.status is active
data.telephony.vobiz.configured is true for Vobiz, data.telephony.plivo.configured is true for Plivo, or data.telephony.tata_smartflo.configured is true for Tata Smartflo
the provider appears in data.allowed_telephony_providers

If the provider is not configured, configure it first. For new multi-connection BYOP builds, prefer POST /api/v2/telephony/connections and save the returned connection_id; the older config endpoints update the default connection.

# Vobiz
curl -X PUT "$BASE_URL/config/telephony/vobiz" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_id": "MA_XXXXXXXX",
    "auth_token": "your_vobiz_auth_token",
    "from_number": "+918065480085"
  }'

# Plivo
curl -X PUT "$BASE_URL/config/telephony/plivo" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_id": "MAxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_plivo_auth_token",
    "from_number": "+14155551234"
  }'

# Tata Smartflo
curl -X PUT "$BASE_URL/config/telephony/tata-smartflo" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ops@example.com",
    "password": "your-smartflo-password",
    "from_number": "+918065480085",
    "base_url": "https://api-smartflo.tatateleservices.com"
  }'

List connections when you need to choose a specific Plivo, Vobiz, or Tata Smartflo connection:

curl -sS "$BASE_URL/telephony/connections?provider=$CONNECTION_PROVIDER" \
  -H "Authorization: Bearer $API_KEY"

Create or choose an inbound agent:

curl -X POST "$BASE_URL/agent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Inbound Test Agent",
    "prompt": "You are a concise inbound support agent. Greet the caller, confirm the test is connected, and answer briefly.",
    "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
    "language": "en",
    "agent_type": "inbound",
    "intro_message": "Thanks for calling. This is the inbound test agent."
  }'

Save the returned data.id as AGENT_ID.

Sync your DIDs to Vocobase

Plivo — Vocobase pulls your inventory directly from Plivo’s REST API:

curl -X POST https://api.vocobase.com/api/v2/phone-numbers/sync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "PLIVO",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

Plivo response:

{
  "success": true,
  "data": {
    "imported": 2,
    "skipped": 1,
    "total_remote": 3
  }
}

Vobiz — pass an explicit numbers list (Vobiz has no inventory pull):

curl -X POST https://api.vocobase.com/api/v2/phone-numbers/sync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "VOBIZ",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "numbers": ["+918065480085", "+919109518550"]
  }'

Vobiz response:

{
  "success": true,
  "data": {
    "added": 2,
    "updated": 0,
    "removed": 0
  }
}

The Vobiz request body field is numbers, not phone_numbers.

Tata Smartflo — Vocobase pulls your DID inventory from Smartflo GET /v1/my_number:

curl -X POST https://api.vocobase.com/api/v2/phone-numbers/sync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "TATA_SMARTFLO",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

Tata Smartflo response:

{
  "success": true,
  "data": {
    "imported": 2,
    "skipped": 0,
    "total_remote": 2
  }
}

Syncing a Tata Smartflo DID into Vocobase does not change the Smartflo panel route by itself. Route the DID to the Voice-Bot streaming app in Smartflo before testing inbound calls.

List imported DIDs

List the partner’s imported phone numbers and save the id for the DID you want to assign:

curl "https://api.vocobase.com/api/v2/phone-numbers?provider=$PROVIDER" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "id": "f1a2c3d4-1111-2222-3333-444455556666",
        "phone_number": "+918065480085",
        "provider": "VOBIZ",
        "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
        "connection_name": "Vobiz India - Support",
        "friendly_name": null,
        "status": "ACTIVE",
        "is_default": false,
        "inbound_enabled": false,
        "agent": null,
        "created_at": "2026-05-20T08:00:00.000Z",
        "updated_at": "2026-05-20T08:00:00.000Z"
      }
    ]
  }
}

Save the phone number id as PHONE_NUMBER_ID.

Assign an agent to a DID

PUT /api/v2/phone-numbers/:id with agent_id. By default, assigning an agent also sets inbound_enabled to true. For outbound-only testing with the same DID on another account, send "inbound_enabled": false.

curl -X PUT https://api.vocobase.com/api/v2/phone-numbers/f1a2... \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "inbound_enabled": true }'

Successful response:

{
  "success": true,
  "data": {
    "id": "f1a2c3d4-1111-2222-3333-444455556666",
    "phone_number": "+918065480085",
    "provider": "VOBIZ",
    "friendly_name": null,
    "status": "ACTIVE",
    "is_default": false,
    "inbound_enabled": true,
    "agent": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Inbound Test Agent"
    }
  }
}

If carrier-side assignment fails, you’ll get a provider sync error such as 502 VOBIZ_SYNC_FAILED, 502 PLIVO_SYNC_FAILED, or 502 TATA_SMARTFLO_SYNC_FAILED. Retry after confirming the credentials, DID ownership, and provider-side routing.

Reconcile with one call

If you edit something in the carrier’s console directly or rotate credentials, POST /api/v2/phone-numbers/resync refreshes the assignment for every DID on that provider:

curl -X POST https://api.vocobase.com/api/v2/phone-numbers/resync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "VOBIZ",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

{
  "success": true,
  "data": {
    "total": 3,
    "succeeded": 3,
    "failed": [],
    "application_id": "VB_APP_a1b2c3d4"
  }
}

Receive the call

Call your DID. Vocobase routes the incoming call to the assigned agent and sends the same session.completed webhook payload as the Twilio flow above, with provider in the metadata.Expected result:

caller hears the assigned agent’s greeting
call creates an inbound session
session.completed webhook fires after hangup
webhook data.call.direction is inbound
webhook data.call.to_number is the DID
no VOBIZ_SYNC_FAILED, PLIVO_SYNC_FAILED, TATA_SMARTFLO_SYNC_FAILED, or 5xx appears during the assignment or call

See the per-provider setup guides for credential configuration — Plivo Setup, Vobiz Setup, and Tata Smartflo Setup. For multiple named connections, use Telephony Connections.

End-to-end Vobiz test script

This script assumes the agent already exists and the DID belongs to the partner’s Vobiz account.

set -euo pipefail

: "${API_KEY:?Set API_KEY}"
: "${AGENT_ID:?Set AGENT_ID}"
: "${DID:?Set DID in E.164 format, e.g. +918065480085}"

BASE_URL="${BASE_URL:-https://api.vocobase.com/api/v2}"
CONNECTION_FRAGMENT=""
if [ -n "${CONNECTION_ID:-}" ]; then
  CONNECTION_FRAGMENT=",\"connection_id\":\"$CONNECTION_ID\""
fi

echo "1. Check config"
curl -sS "$BASE_URL/config" \
  -H "Authorization: Bearer $API_KEY"

echo "\n2. Sync Vobiz DID"
curl -sS -X POST "$BASE_URL/phone-numbers/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"provider\":\"VOBIZ\"$CONNECTION_FRAGMENT,\"numbers\":[\"$DID\"]}"

echo "\n3. List Vobiz DIDs"
curl -sS "$BASE_URL/phone-numbers?provider=VOBIZ${CONNECTION_ID:+&connection_id=$CONNECTION_ID}" \
  -H "Authorization: Bearer $API_KEY"

echo "\n4. Set PHONE_NUMBER_ID from the list response, then run:"
echo "curl -X PUT \"$BASE_URL/phone-numbers/\$PHONE_NUMBER_ID\" \\"
echo "  -H \"Authorization: Bearer \$API_KEY\" \\"
echo "  -H \"Content-Type: application/json\" \\"
echo "  -d '{ \"agent_id\": \"'\$AGENT_ID'\", \"inbound_enabled\": true }'"

echo "\n5. After assignment succeeds, call $DID from a real phone."

Troubleshooting V2 inbound

Symptom	Likely cause	Fix
`400 VOBIZ_NOT_CONFIGURED` or `400 PLIVO_NOT_CONFIGURED`	Partner has no active telephony connection for that provider	Run `PUT /api/v2/config/telephony/vobiz` or `PUT /api/v2/config/telephony/plivo`, then retry
`400 TATA_SMARTFLO_NOT_CONFIGURED`	Partner has no active Tata Smartflo telephony connection	Run `PUT /api/v2/config/telephony/tata-smartflo`, then retry
`400 CONNECTION_AMBIGUOUS`	Partner has multiple active connections for that provider	Pass `connection_id` from `GET /api/v2/telephony/connections`
`400 VALIDATION_ERROR` on Vobiz sync	Body used `phone_numbers`, omitted `numbers`, or sent invalid E.164 values	Send `{ "provider": "VOBIZ", "numbers": ["+918065480085"] }`
`400 VALIDATION_ERROR` on Tata Smartflo sync	Provider-side DID inventory is unavailable or the provider value is incorrect	Send `{ "provider": "TATA_SMARTFLO" }` and confirm Smartflo API access is enabled
`409 VALIDATION_ERROR`	DID is already inbound-enabled on another active row	Disable inbound routing on the old row, or keep this row outbound-only with `inbound_enabled: false`
`400 AGENT_NOT_FOUND`	Agent ID belongs to another user, is deleted, or is not a valid UUID	Use an active agent owned by the same partner user
`404 phone number not found`	`PHONE_NUMBER_ID` is from another partner/provider or was not imported	Re-run `GET /api/v2/phone-numbers?provider=<PROVIDER>` and use that `id`
`502 VOBIZ_SYNC_FAILED`	Carrier-side assignment failed	Confirm Vobiz credentials and DID ownership, then retry
`502 TATA_SMARTFLO_SYNC_FAILED`	Tata Smartflo DID sync or inbound routing failed	Confirm Smartflo API access, DID ownership, and Smartflo panel Voice-Bot routing, then retry
Assignment succeeds but call reaches the wrong destination	Carrier-side Application binding may be stale	Run `POST /api/v2/phone-numbers/resync` and call again
Call connects but no webhook arrives	Partner webhook is not configured or endpoint rejects delivery	Configure `POST /api/v2/config/webhooks` and check your webhook server logs

Next steps

Knowledge Base

Upload documents to improve your agent’s answers.

Billing (₹)

Understand how call ₹ is calculated, including 15s buckets and tier pricing.

Plivo Setup

Configure Plivo credentials and DIDs.

Vobiz Setup

Configure Vobiz credentials and DIDs.

Tata Smartflo Setup

Configure Tata Smartflo credentials and DID routing.

Telephony Connections

Create and manage multiple named BYOP connections.

Twilio Setup

Configure Twilio credentials for your account.

Webhook Payloads

See the full payload structure for completed calls.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Inbound Calls

Inbound Calls

How inbound calls work

Prerequisites

Set up inbound calling

Inbound vs. outbound agents

Adding a knowledge base

Troubleshooting

Calls go to Twilio voicemail instead of the agent

Agent does not answer

Caller hears silence

Webhook shows wrong direction

Use the V2 phone-numbers API (Plivo + Vobiz + Tata Smartflo)

API tester quickstart

End-to-end Vobiz test script

Troubleshooting V2 inbound

Next steps

Knowledge Base

Billing (₹)

Plivo Setup

Vobiz Setup

Tata Smartflo Setup

Telephony Connections

Twilio Setup

Webhook Payloads

​Inbound Calls

​How inbound calls work

​Prerequisites

​Set up inbound calling

​Inbound vs. outbound agents

​Adding a knowledge base

​Troubleshooting

​Calls go to Twilio voicemail instead of the agent

​Agent does not answer

​Caller hears silence

​Webhook shows wrong direction

​Use the V2 phone-numbers API (Plivo + Vobiz + Tata Smartflo)

​API tester quickstart

​End-to-end Vobiz test script

​Troubleshooting V2 inbound

​Next steps

Knowledge Base

Billing (₹)

Plivo Setup

Vobiz Setup

Tata Smartflo Setup

Telephony Connections

Twilio Setup

Webhook Payloads

Inbound Calls

How inbound calls work

Prerequisites

Set up inbound calling

Inbound vs. outbound agents

Adding a knowledge base

Troubleshooting

Calls go to Twilio voicemail instead of the agent

Agent does not answer

Caller hears silence

Webhook shows wrong direction

Use the V2 phone-numbers API (Plivo + Vobiz + Tata Smartflo)

API tester quickstart

End-to-end Vobiz test script

Troubleshooting V2 inbound

Next steps