Skip to main content
POST
/
telephony
/
outbound-call
Initiate Outbound Call
curl --request POST \
  --url https://api.talkifai.dev/telephony/outbound-call \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "Call initiated successfully",
  "room_name": "outbound_agent_abc123_12025550123_1705320000",
  "agent": {
    "id": "agent_abc123",
    "name": "Sales Agent"
  },
  "from_number": "+12025550100",
  "to_number": "+12025550123"
}

​
Prerequisites

Before making outbound calls:
  1. Register a phone number in Studio → Phone Numbers
  2. Assign an outbound agent to that phone number
  3. Configure SIP trunk with your carrier (Twilio, Telnyx, etc.)
  4. Ensure sufficient credits in your organization account
The agent assigned to from_number must use Pipeline or Realtime architecture. Text-only agents cannot make voice calls and will return a 400 error.

​
How It Works

1. Validate phone numbers (E.164 format)
         │
         ▼
2. Look up from_number in database
         ├── Not found → 404 Error
         └── Found → Get assigned outbound agent
                   │
                   ▼
3. Check agent architecture
         ├── Text agent → 400 Error
         └── Voice agent → Continue
                   │
                   ▼
4. Decrypt SIP credentials
         │
         ▼
5. Generate room: outbound_{agentId}_{toNumber}_{timestamp}
         │
         ▼
6. Initiate SIP call via LiveKit
         ├── Success → Return room_name
         └── Timeout (60s) → 408 Error

​
Phone Number Format

Both numbers must be in E.164 format:
FormatValid?
+12025550123✅
+442071838750✅
2025550123❌ Missing + and country code
1-202-555-0123❌ Contains dashes

Authorizations

​
Authorization
string
header
required

Your TalkifAI API key. Get it from Studio → Settings → API Keys.

Query Parameters

​
to_number
string
required

Destination phone number in E.164 format

​
from_number
string
required

Your registered TalkifAI phone number in E.164 format

Response

Call initiated

​
success
boolean
Example:

true

​
message
string
Example:

"Call initiated successfully"

​
room_name
string
Example:

"outbound_agent_abc123_12025550123_1705320000"

​
agent
object
​
from_number
string
Example:

"+12025550100"

​
to_number
string
Example:

"+12025550123"