DEV Community

voipbin
voipbin

Posted on

VoIPBin Quickstart: Make Your First AI Phone Call in 10 Minutes

#voip #ai #tutorial #webdev

VoIPBin Quickstart: Make Your First AI Phone Call in 10 Minutes

Who is this for: Developers building AI agents, voice bots, or anything that needs to make/receive phone calls.
Goal: From signup to your first outbound call in under 10 minutes.
Prerequisites: curl, internet connection, a valid email address.

Overview 

Step 1: Sign up & get your accesskey     (~1 min)
Step 2: Create an extension              (~1 min)
Step 3: Register a virtual number        (~2 min)
Step 4: Make your first call with TTS    (~2 min)
[Optional] Add an AI voice agent         (~5 min)
Enter fullscreen mode Exit fullscreen mode

URL rules:

  • Signup only: https://api.voipbin.net/auth/signup (no version prefix)
  • All other APIs: https://api.voipbin.net/v1.0/...
  • Auth: append ?accesskey=<token> to every /v1.0/ request

Step 1: Sign Up & Get Your accesskey (~1 min)

1-1. Create your account 

curl -X POST "https://api.voipbin.net/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company",
    "email": "you@example.com",
    "accepted_tos": true
  }'
Enter fullscreen mode Exit fullscreen mode

Required fields:

  • email — must be unique
  • accepted_tos — must be true (HTTP 400 if missing or false)
  • name — display name (optional but recommended)

Success response (HTTP 200):

{
  "customer": {
    "id": "8ecaddc4-132b-442c-b298-50eb5f999ef4",
    "name": "My Company",
    "email": "you@example.com",
    "status": "initial"
  },
  "accesskey": {
    "token": "vb_hTKRAgGglhaw8na3zpuHEx8JQs5dPJgd",
    "tm_expire": "2027-04-10T02:35:36Z"
  }
}
Enter fullscreen mode Exit fullscreen mode

⚠️ Save your token now. It is only returned once at signup. Subsequent calls to GET /v1.0/accesskeys only return a token_prefix.

Got an empty {} response? The email is already registered. Use a different email (VoIPBin does not confirm duplicates for security reasons).

1-2. Save your key 

export VOIPBIN_KEY="vb_hTKRAgGglhaw8na3zpuHEx8JQs5dPJgd"  # replace with your token
Enter fullscreen mode Exit fullscreen mode

1-3. Verify your account 

curl "https://api.voipbin.net/v1.0/customer?accesskey=$VOIPBIN_KEY"
Enter fullscreen mode Exit fullscreen mode

Check these fields:

  • status: "initial" — email not yet verified, but virtual number tests work fine
  • balance_token: 100 — free credits for new accounts

To call real PSTN numbers (like +1-555-xxx), you will need email verification + identity verification. For now, virtual numbers work without any verification.

Step 2: Create an Extension (~1 min)

An extension is a virtual phone endpoint — think of it as an internal SIP address. You can receive calls on it using a SIP softphone (e.g., Linphone), or use it as a destination for your AI agent to call.

Note on uniqueness: The extension value must be globally unique across the entire VoIPBin platform. Use a timestamp or UUID to avoid conflicts.

EXT_ID="qs-$(date +%s)"

curl -X POST "https://api.voipbin.net/v1.0/extensions?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"extension\": \"$EXT_ID\",
    \"name\": \"quickstart-phone\",
    \"detail\": \"My quickstart extension\",
    \"password\": \"SecurePass123!\"
  }"
Enter fullscreen mode Exit fullscreen mode

Success response:

{
  "id": "5c48c33d-5a0d-4c66-a858-d93baf692352",
  "name": "quickstart-phone",
  "extension": "qs-1775789155",
  "direct_hash": "direct.5411df2cf9c6"
}
Enter fullscreen mode Exit fullscreen mode

Important: When making calls to this extension, use the name value ("quickstart-phone") as target_name.

Optional — connect a SIP softphone to actually hear the call:

  • SIP server: sip.voipbin.net
  • Username: the extension field value
  • Domain: the domain_name field value
  • Password: what you set above

Step 3: Register a Virtual Number (~2 min)

Virtual numbers (+899 range) let you test voice flows without buying a real phone number. No email verification needed.

3-1. Find an available virtual number 

curl "https://api.voipbin.net/v1.0/available_numbers?accesskey=$VOIPBIN_KEY&type=virtual"
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "result": [
    { "number": "+899617591104", "country": "899", "features": ["voice"] },
    { "number": "+899469526280", "country": "899", "features": ["voice"] }
  ]
}
Enter fullscreen mode Exit fullscreen mode

3-2. Register the number 

curl -X POST "https://api.voipbin.net/v1.0/numbers?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+899617591104",
    "type": "virtual",
    "call_flow_id": "00000000-0000-0000-0000-000000000000",
    "message_flow_id": "00000000-0000-0000-0000-000000000000",
    "name": "quickstart-virtual",
    "detail": "My quickstart number"
  }'
Enter fullscreen mode Exit fullscreen mode

call_flow_id and message_flow_id define what happens when someone calls this number. For outbound-only testing, use the nil UUID "00000000-0000-0000-0000-000000000000".

export VOIPBIN_NUMBER="+899617591104"  # replace with your number
Enter fullscreen mode Exit fullscreen mode

Step 4: Make Your First Call — TTS Voice Message (~2 min)

This is the part where your AI agent actually speaks. You do not need to handle any audio, codecs, or media servers — VoIPBin takes care of all of that.

curl -X POST "https://api.voipbin.net/v1.0/calls?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"source\": {
      \"type\": \"tel\",
      \"target\": \"$VOIPBIN_NUMBER\"
    },
    \"destinations\": [
      {
        \"type\": \"extension\",
        \"target_name\": \"quickstart-phone\"
      }
    ],
    \"actions\": [
      {
        \"type\": \"talk\",
        \"option\": {
          \"text\": \"Hello! This is a VoIPBin test call. Your AI voice agent is working!\",
          \"language\": \"en-US\"
        }
      },
      {
        \"type\": \"hangup\"
      }
    ]
  }"
Enter fullscreen mode Exit fullscreen mode

Supported languages for talk:

  • English: "en-US"
  • Korean: "ko-KR"
  • Japanese: "ja-JP"

Success response:

{
  "groupcalls": [
    {
      "id": "fc2b8e74-cdab-435c-827b-cc3c6e59ffc1",
      "status": "progressing"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

status: "progressing" means the call connected and TTS is playing. That is it — your AI agent just made a phone call.

Check call status 

GROUPCALL_ID="fc2b8e74-cdab-435c-827b-cc3c6e59ffc1"
curl "https://api.voipbin.net/v1.0/groupcalls/$GROUPCALL_ID?accesskey=$VOIPBIN_KEY"
Enter fullscreen mode Exit fullscreen mode

Call states: dialing → ringing → progressing → hangup

Step 5 (Optional): Add an AI Voice Agent

Want two-way conversation instead of one-way TTS? You can attach a GPT or Gemini model to handle the dialogue.

Create an AI configuration 

curl -X POST "https://api.voipbin.net/v1.0/ais?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-ai",
    "detail": "My AI voice agent",
    "engine_model": "openai.gpt-4o-mini",
    "engine_key": "<YOUR_OPENAI_API_KEY>",
    "init_prompt": "You are a helpful voice assistant. Keep responses short and clear.",
    "tts_type": "openai",
    "stt_type": "openai",
    "stt_language": "en-US"
  }'
Enter fullscreen mode Exit fullscreen mode

Supported models: openai.gpt-4o-mini, openai.gpt-4o, gemini.gemini-2.0-flash, gemini.gemini-2.5-flash, grok.grok-3-mini

Make a call with the AI agent 

curl -X POST "https://api.voipbin.net/v1.0/calls?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"source\": { \"type\": \"tel\", \"target\": \"$VOIPBIN_NUMBER\" },
    \"destinations\": [{ \"type\": \"extension\", \"target_name\": \"quickstart-phone\" }],
    \"actions\": [
      {
        \"type\": \"ai_talk\",
        \"option\": {
          \"assistance_type\": \"ai\",
          \"assistance_id\": \"<YOUR_AI_ID>\",
          \"duration\": 300
        }
      }
    ]
  }"
Enter fullscreen mode Exit fullscreen mode

Common Errors

Status Cause Fix
401 on signup Using /v1.0/auth/signup Use https://api.voipbin.net/auth/signup (no version prefix)
400 on signup Missing accepted_tos or email Add "accepted_tos": true and a valid email
400 on extension extension value already taken Use a timestamp: "qs-$(date +%s)"
200 {} on signup Email already registered Use a different email
401 on API calls Wrong accesskey Check your $VOIPBIN_KEY value

What's Next

Feature Endpoint What it gives you
Reusable flows POST /v1.0/flows Save and reuse call logic
Call recording POST /v1.0/calls/{id}/recording_start Record ongoing calls
Real-time transcription transcribe_start action + WebSocket Live speech-to-text
Inject TTS mid-call POST /v1.0/speakings/{id}/say Speak into an active call
Buy a real number GET /v1.0/available_numbers?country_code=US PSTN numbers
Outbound campaigns POST /v1.0/campaigns Bulk automated calling

Receive events (webhook or WebSocket):

# Set a webhook
curl -X PUT "https://api.voipbin.net/v1.0/customer?accesskey=$VOIPBIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_method": "POST", "webhook_uri": "https://your-server.com/events"}'

# Or connect via WebSocket
# wss://api.voipbin.net/v1.0/ws?accesskey=<VOIPBIN_KEY>
Enter fullscreen mode Exit fullscreen mode

Resources

API Docs https://api.voipbin.net/redoc/
OpenAPI spec https://api.voipbin.net/openapi.json
Detailed docs https://api.voipbin.net/docs/
Admin console https://admin.voipbin.net
Go SDK https://github.com/voipbin/voipbin-go
MCP server uvx voipbin-mcp
Website https://voipbin.net

Top comments (0)