Inbound Calls

Inbound calls are the most common use case for voice agents. When a customer dials your number, your thinnestAI voice agent picks up instantly, greets the caller, and handles the conversation — no hold times, no menus, no frustration.

Prerequisites

Before setting up inbound calls, you need:

1. A thinnestAI account with voice capabilities enabled
2. A voice agent configured in the dashboard
3. A phone number from Twilio or Vobiz

Setting Up a Phone Number

Option A: Purchase a Twilio Number

1. Go to Settings → Phone Numbers in the thinnestAI dashboard.
2. Click Add Phone Number → Twilio.
3. Enter your Twilio credentials:

TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token

4. Browse available numbers by country and area code.
5. Select a number and click Purchase.
6. The number is automatically configured to route calls to thinnestAI.

Option B: Connect a Vobiz Number

1. Go to Settings → Phone Numbers → Add Phone Number → Vobiz.
2. Enter your Vobiz SIP credentials.
3. Configure the SIP trunk to point to your thinnestAI endpoint.
4. The number appears in your dashboard once connected.

Option C: Import Your Own Twilio Number (BYOK)

If you already have a Twilio account with purchased numbers:

1. Go to Settings → Phone Numbers → Twilio → Import Your Own (BYOK).
2. Enter your Twilio Account SID and Auth Token (from console.twilio.com).
3. Click Validate & Connect — your credentials are encrypted and stored securely.
4. You'll see all phone numbers in your Twilio account.
5. Click Import on any number to connect it.

What happens automatically:

• thinnestAI creates an Elastic SIP Trunk on your Twilio account
• Configures the incoming webhook to route calls to your voice agent
• Creates LiveKit SIP resources for real-time audio
• Sets up outbound calling capability

Billing: No monthly charge from thinnestAI — you pay Twilio directly. We only charge the ₹1.50/min platform fee.

Option D: Import Your Own Vobiz Number (BYOK)

If you already have a Vobiz account with Indian DID numbers:

1. Go to Settings → Phone Numbers → Vobiz → Import Your Own (BYOK).
2. Enter your Vobiz Auth ID and Auth Token (from vobiz.ai/dashboard).
3. Click Validate & Connect.
4. Select numbers to import from your account.

What happens automatically:

• SIP trunk, credentials, and origination URI created on your Vobiz account
• LiveKit inbound/outbound trunks configured for routing
• Dispatch rules set up for agent routing

Billing: No monthly charge from thinnestAI — you pay Vobiz directly. We only charge the ₹1.50/min platform fee.

Option E: Import Your Own Exotel Number (BYOK) Beta

1. Go to Phone Numbers → Exotel.
2. Enter your API Key, API Token, Account SID, and Subdomain (from developer.exotel.com).
3. Click Validate & Connect — your numbers are listed.
4. Click Import on any number.

Billing: ₹0/mo from thinnestAI. You pay Exotel directly for telephony. We charge ₹1.50/min platform fee.

Option F: Import Your Own Plivo Number (BYOK) Beta

1. Go to Phone Numbers → Plivo.
2. Enter your Auth ID and Auth Token (from console.plivo.com).
3. Click Validate & Connect.
4. Import your numbers.

Billing: ₹0/mo from thinnestAI. You pay Plivo directly. We charge ₹1.50/min platform fee.

Option G: Import Your Own Telnyx Number (BYOK) Beta

1. Go to Phone Numbers → Telnyx.
2. Enter your API Key (from portal.telnyx.com).
3. Click Validate & Connect.
4. Import your numbers.

Billing: ₹0/mo from thinnestAI. You pay Telnyx directly. We charge ₹1.50/min platform fee.

Configuring Your Agent for Inbound Calls

Agent Settings

Navigate to your agent's configuration and set up the inbound call behavior:

Greeting message — The first thing your agent says when it picks up:

"Hello, thank you for calling Acme Support. My name is Sarah. How can I help you today?"

System prompt — Define how your agent handles calls:

You are Sarah, a customer support agent for Acme Corp.

Rules:
- Always greet the caller warmly
- Ask for their account number or email to look up their information
- Handle common questions about billing, shipping, and returns
- If you cannot resolve the issue, offer to transfer to a human agent
- Always confirm the resolution before ending the call

End-of-call message — What your agent says before hanging up:

"Thank you for calling Acme Support. Is there anything else I can help you with? Have a great day!"

Assigning the Phone Number

1. Open your voice agent in the dashboard.
2. Go to Phone Numbers tab.
3. Select the phone number you want to assign.
4. Click Save.

All calls to that number will now be routed to your voice agent.

Call Routing and IVR Navigation

Simple Routing

By default, all calls to your assigned number go directly to the voice agent. The agent picks up, greets the caller, and handles the conversation.

Multi-Agent Routing

For more complex setups, you can route calls to different agents based on criteria:

By time of day:

{
  "routing_rules": [
    {
      "condition": "time_between",
      "start": "09:00",
      "end": "17:00",
      "timezone": "America/New_York",
      "agent_id": "business_hours_agent"
    },
    {
      "condition": "default",
      "agent_id": "after_hours_agent"
    }
  ]
}

By caller information:

{
  "routing_rules": [
    {
      "condition": "caller_id_prefix",
      "prefix": "+44",
      "agent_id": "uk_support_agent"
    },
    {
      "condition": "default",
      "agent_id": "general_agent"
    }
  ]
}

Visual IVR

thinnestAI supports Visual IVR — an intelligent routing layer that uses AI instead of DTMF menus:

1. The agent answers the call and asks what the caller needs.
2. Based on the caller's natural language response, the system routes to the appropriate department or agent.
3. No "Press 1 for billing, press 2 for support" — just a natural conversation.

Configure Visual IVR in the Flow Editor by creating a routing node connected to multiple agent nodes.

Handling Caller Information

Caller ID

When a call comes in, thinnestAI captures:

• Caller phone number — The caller's phone number in E.164 format
• Called number — Which of your numbers was dialed
• Call timestamp — When the call started
• Call direction — Marked as inbound

Passing Context to Your Agent

You can enrich calls with customer data by configuring a webhook that fires when a call comes in:

POST https://your-app.com/webhooks/incoming-call

The webhook receives:

{
  "call_id": "call_abc123",
  "caller_number": "+14155551234",
  "called_number": "+18005551234",
  "agent_id": "agent_xyz",
  "timestamp": "2026-03-05T10:30:00Z"
}

Your webhook can return context to inject into the conversation:

{
  "context": {
    "customer_name": "John Smith",
    "account_id": "ACME-12345",
    "subscription_tier": "Enterprise",
    "open_tickets": 2
  }
}

The agent can then use this information: "Hi John, I can see you're on our Enterprise plan. How can I help you today?"

Testing Inbound Calls

Web Call Test

The fastest way to test is the built-in web call feature:

1. Open your voice agent in the dashboard.
2. Click Test Call.
3. Your browser connects directly to the agent.
4. Speak naturally and verify the agent's responses.

Live Phone Test

For a full end-to-end test:

1. Call your assigned phone number from any phone.
2. Verify the greeting plays correctly.
3. Test various conversation paths.
4. Confirm call recording is working (if enabled).
5. Test edge cases: silence, interruptions, unexpected questions.

Test Checklist

Use this checklist before going live:

• Agent answers within 1-2 seconds
• Greeting message sounds natural
• Agent understands common questions
• Agent handles interruptions gracefully
• Silence timeout triggers an appropriate prompt
• Call transfer works (if configured)
• Call recording captures both sides
• End-of-call behavior is correct
• Agent handles "I want to speak to a human" requests

Monitoring Call Logs

Dashboard

The Call Logs section shows all inbound calls:

API Access

Retrieve call logs programmatically:

curl -X GET "https://api.thinnest.ai/voice/sessions?direction=inbound&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "calls": [
    {
      "id": "call_abc123",
      "direction": "inbound",
      "caller_number": "+14155551234",
      "agent_id": "agent_xyz",
      "duration_seconds": 145,
      "status": "completed",
      "recording_url": "https://storage.thinnest.ai/recordings/call_abc123.wav",
      "created_at": "2026-03-05T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

Alerts

Set up alerts for important events:

• Missed calls — When a call is not answered (agent unavailable)
• Long calls — Calls exceeding a duration threshold
• Transfer failures — When a call transfer does not complete
• High volume — When call volume spikes above normal

Configure alerts in Settings → Notifications.

Best Practices

1. Keep greetings short — Callers want to state their problem quickly. A 5-second greeting is better than 15 seconds.

2. Handle "I don't understand" gracefully — Configure your agent to ask clarifying questions rather than repeating the same response.

3. Set appropriate timeouts — If the caller is silent for too long, prompt them: "Are you still there? I'm happy to help if you have any questions."

4. Test with real callers — Internal testing catches most issues, but real callers will find edge cases you did not anticipate.

5. Monitor regularly — Review call logs weekly. Look for patterns in failed conversations and update your agent's prompt accordingly.

6. Use context — The more your agent knows about the caller before the conversation starts, the better the experience.

Next Steps

• Voice Configuration — Fine-tune how your agent sounds
• Call Recording — Enable recording and transcription
• Call Transfers — Route calls to human agents when needed