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)
A phone number with voice capabilities from your chosen provider

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

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)

For Plivo and Vobiz, you don’t need to paste an answer URL into the carrier’s portal. Use the V2 phone-numbers endpoints — Vocobase will pull or accept your DID inventory, then auto-bind each DID to a carrier Application pointing at our inbound URL the moment you assign an agent.

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" # or PLIVO
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, or data.telephony.plivo.configured is true for Plivo
the provider appears in data.allowed_telephony_providers

If the provider is not configured, configure it first:

# 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"
  }'

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" }'

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",
    "numbers": ["+918065480085", "+919109518550"]
  }'

Vobiz response:

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

The Vobiz request body field is numbers, not phone_numbers.

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=VOBIZ" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "id": "f1a2c3d4-1111-2222-3333-444455556666",
        "phone_number": "+918065480085",
        "provider": "VOBIZ",
        "friendly_name": null,
        "status": "ACTIVE",
        "is_default": 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. For both Plivo and Vobiz, Vocobase configures the carrier-side routing for the DID automatically — no portal paste needed.

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" }'

Successful response:

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

If carrier-side assignment fails, you’ll get 502 VOBIZ_SYNC_FAILED or 502 PLIVO_SYNC_FAILED. Retry after confirming the credentials and DID ownership.

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" }'

{
  "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, or 5xx appears during the assignment or call

See the per-provider setup guides for credential configuration — Plivo Setup, Vobiz Setup. The endpoints above only work after the partner has uploaded their auth_id / auth_token via PUT /api/v2/config/telephony/{plivo|vobiz}.

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}"

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\",\"numbers\":[\"$DID\"]}"

echo "\n3. List Vobiz DIDs"
curl -sS "$BASE_URL/phone-numbers?provider=VOBIZ" \
  -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'\" }'"

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 VALIDATION_ERROR` on Vobiz sync	Body used `phone_numbers`, omitted `numbers`, or sent invalid E.164 values	Send `{ "provider": "VOBIZ", "numbers": ["+918065480085"] }`
`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=VOBIZ` and use that `id`
`502 VOBIZ_SYNC_FAILED`	Carrier-side assignment failed	Confirm Vobiz credentials and DID ownership, 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.

Twilio Setup

Configure Twilio credentials for your account.

Webhook Payloads

See the full payload structure for completed calls.

Documentation Index

​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)

​API tester quickstart

​End-to-end Vobiz test script

​Troubleshooting V2 inbound

​Next steps

Knowledge Base

Billing (₹)

Plivo Setup

Vobiz Setup

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)

API tester quickstart

End-to-end Vobiz test script

Troubleshooting V2 inbound

Next steps