Phone Calls

Give your voice agent a phone number so customers can call it — or have it call them. thinnestAI handles the entire call lifecycle: answering, speaking, listening, and hanging up.

Prerequisites

• A thinnestAI account with voice enabled
• A voice agent configured with TTS and STT settings
• A phone number from Twilio or Vobiz

Quick Start

1. Get a Phone Number

Option A: Twilio (recommended for most users)

1. Sign up at twilio.com
2. Purchase a phone number in the Twilio Console
3. In thinnestAI dashboard, go to Settings > Phone Numbers > Add > Twilio
4. Enter your Account SID and Auth Token

Option B: Vobiz (for Indian telephony)

1. Get SIP credentials from your Vobiz account
2. In thinnestAI, go to Settings > Phone Numbers > Add > Vobiz
3. Enter your SIP trunk credentials

Option C: Bring Your Own Number

If you already have a number with any SIP provider:

1. Go to Settings > Phone Numbers > Add > Existing
2. Enter the number in E.164 format (e.g., +14155551234)
3. Point your provider's webhook to:

https://api.thinnest.ai/voice/twilio/incoming/YOUR_PHONE_ID

2. Assign to Your Agent

1. Open your voice agent
2. Go to Deploy > Phone
3. Select your phone number
4. Configure the greeting message
5. Click Enable

3. Test It

Call your number — your agent picks up immediately.

Inbound Calls

When someone calls your number:

Caller dials your number
        ↓
Twilio/Vobiz routes to thinnestAI via SIP
        ↓
Voice engine picks up, plays greeting
        ↓
Caller speaks → STT → Agent processes → TTS → Caller hears response
        ↓
Loop continues until call ends

Configuring Inbound Behavior

Example Agent Configuration

{
  "voice": {
    "greeting": "Hi, thanks for calling Acme. How can I help you today?",
    "tts": {
      "provider": "aero",
      "model": "aero-2",
      "voice": "maya"
    },
    "stt": {
      "provider": "deepgram",
      "model": "nova-2",
      "language": "en"
    },
    "max_duration": 600,
    "recording": true
  }
}

Outbound Calls

Have your agent call customers proactively.

Single Call via API

curl -X POST "https://api.thinnest.ai/voice/outbound/dial" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz",
    "to_number": "+14155551234",
    "from_number": "+18005551234",
    "context": {
      "customer_name": "Jane Doe",
      "appointment_date": "March 10, 2026"
    }
  }'

Scheduled Calls

Schedule a call for a future time:

curl -X POST "https://api.thinnest.ai/voice/outbound/dial" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "agent_xyz",
    "to_number": "+14155551234",
    "from_number": "+18005551234",
    "scheduled_at": "2026-03-10T14:00:00Z"
  }'

Batch Calls (Campaigns)

For bulk outreach, use Campaigns:

1. Create a campaign with your voice agent
2. Upload a contact list (CSV or manual)
3. Set schedule, concurrency, and retry rules
4. Launch — the platform calls each contact automatically

Call Status Webhook

Track call progress by providing a webhook URL:

{
  "webhook_url": "https://your-app.com/call-status",
  "to_number": "+14155551234",
  ...
}

You'll receive events: initiating, ringing, in_progress, completed, failed, no_answer.

SIP Trunking

For enterprise setups, connect your existing PBX or contact center via SIP:

Your PBX / Contact Center
        ↓ (SIP)
Twilio Elastic SIP Trunk / Vobiz
        ↓ (SIP)
thinnestAI Voice Engine (LiveKit)
        ↓
AI Agent handles the call

Benefits

• Use existing phone numbers — no porting needed
• Keep your current PBX infrastructure
• Route some calls to AI, others to humans
• Failover between providers

See the full SIP Integration guide for setup details.

Call Analytics

Every call generates:

• Duration and timestamps
• Full transcript (caller and agent)
• Recording (if enabled)
• Token usage and cost
• Caller phone number (auto-captured as a lead)

View call history in Voice > Sessions in the dashboard.

Pricing

Exact rates depend on your Twilio/Vobiz plan and the TTS/STT providers you choose.

Troubleshooting