Inbound Call

Handles inbound phone calls — resolves the caller, fetches assistant configuration, builds the AI starter script with contact context.

Volume: ~3K runs/week | Auth: None (Telnyx webhook)

Request

POST /api/v1/inbound-call
Content-Type: application/json

Body Parameters

Field	Type	Required	Description
`to_number`	string	✅	Called number (your Telnyx number)
`from_number`	string	✅	Caller's phone number
`llm_id`	string		LLM/assistant ID for routing
`agent_id`	string		Alternative agent ID

Responses

Success

{
  "assistant_id": "asst_123",
  "assistant_name": "Support Agent",
  "prompt": "You are a helpful assistant for Acme Corp...",
  "first_message": "Hello! Thanks for calling Acme Corp. How can I help?",
  "contact": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+15551234567"
  },
  "location_id": "loc_456",
  "variables": {
    "contact_name": "John Doe",
    "company": "Acme Corp"
  }
}

No LLM ID

{ "event": "done", "path": "llm doesnt exist" }

No Routing Config

{ "error": "No routing config for number", "to_number": "+15559876543" }

Test with cURL

curl -X POST http://localhost:3000/api/v1/inbound-call \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+15559876543",
    "from_number": "+15551234567",
    "llm_id": "asst_123"
  }'

Pipeline Flow

Validate llm_id exists
Look up PhoneNumber → inboundForAssistant relation (Prisma)
Get SubAccount for location context
Search GHL contacts by caller phone number
If contact found: fetch full contact details
Build AI starter script with assistant prompt + contact context
Return assistant config with resolved variables

POST /api/v1/inbound-call

On this page