> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound Calls

> Configure your voice agent to answer incoming phone calls automatically with intelligent conversation handling.

# 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:

```bash theme={null}
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](https://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](https://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](https://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](https://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](https://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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```bash theme={null}
POST https://your-app.com/webhooks/incoming-call
```

The webhook receives:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

| Field          | Description                                |
| -------------- | ------------------------------------------ |
| **Call ID**    | Unique identifier for the call             |
| **Caller**     | The caller's phone number                  |
| **Agent**      | Which agent handled the call               |
| **Duration**   | How long the call lasted                   |
| **Status**     | Completed, Transferred, Dropped, No Answer |
| **Recording**  | Link to the call recording (if enabled)    |
| **Transcript** | Full conversation transcript               |
| **Timestamp**  | When the call occurred                     |

### API Access

Retrieve call logs programmatically:

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

Response:

```json theme={null}
{
  "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](/docs/voice/voice-configuration) — Fine-tune how your agent sounds
* [Call Recording](/docs/voice/call-recording) — Enable recording and transcription
* [Call Transfers](/docs/voice/call-transfer) — Route calls to human agents when needed