This guide walks you through setting up ThunderPhone to handle your first AI-powered phone call.
Prerequisites
You’ll need a ThunderPhone account. Sign up if you haven’t already. Step 1: Get Your API Token
Log into ThunderPhone Dashboard
Navigate to Settings
Click on Settings in the sidebar, then select API Keys.
Generate a Token
Click Create API Key and copy your token. Store it securely—you won’t be able to see it again.
Step 2: Create Your First Agent
An agent defines how your AI handles conversations—including the system prompt, voice, and any tools it can use.
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/agents \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support",
"prompt": "You are a friendly customer support agent for Acme Corp. Help customers with their questions about orders, returns, and product information. Be concise and helpful.",
"voice": "en-US-Standard-Journey-D",
"product": "spark"
}'
Product options: Choose spark for the fastest response times, bolt for balanced performance, or zap for highest quality.
Step 3: Provision a Phone Number
curl -X POST https://api.thunderphone.com/v1/orgs/{org_id}/phone-numbers \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"inbound_agent_id": 12
}'
curl -X PUT https://api.thunderphone.com/v1/orgs/{org_id}/webhook \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/thunderphone-webhook"
}'
call.incoming — When a call starts (return agent config to override)call.complete — When a call ends (includes transcript and recording URL)
See Webhooks for implementation details.
Step 5: Test Your Agent
Call your new phone number! The AI agent will answer and respond according to your configured prompt.
You can view call details in the dashboard or via the API:
curl https://api.thunderphone.com/v1/orgs/{org_id}/calls \
-H "Authorization: Token YOUR_API_TOKEN"
Next Steps
