Documentation

Inbound Calling

Configure inbound calling for Twilio, Vonage, Plivo, Telnyx, Cloudonix, Vobiz, and Asterisk ARI providers in Paladin AI

Overview#

Paladin AI supports inbound calling throughout all supported telephony providers. When someone calls your configured phone number, your voice agent automatically answers and handles the interaction. Inbound and outbound calls share the same telephony configuration.

Supported Providers for Inbound Calls#

TwilioIndustry leading platform with robust inbound call handlingVonageApplication level inbound routing with high quality 16kHz audioPlivoApplication level inbound routing on Plivo's global voice cloudTelnyxApplication level inbound via Telnyx Call Control APICloudonixSIP based inbound calling with flexible trunk configurationVobizCloud based telephony with global reach and competitive pricingAsterisk ARIConnect to your own Asterisk PBX via the Asterisk REST Interface

How Inbound Calling Works#

Paladin exposes a single inbound webhook URL for the whole org:

text
https://app.paladin.northmanngrp.com/api/v1/telephony/inbound/run

When a call arrives:

  1. Call Received: Your telephony provider receives the incoming call
  2. Webhook Triggered: The provider sends a webhook to /inbound/run
  3. Org & Agent Resolved: Paladin identifies the org from the webhook's account credentials, then looks up which agent should answer based on the called number's Inbound workflow assignment in your telephony configuration
  4. Audio Streaming: Real-time audio streams between caller and agent via WebSocket
  5. Conversation Handled: Your voice agent manages the entire conversation

You don't construct per-workflow URLs anymore — the routing is done by the called number's inbound workflow assignment in Paladin.

Configuration in Paladin AI#

Setting up inbound calling takes three steps:

Step 1: Configure Telephony Provider#

The telephony configuration for inbound calling is identical to outbound calling. Add (or open) a configuration at /telephony-configurations following your provider's documentation:

Step 2: Assign an Inbound Workflow to the Phone Number#

  1. Go to /telephony-configurations and open your configuration
  2. In the Phone numbers section, edit the number that should receive inbound calls
  3. Set its Inbound workflow to the agent that should answer
  4. Save

This is what tells Paladin which agent to run when a call comes in for that number.

Step 3: Point Your Provider at /inbound/run#

Each provider needs its inbound webhook (Twilio Voice URL / Vonage Answer URL / etc.) set to the global Paladin endpoint:

text
https://app.paladin.northmanngrp.com/api/v1/telephony/inbound/run

The exact place to set this varies by provider — follow the provider-specific instructions:

Testing Inbound Calls#

After completing both the Paladin AI configuration and provider-specific setup:

  1. Test Call: Call your configured phone number from another phone
  2. Verify Connection: Ensure your voice agent answers and responds appropriately
  3. Check Logs: Monitor call logs in both Paladin AI and your provider's dashboard
  4. Audio Quality: Verify clear two-way audio communication

Troubleshooting Common Issues#

Calls go to voicemail instead of agent
  • Verify webhook URLs are correctly configured at your provider
  • Check that webhook endpoints are publicly accessible
  • Ensure phone numbers are properly linked to your application
Agent doesn
  • Confirm your voice agent workflow is properly configured
  • Check webhook signature validation is working
  • Verify WebSocket connections are established successfully
Provider mismatch error
  • Error: "Configuration error: This phone number is configured for a different telephony provider"
  • Solution: Check your dashboard settings and update your webhook URL configuration to match the correct provider
  • Ensure the phone number is configured for the same provider in both Paladin AI and your telephony console
Workflow not found error
  • Error: "Workflow not found"
  • Solution: Open the called number in /telephony-configurations and confirm an Inbound workflow is assigned. Without an assignment, Paladin has no agent to route the call to.
  • Verify the assigned workflow still exists in your dashboard
Account validation failed
  • Error: "Authentication error: Account credentials do not match"
  • Solution: Verify your account SID/credentials configuration in Paladin AI matches your telephony provider settings
  • Re-enter your provider credentials in the telephony configuration page
Phone number not configured
  • Error: "Phone number not configured: This number is not set up for inbound calls"
  • Solution: Add this phone number under Phone numbers in your telephony configuration at /telephony-configurations
  • Ensure the phone number is also linked to your provider account
Signature validation failed
  • Error: "Security error: Webhook signature validation failed"
  • Solution: Verify your auth token configuration in Paladin AI matches your provider settings
  • Ensure webhook requests are coming from your telephony provider's verified IP ranges
  • Check that your webhook URL is accessible and responding correctly
Quota exceeded error
  • Error: "Service temporarily unavailable: Your account has exceeded usage limits"
  • Solution: Contact your administrator or upgrade your plan to continue receiving calls
  • Check your provider account billing and usage limits
General authentication failed
  • Error: "Authentication failed"
  • Solution: Check your webhook URL configuration and ensure your telephony provider settings match your dashboard configuration
  • Verify all credentials are entered correctly and haven't expired
  • Test the webhook URL is publicly accessible from your provider's servers
Poor audio quality on inbound calls
  • Check network bandwidth and latency from provider to Paladin AI
  • Verify audio pipeline configuration matches provider requirements
  • Review WebSocket connection stability

Best Practices#

  • Single Configuration: Use the same telephony configuration for both inbound and outbound calls
  • Testing: Always test inbound calling after configuration changes
  • Monitoring: Monitor both Paladin AI logs and provider dashboards for call analytics
  • Security: Ensure webhook signature verification is enabled for security

Next Steps#

  1. Choose your telephony provider and complete the basic configuration
  2. Follow the provider-specific setup instructions
  3. Assign an inbound workflow to each phone number that should accept calls
  4. Test your inbound calling setup