Phone Number Management & Outbound Calling

This document provides comprehensive documentation for managing phone numbers and making outbound calls through the KrosAI Platform.

Overview

The phone number management system allows users to:

• Request phone numbers for their account

• Configure phone numbers

• Make outbound calls using configured phone numbers

• Monitor call statistics and history

• Manage phone number configurations

Authentication

All endpoints require authentication using either:

• API Key: Authorization: Bearer <your-api-key>

• User Token: Authorization: Bearer <user-jwt-token>

Phone Number Request Flow

1. Request a Phone Number

Endpoint: POST /telephony/phone-number-requests

Description: Submit a request for a phone number. This request will be reviewed by administrators.

Request Body:

{
  "phone_number": "[phone]",
  "provider": "krosai",
  "monthly_cost": 1.00,
  "setup_cost": 0.00,
  "capabilities": {
    "voice": true,
    "sms": false,
    "mms": false
  },
  "purpose": "Customer support calls",
  "expected_volume": "100 calls per month"
}

Response:

{
  "id": "req_123456",
  "user_id": "user_789",
  "phone_number": "[phone]",
  "status": "pending",
  "created_at": "2024-01-15T10:00:00Z",
  "message": "Phone number request submitted successfully"
}

Status Codes:

• 201 Created: Request submitted successfully

• 400 Bad Request: Invalid request data

• 401 Unauthorized: Authentication required

• 409 Conflict: Phone number already requested

2. Check Request Status

Endpoint: GET /telephony/phone-number-requests/{request_id}

Description: Get the current status of a phone number request.

Response:

{
  "id": "req_123456",
  "user_id": "user_789",
  "phone_number": "[phone]",
  "status": "approved",
  "approved_at": "2024-01-16T14:30:00Z",
  "approved_by": "admin_001",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-16T14:30:00Z"
}

Possible Statuses:

• pending: Awaiting admin review

• approved: Request approved, ready for assignment

• rejected: Request denied

• assigned: Phone number assigned to user

Phone Number Configuration

1. Configure a Phone Number

Endpoint: POST /outbound-calls/phone-numbers/{phone_number_id}/configure

Description: Configure a phone number with LiveKit SIP trunks and dispatch rules for making/receiving calls.

Request Body:

{
  "sip_trunk": {
    "name": "Main Outbound Trunk",
    "address": "sip.twilio.com",
    "numbers": ["[phone]"],
    "auth_username": "your_username",
    "auth_password": "your_password",
    "destination_country": "US"
  },
  "dispatch_rule": {
    "rule_name": "Customer Support Agent",
    "room_prefix": "support-",
    "agent_name": "voice-agent"
  }
}

Response:

{
  "message": "Phone number configured successfully",
  "phone_number_id": "pn_123456",
  "phone_number": "[phone]",
  "trunk_created": true,
  "dispatch_rule_created": true
}

Configuration Options:

SIP Trunk Configuration

• name: Human-readable name for the trunk

• address: SIP provider address (e.g., sip.twilio.com)

• numbers: Array of phone numbers associated with this trunk

• auth_username: Authentication username (if required)

• auth_password: Authentication password (if required)

• destination_country: Two-letter country code for outbound trunks

Dispatch Rule Configuration

• rule_name: Name for the dispatch rule

• room_prefix: Prefix for room names (e.g., support- creates rooms like support-abc123)

• agent_name: Name of the agent to dispatch for calls

2. Get Phone Number Configuration

Endpoint: GET /outbound-calls/phone-numbers/{phone_number_id}/configuration

Description: Retrieve the complete configuration for a phone number.

Response:

{
  "phone_number": {
    "id": "pn_123456",
    "phone_number": "[phone]",
    "status": "active",
    "provider": "twilio",
    "capabilities": {
      "voice": true,
      "sms": false
    }
  },
  "sip_trunks": [
    {
      "id": "trunk_001",
      "livekit_trunk_id": "ST_7CBBAh8Z2hhH",
      "name": "Main Outbound Trunk",
      "type": "outbound",
      "address": "sip.twilio.com",
      "status": "active"
    }
  ],
  "dispatch_rules": [
    {
      "id": "rule_001",
      "livekit_rule_id": "DR_abc123",
      "name": "Customer Support Agent",
      "room_prefix": "support-",
      "agent_name": "voice-agent",
      "status": "active"
    }
  ],
  "configuration_summary": {
    "has_outbound_trunk": true,
    "has_inbound_trunk": false,
    "has_dispatch_rules": true,
    "fully_configured": true
  }
}

3. Remove Phone Number Configuration

Endpoint: DELETE /outbound-calls/phone-numbers/{phone_number_id}/configuration

Description: Remove specific or all configurations from a phone number.

Query Parameters:

• config_type (required): Type of configuration to remove

  • sip_trunk: Remove SIP trunk configuration

  • dispatch_rule: Remove dispatch rule configuration

  • all: Remove all configurations

Response:

{
  "message": "SIP trunk configuration removed",
  "phone_number_id": "pn_123456"
}

4. List User Phone Numbers

Endpoint: GET /outbound-calls/phone-numbers

Description: Get all phone numbers assigned to the current user with their configuration status.

Response:

{
  "phone_numbers": [
    {
      "id": "pn_123456",
      "phone_number": "[phone]",
      "status": "active",
      "provider": "twilio",
      "user_assignment": {
        "id": "upn_001",
        "assigned_at": "2024-01-16T15:00:00Z",
        "capabilities": {
          "voice": true,
          "sms": false
        }
      },
      "configuration_status": {
        "has_outbound_trunk": true,
        "has_inbound_trunk": false,
        "has_dispatch_rules": true,
        "fully_configured": true
      }
    }
  ],
  "total": 1,
  "summary": {
    "fully_configured": 1,
    "partially_configured": 0
  }
}

Outbound Calling

1. Create an Outbound Call

Endpoint: POST /outbound-calls/create

Description: Initiate an outbound call to a phone number. This creates a call record and dispatches an agent via LiveKit.

Request Body:

{
  "phone_number": "[phone]",
  "system_prompt": "You are a customer support agent. Help the customer with their inquiry.",
  "welcome_message": "Hello! Thank you for calling our support line. How can I help you today?"
}

Response:

{
  "call_id": "call_123456",
  "room_name": "outbound-call-abc123-def456",
  "phone_number": "[phone]",
  "caller_id": "[phone]",
  "status": "initiated",
  "agent_config": {
    "system_prompt": "You are a customer support agent..."
  },
  "message": "Outbound call created successfully. Use LiveKit CLI or API to dispatch the agent."
}

Call Configuration Options:

• phone_number: Target phone number to call (with country code)

• system_prompt: Custom system prompt for the AI agent

• welcome_message: Custom welcome message for the call

2. Call Management

Hang Up a Call

Endpoint: POST /outbound-calls/{call_id}/hangup

Description: End an active call by deleting the LiveKit room.

Response:

{
  "message": "Call hung up"
}

Transfer a Call

Endpoint: POST /outbound-calls/{call_id}/transfer

Description: Transfer an ongoing call to another phone number.

Request Body:

{
  "to_number": "[phone]",
  "participant_identity": "[phone]"
}

Response:

{
  "message": "Call transfer initiated"
}

3. Call Information

Get Call Details

Endpoint: GET /outbound-calls/{call_id}/details

Description: Retrieve comprehensive call information including optional transcript and summary.

Query Parameters:

• include_transcript (optional): Include full conversation transcript

• include_summary (optional): Include AI-generated summary of the call

Response:

{
  "call": {
    "id": "call_123456",
    "user_id": "user_789",
    "room_name": "outbound-call-abc123-def456",
    "phone_number": "[phone]",
    "caller_id": "[phone]",
    "status": "completed",
    "started_at": "2024-01-16T15:00:00Z",
    "ended_at": "2024-01-16T15:05:30Z",
    "duration_seconds": 330,
    "conversation_id": "conv_456789"
  },
  "summary": {
    "status": "completed",
    "started_at": "2024-01-16T15:00:00Z",
    "ended_at": "2024-01-16T15:05:30Z",
    "duration_seconds": 330,
    "phone_number": "[phone]",
    "caller_id": "[phone]",
    "conversation_id": "conv_456789"
  },
  "transcript": [
    {
      "role": "agent",
      "content": "Hello! Thank you for calling our support line. How can I help you today?",
      "created_at": "2024-01-16T15:00:05Z"
    },
    {
      "role": "user",
      "content": "Hi, I have a question about my account.",
      "created_at": "2024-01-16T15:00:15Z"
    }
  ],
  "transcript_summary": "The customer called with a question about their account. The agent provided assistance and resolved the inquiry successfully. The call lasted approximately 5.5 minutes and ended with the customer's issue being resolved."
}

Get Call Statistics

Endpoint: GET /outbound-calls/stats

Description: Get aggregate statistics for the authenticated user's outbound calls.

Response:

{
  "total_calls": 25,
  "completed_calls": 20,
  "failed_calls": 2,
  "in_progress_calls": 3,
  "total_duration_seconds": 7200,
  "average_duration_seconds": 360.0,
  "calls_last_24h": 5,
  "calls_last_7d": 18
}

Error Handling

Common Error Responses

400 Bad Request:

{
  "detail": "Phone number not found"
}

401 Unauthorized:

{
  "detail": "Authentication required"
}

403 Forbidden:

{
  "detail": "Not authorized to view this call"
}

404 Not Found:

{
  "detail": "Outbound call not found"
}

500 Internal Server Error:

{
  "detail": "Failed to configure phone number"
}

Rate Limits

• Phone Number Requests: 5 requests per hour per user

• Phone Number Configuration: 10 configurations per hour per user

• Outbound Calls: 100 calls per hour per user

• API Calls: 1000 requests per hour per API key

Best Practices

Phone Number Configuration

1. Use descriptive names for trunks and dispatch rules

2. Set appropriate room prefixes to organize different types of calls

3. Configure both inbound and outbound trunks for full functionality

4. Test configurations with small call volumes before production use

Outbound Calling

1. Provide clear system prompts for consistent agent behavior

2. Use appropriate voice settings for your use case

3. Monitor call quality and adjust settings as needed

4. Implement proper error handling for failed calls

Security

1. Keep authentication credentials secure

2. Use environment variables for sensitive configuration

3. Regularly rotate API keys

4. Monitor usage patterns for unusual activity

Integration Examples

Python Client Example

import requests
import json

# Configure phone number
config_data = {
    "sip_trunk": {
        "name": "Main Trunk",
        "address": "sip.twilio.com",
        "numbers": ["[phone]"],
        "destination_country": "US"
    },
    "dispatch_rule": {
        "rule_name": "Support Agent",
        "room_prefix": "support-",
        "agent_name": "voice-agent"
    }
}

response = requests.post(
    "https://api.krosai.com/outbound-calls/phone-numbers/pn_123456/configure",
    json=config_data,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

# Make outbound call
call_data = {
    "phone_number": "[phone]",
    "system_prompt": "You are a helpful customer support agent.",
    "welcome_message": "Hello! How can I help you today?"
}

response = requests.post(
    "https://api.krosai.com/outbound-calls/create",
    json=call_data,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

cURL Examples

Configure Phone Number:

curl -X POST "https://api.krosai.com/outbound-calls/phone-numbers/pn_123456/configure" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sip_trunk": {
      "name": "Main Trunk",
      "address": "sip.twilio.com",
      "numbers": ["[phone]"],
      "destination_country": "US"
    }
  }'

Make Outbound Call:

curl -X POST "https://api.krosai.com/outbound-calls/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "[phone]",
    "system_prompt": "You are a helpful customer support agent."
  }'

Support

For technical support or questions about phone number management and outbound calling:

• Documentation: https://docs.krosai.com

• API Status: https://status.krosai.com

• Support Email: [e-mail]

• Developer Community: https://community.krosai.com