KallyAI API Integration

KallyAI is an AI phone assistant that makes calls to businesses on behalf of users.

Complete Workflow

When a user asks to make a call:

Step 1: Gather Call Details

Collect from user:

• Phone number to call (required)
• What to accomplish - the task description (required)
• Category: restaurant, clinic, hotel, or general (required)
• For reservations: name, date, time, party size

Step 2: Authenticate User

Use the CLI OAuth flow:

https://api.kallyai.com/v1/auth/cli?redirect_uri=http://localhost:8976/callback

This opens a login page. After authentication, the user is redirected to the localhost callback with tokens:

http://localhost:8976/callback?access_token=<token>&refresh_token=<refresh>&expires_in=3600

Start a local HTTP server to capture the callback and extract the tokens.

Step 3: Make the Call

Once authenticated, call the API:

POST https://api.kallyai.com/v1/calls
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "submission": {
    "task_category": "general",
    "task_description": "Ask about store hours and availability",
    "respondent_phone": "+15551234567",
    "language": "en",
    "call_language": "en"
  },
  "timezone": "America/New_York"
}

Step 4: Report Results

Response contains:

{
  "call_id": "uuid",
  "status": "success",
  "highlights": "They have iPhone 15 for €800, good condition",
  "next_steps": "Call back to arrange pickup"
}

Status values: success, no_answer, busy, failed, voicemail, cancelled

---

CLI Commands Reference

Making Calls

kallyai -p "+15551234567" -t "Reserve a table for 4 at 8pm" \
  --category restaurant \
  --name "John Smith" \
  --party-size 4 \
  --date "2026-01-28" \
  --time "20:00"

| Option | Short | Description | |--------|-------|-------------| | --phone | -p | Phone number (E.164 format) | | --task | -t | What the AI should accomplish | | --category | -c | restaurant, clinic, hotel, general | | --language | -l | en or es | | --name | | Your name (for reservations) | | --business | | Business name | | --party-size | | Party size (restaurants) | | --date | | YYYY-MM-DD | | --time | | HH:MM (24-hour) |

Account & Usage

kallyai --usage        # Show minutes/calls remaining
kallyai --subscription # Show subscription status
kallyai --billing      # Open Stripe billing portal

Call History

kallyai --history              # List recent calls
kallyai --call-info <ID>       # Get call details
kallyai --transcript <ID>      # Get conversation transcript

Authentication

kallyai --login      # Force re-authentication
kallyai --logout     # Clear saved credentials
kallyai --auth-status # Check if logged in

---

Quick Reference

Base URL: https://api.kallyai.com

CLI OAuth URL: https://api.kallyai.com/v1/auth/cli?redirect_uri=http://localhost:8976/callback

Required fields for calls: | Field | Description | |-------|-------------| | task_category | restaurant, clinic, hotel, general | | task_description | What AI should accomplish | | respondent_phone | Phone number in E.164 format (+1234567890) |

Optional fields: | Field | Description | |-------|-------------| | business_name | Name of business | | user_name | Name for reservation | | appointment_date | YYYY-MM-DD | | appointment_time | HH:MM (24-hour) | | party_size | Number of people (1-50) | | language | en or es | | call_language | en or es |

Example Requests

Restaurant reservation:

{
  "submission": {
    "task_category": "restaurant",
    "task_description": "Reserve table for 4 at 8pm",
    "respondent_phone": "+14155551234",
    "business_name": "Italian Bistro",
    "user_name": "John Smith",
    "party_size": 4,
    "appointment_date": "2026-01-28",
    "appointment_time": "20:00"
  },
  "timezone": "America/New_York"
}

Medical appointment:

{
  "submission": {
    "task_category": "clinic",
    "task_description": "Schedule dental checkup",
    "respondent_phone": "+14155551234",
    "user_name": "Jane Doe",
    "time_preference_text": "morning before 11am"
  },
  "timezone": "America/New_York"
}

Common Errors

| Code | HTTP | Action | |------|------|--------| | quota_exceeded | 402 | User needs to upgrade at kallyai.com/pricing | | missing_phone_number | 422 | Ask user for phone number | | emergency_number | 422 | Cannot call 911/emergency services | | country_restriction | 403 | Country not supported |

Security

• Token storage: ~/.kallyai_token.json with 0600 permissions
• CSRF protection: State parameter validation
• Localhost only: OAuth redirects only to localhost/127.0.0.1
• Auto-refresh: Tokens refresh automatically when expired