Skip to main content
You can do all this using the UI which will be much faster and simpler

​
Prerequisites

Before you begin, make sure you have:
  • A Feather account (sign up here)
  • Your API key from the dashboard
  • A phone number to test with (or use Twilio integration)

​
Step 1: Create Your First Agent

Create an agent with a basic configuration. This will create both the agent and its first version: 
curl -X POST "https://prod.featherhq.com/api/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries and support requests",
    "voicemailMessage": null,
    "overrideSTTConfig": null,
    "sttConfigId": "nova-3-stt",
    "ttsConfigId": "aura-2-tts",
    "llmConfigId": "gpt-4o-mini-llm",
    "voiceId": "6011b4c8-6140-4b7e-8a92-d9880de97b77",
    "prompt": {
      "system": "You are a helpful customer support assistant. Be friendly, professional, and help customers with their questions.",
      "tools": [],
      "preBuiltTools": []
    },
    "useKnowledgeBase": false,
    "enableBackgroundAudio": false
  }'
This creates both an agent and its first version. Save the agent.id and agent.version.id from the response - you’ll need them for the next steps.

​
Step 2: Set Up Phone Numbers

You have two options for phone numbers:

​
Option A: Connect Existing Twilio Number

If you already have a Twilio account with phone numbers: 
curl -X POST "https://prod.featherhq.com/api/v1/twilio/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSid": "YOUR_TWILIO_ACCOUNT_SID",
    "authToken": "YOUR_TWILIO_AUTH_TOKEN",
    "phoneNumber": "+14155551234"
  }'

​
Option B: Purchase New Twilio Number

Search for and purchase a new number: 
# Search for available numbers
curl "https://prod.featherhq.com/api/v1/twilio/search?areaCode=415" \
  -H "X-API-Key: YOUR_API_KEY"

# Purchase a number
curl -X POST "https://prod.featherhq.com/api/v1/twilio/purchase" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234"
  }'

​
Step 3: Associate Phone Number with Agent

Set up dispatch rules so calls use your agent: 
# For outbound calls
curl -X PUT "https://prod.featherhq.com/api/v1/phone-number/outbound/YOUR_PHONE_ID/dispatch-rule" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentIds": ["YOUR_AGENT_ID"]
  }'

# For inbound calls (optional)
curl -X POST "https://prod.featherhq.com/api/v1/phone-number/inbound/YOUR_PHONE_ID/dispatch-rule" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_ID"
  }'

​
Step 4: Make Your First Call

Dispatch your agent to make an outbound call: 
curl -X POST "https://prod.featherhq.com/api/v1/agent/YOUR_AGENT_ID/dispatch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_123",
    "firstName": "John",
    "toPhoneNumber": "+14155559999",
    "mode": "audio",
    "customer": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "variables": {
      "product_interest": "Premium Plan"
    }
  }'
Your agent will call the toPhoneNumber and introduce itself as a customer support assistant. The call will be recorded and transcribed, and you can view the details in your dashboard.

​
What’s Next?

Congratulations! You’ve created your first voice AI agent and made a call. Here are some next steps:

Add Tools

Give your agent capabilities like booking appointments, looking up information, or updating your CRM.

Knowledge Base

Upload documents so your agent can answer specific questions about your business with accurate information.

Workflows

Create multi-step call sequences to nurture leads over time with automated follow-ups.

Testing Lab

Test your agent with automated scenarios to ensure quality before production deployment.

​
Understanding Agent Concepts

​
Agent vs Agent Version

  • Agent: The persistent identity with a name and description
  • Agent Version: The configuration that defines behavior (prompts, tools, voice, etc.)
You can have multiple versions of the same agent for testing different configurations. Only one version can be deployed (active) at a time.

​
Configuration Options

​
Monitoring Your Calls

After dispatching calls, you can:
  1. View call details - See transcripts, recordings, and analytics in your dashboard
  2. Check dispositions - Understand how calls ended (completed, no answer, etc.)
  3. Track lead information - See what your agent learned during conversations
  4. Monitor performance - Analyze call duration, success rates, and more
Learn more in Calls.

​
Troubleshooting

​
Agent Not Responding

  • Verify the agent version is deployed
  • Check that dispatch rules are configured correctly
  • Ensure phone numbers are in E.164 format (+14155551234)

​
Can’t Connect to Twilio

  • Verify Twilio credentials are correct
  • Ensure phone number is valid and available
  • Check Twilio account has sufficient balance
Need more help? Check out our troubleshooting guide or reach out to support@featherhq.com.