Voice API

The Voice API enables you to programmatically trigger phone calls that connect your leads to your sales team in under 3 seconds. Perfect for real estate teams and high-velocity sales organizations.

Endpoint

POST https://www.telephony.io/api/voice/trigger-call

Parameters

All parameters are required unless marked as optional.

Parameter	Type	Description
`agentPhone`	string	Phone number of your sales agent (E.164 format: `+61412345678`)
`leadPhone`	string	Phone number of the lead to connect (E.164 format)
`leadName`	string	Name of the lead (used in whisper message to agent)
`source`	string	Optional. Lead source identifier (e.g., "Zillow", "Facebook", "Website Form")
`metadata`	object	Optional. Custom key-value pairs to attach to this call

Example Request

Here's a complete example using cURL:

curl -X POST https://www.telephony.io/api/voice/trigger-call \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentPhone": "+61412345678",
    "leadPhone": "+61498765432",
    "leadName": "Sarah Johnson",
    "source": "Zillow",
    "metadata": {
      "propertyId": "PROP-12345",
      "listingUrl": "https://example.com/property/12345"
    }
  }'

Example with JavaScript

const triggerCall = async () => {
  const response = await fetch('https://www.telephony.io/api/voice/trigger-call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agentPhone: '+61412345678',
      leadPhone: '+61498765432',
      leadName: 'Sarah Johnson',
      source: 'Zillow',
      metadata: {
        propertyId: 'PROP-12345'
      }
    })
  });

  const data = await response.json();
  return data;
};

Response

On success, you'll receive a 200 OK response:

{
  "success": true,
  "callId": "call_9h2k4j8f9s7d6",
  "status": "initiated",
  "agentPhone": "+61412345678",
  "leadPhone": "+61498765432",
  "estimatedConnectTime": "2-3 seconds",
  "creditsUsed": 0.10
}

Response Fields

callId - Unique identifier for this call (use for webhooks and status checks)
status - Current call status (initiated, ringing, connected, completed, failed)
creditsUsed - Initial credits deducted (final charge calculated after call ends)

Call Flow

Agent Called First: We call your agent's phone
Whisper Message: Agent hears "New lead from Zillow: Sarah Johnson. Press 1 to connect."
Lead Connected: After agent presses 1, we connect them to the lead
Conversation: Both parties are now on the call
Recording (Optional): Call is recorded if enabled in dashboard settings

💡 Pro Tip

Set up webhooks to receive real-time updates about call status changes. See Webhooks documentation for details.

Error Responses

Common error scenarios:

Insufficient Credits

{
  "error": {
    "code": "insufficient_credits",
    "message": "Account balance too low. Please add credits to continue."
  }
}

Invalid Phone Number

{
  "error": {
    "code": "invalid_phone_number",
    "message": "Phone number must be in E.164 format (+61...)"
  }
}

Pricing

Voice calls are charged per minute:

Australian landlines: AU$0.08/min
Australian mobiles: AU$0.10/min
International rates vary by destination (see pricing page)

Minimum charge is 1 minute. Partial minutes are rounded up. Both legs of the call (to agent and to lead) are charged.