Telephony

​

Overview

• Twilio (fully tested and documented)

• Telnyx
• Plivo
• SignalWire
• Bandwidth
• Vonage

​

Studio Phone Numbers Page

​

Page Layout

​

Left Column: Phone Numbers List (Sidebar)

1. Header
   • Icon: Phone icon (purple background)
   • Title: “Phone Numbers”
   • Add Button: Plus icon (blue, circular, top-right)
2. Search Bar
   • Placeholder: “Search phone numbers…”
   • Icon: Search icon (left side)
   • Filters by:
     • Phone number
     • Inbound agent name
     • Outbound agent name
3. Phone Numbers List
   • Scrollable list of all phone numbers
   • Each number shows:
     • Phone Number (bold, truncated if long)
     • Status Badge (green = active, gray = inactive)
     • Inbound Agent (agent name + mode)
     • Outbound Agent (agent name + mode)
   • Selected State: Blue background with blue border
   • Hover State: Light gray background
4. Action Buttons (per number)
   • Edit Button (pencil icon)
     • Opens edit dialog
     • Edit number details
   • Delete Button (trash icon)
     • Red on hover
     • Requires confirmation

• Phone icon (gray, large)
• Text: “No phone numbers found”
• Action: Click “Add Phone Number” button

​

Right Column: Phone Number Details (Main Content)

• Phone icon (gray, 64x64)
• Text: “Select a phone number” or “No phone numbers”
• Subtext: Instructions
• Add Button: “Add Phone Number” (if no numbers exist)

• Phone Number (large, bold)
• Status Badge (green/gray)
• ID: Internal phone number ID
• Test Call Button: Green “Make Test Call” button
  • Links to /demo-call
  • Opens demo call page

• Title: “Inbound Call Configuration”
• Field: “Inbound Call Agent” dropdown
  • Shows all available agents
  • Format: “Agent Name (mode)”
  • Current selection shown below
• Save: Included in main save button

• Title: “Outbound Call Configuration”
• Field: “Outbound Call Agent” dropdown
  • Shows all available agents
  • Format: “Agent Name (mode)”
  • Current selection shown below
• Save: Included in main save button

• Title: “Call Settings”
• Field 1: “Webhook URL”
  • Input field
  • Copy button (clipboard icon)
  • Placeholder: “https://your-webhook-url.com/webhook”
• Field 2: “Call Recording”
  • Dropdown options:
    • Disabled
    • Record all calls
    • Record with consent

• Location: Below configuration cards
• Text: “Save Agent Assignments”
• Icon: Save icon
• Loading State: Shows spinner, “Saving…”
• Success: Toast notification

​

Add/Edit Phone Number Dialog

• Add: “Add Phone Number”
• Edit: “Edit Phone Number”

• Cancel: Closes dialog, no changes
• Save: Validates and saves number
  • Shows loading spinner
  • Toast on success/error
  • Refreshes list on success

• Phone number must be in E.164 format
• Must start with +
• Minimum 10 digits after +
• Termination URI must be valid URL

​

Delete Phone Number

1. Click trash icon on phone number
2. Confirmation dialog appears:
   • “Are you sure you want to delete phone number +1234567890?”
   • “This action cannot be undone.”
3. Click Confirm or Cancel
4. If confirmed:
   • Calls backend API to delete
   • Removes from local state
   • Shows success toast
   • Selects next number or shows empty state

• Phone number record
• Associated SIP trunks in LiveKit
• Agent assignments
• Call history (preserved in database)

​

Save Agent Assignments

1. Select inbound agent from dropdown
2. Select outbound agent from dropdown
3. Click “Save Agent Assignments”
4. Sends PUT request to backend:
   {
     "phone_number": "+1234567890",
     "inbound_agent_id": "agent_abc123",
     "outbound_agent_id": "agent_def456"
   }
   
5. Shows loading state
6. Success toast: “Agent assignments saved successfully”
7. Refreshes data

• At least one agent must be selected
• Agent must be Pipeline or Realtime architecture
• Text agents cannot be assigned

​

Search & Filter

• Real-time filtering
• Case-insensitive
• Searches:
  • Phone number string
  • Inbound agent name
  • Outbound agent name

• +1202 → Finds all numbers starting with +1202
• Support → Finds numbers with “Support” agent assigned
• Sales → Finds numbers with “Sales” agent assigned

​

Status Badges

• ✅ Phone number added
• ✅ Termination URI set
• ✅ At least one agent assigned (inbound or outbound)
• ✅ SIP credentials configured (for outbound)

​

Keyboard Shortcuts

• N — New phone number
• Ctrl+F — Focus search
• Delete — Delete selected number
• Enter — Save changes

​

Mobile Responsiveness

• Two-column layout (sidebar + main)
• Full configuration cards visible
• All fields accessible

• Sidebar collapses to icons only
• Main content takes full width
• Cards stack vertically

• Sidebar becomes drawer (slide-in)
• Hamburger menu to toggle
• Cards full width
• Simplified form fields

​

Real-Time Updates

• Refreshes when organization changes
• Listens for agentUpdated events
• Manual refresh via reload

• Uses CustomEvent for communication
• Events:
  • phoneNumberAdded
  • phoneNumberUpdated
  • phoneNumberDeleted

​

Error States

• Yellow warning box
• Text: “Please select an organization first”
• Action: Select organization from sidebar

• Toast notification
• Error message from backend
• Retry option

• Inline error messages
• Red border on invalid fields
• Helper text below field

​

Inbound Calling

​

How it works

Customer dials phone number
        │
        ▼
   Carrier (Twilio/Telnyx/etc.)
        │  SIP
        ▼
   LiveKit SIP Server
        │
        ▼
   Voice Agent Runtime
        │
        ▼
   AI Agent joins the call

​

Setup with Twilio

sip:livekit.talkifai.dev:5061;transport=tls

​

Outbound Calling

​

Prerequisites

1. Outbound Trunk: Configure an outbound SIP trunk in your carrier console
2. SIP Credentials: Create SIP username/password for authentication
3. IP ACL: Add your VM’s public IP address to the carrier’s allowed list
4. Phone Number: Add the phone number in TalkifAI Studio with SIP credentials

​

Configure Outbound Calling

​

Via Dashboard

1. Go to Studio → Phone Numbers
2. Select a number with an outbound agent configured
3. Click Make Call
4. Enter the destination number in E.164 format (e.g., +12025550123)

​

Via API

POST /telephony/outbound-call
Content-Type: application/json

{
  "to_number": "+12025550123",
  "from_number": "+1234567890"
}

{
  "success": true,
  "message": "Call initiated successfully",
  "room_name": "outbound_agent_abc123_12025550123_1234567890",
  "agent": {
    "id": "agent_abc123",
    "name": "Sales Agent"
  },
  "from_number": "+1234567890",
  "to_number": "+12025550123"
}

​

Managing Phone Numbers

​

Phone Number Fields

​

Assigning Agents

• Inbound Agent — Handles incoming calls (answered when someone calls this number)
• Outbound Agent — Used for outgoing calls (when calling from this number)

​

Deleting a Phone Number

1. Go to Studio → Phone Numbers
2. Select the phone number
3. Click the Delete button
4. Confirm deletion

​

BYOC (Bring Your Own Carrier)

• Connect your existing Twilio/Telnyx/Plivo accounts
• Use your own SIP trunks and phone numbers
• Pay carriers directly (no markup from TalkifAI)
• Full control over SIP configuration

• SIP trunk from your carrier
• SIP credentials (username/password)
• LiveKit SIP server configured (self-hosted or cloud)

​

Credential Security

• Credentials are encrypted with a FERNET_KEY environment variable
• Encrypted data is stored in the PhoneNumber table (sipPassword field)
• The encryption key is set once during deployment and should never be changed after credentials are saved
• If you lose the FERNET_KEY, all stored credentials will be unrecoverable

• Store your FERNET_KEY in a secure secrets manager
• Never commit the key to version control
• Rotate credentials periodically (not the encryption key)
• Use different credentials for production and development

​

Carrier-Specific Configuration

​

Twilio

• Elastic SIP Trunking
• Phone Numbers
• Credential Lists
• IP ACL
• Geo Permissions

1. Enable Secure Trunking in your trunk’s General Settings
2. Add ;transport=tls to your Origination URI:
   sip:livekit.talkifai.dev:5061;transport=tls
   
3. For outbound trunks, set:
   "transport": "SIP_TRANSPORT_TLS",
   "media_encryption": "SIP_MEDIA_ENCRYPT_REQUIRE"
   

• Go to Voice → Settings → Geo Permissions
• Enable the countries you want to call

​

Telnyx

• Telnyx uses “Outbound Profiles” instead of credential lists
• IP ACL is configured per outbound profile
• Authentication can be IP-based or credential-based

​

SignalWire

​

Troubleshooting

​

API Reference

• Phone Numbers API
• Telephony API

​

Related Guides

• BYOC Setup — Connect your own SIP carrier
• Agent Architecture — Understand Pipeline vs Realtime vs Text
• LiveKit SIP — LiveKit SIP documentation