​

Inbound Calls

​

Prerequisites

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)

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.

• 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

​

Option D: Import Your Own Vobiz Number (BYOK)

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.

• 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

​

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.

​

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.

​

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.

​

Configuring Your Agent for Inbound Calls

​

Agent Settings

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

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

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

​

Call Routing and IVR Navigation

​

Simple Routing

​

Multi-Agent Routing

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

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

​

Visual IVR

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.

​

Handling Caller Information

​

Caller ID

• 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

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

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

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

​

Testing Inbound Calls

​

Web Call Test

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

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

• 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

​

API Access

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

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

• 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

​

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