API Reference

Complete REST API documentation for authentication and call management

Calls API

Manage voice calls through the Kalem.me API. Create, retrieve, and control your automated voice interactions.

Quick Reference

Base Endpoint

https://kalem.me/api/v1/call

Supported Formats

JSON only

List Calls

Retrieve a paginated list of your calls with optional filtering.

GET /api/v1/call

Example Request

curl -X GET "https://kalem.me/api/v1/call?page=1&per_page=10&status=completed" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": 101,
      "call_id": "call_xyz789abc123",
      "account_id": 1,
      "user_id": 2,
      "agent_id": 5,
      "from": "+1234567890",
      "from_name": "AI Sales Assistant",
      "to": "+19876543210",
      "record": true,
      "processed": true,
      "direction": "outbound",
      "answer_at": "2025-08-06T14:15:30.000000Z",
      "hangup_at": "2025-08-06T14:18:45.000000Z",
      "duration": "00:03:15",
      "call_recording": "https://kalem.me/api/v1/recordings/call_xyz789abc123",
      "trunk_id": "trunk_us_east",
      "ai_data": {
        "customer_name": "Sarah Johnson",
        "customer_id": "cust_789012",
        "account_type": "premium",
        "previous_purchases": ["laptop", "wireless_mouse"],
        "inquiry_type": "product_recommendation",
        "budget_range": "$800-1200",
        "call_outcome": "interested",
        "follow_up_needed": true,
        "scheduled_demo": "2025-08-08T10:00:00Z"
      },
      "created_at": "2025-08-06T14:15:00.000000Z",
      "updated_at": "2025-08-06T14:19:00.000000Z"
    }
  ],
  "links": {
    "first": "https://kalem.me/api/v1/call?page=1",
    "last": "https://kalem.me/api/v1/call?page=5",
    "next": "https://kalem.me/api/v1/call?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://kalem.me/api/v1/call",
    "per_page": 10,
    "to": 10,
    "total": 47
  }
}

💡 Understanding ai_data Field

The ai_data field is crucial for providing context to your AI agent. This data helps create more personalized and intelligent conversations.

✅ Recommended Data Types

  • • Customer Information: name, ID, account type
  • • Purchase History: previous orders, preferences
  • • Support Context: ticket history, issues
  • • Campaign Data: source, campaign type
  • • Business Context: subscription level, notes

🎯 Benefits

  • • More personalized conversations
  • • Contextually aware responses
  • • Better customer experience
  • • Higher conversion rates
  • • Reduced call handling time

Create Call

Initiate a new voice call with your configured AI agent.

POST /api/v1/call

Example Request

curl -X POST "https://kalem.me/api/v1/call" \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 5,
    "from": "+1234567890",
    "to": "+19876543210",
    "from_name": "AI Sales Assistant",
    "record": true,
    "webhook_url": "https://your-webhook.com/call-events",
    "ai_data": {
      "customer_name": "Sarah Johnson",
      "customer_id": "cust_789012",
      "account_type": "premium",
      "previous_purchases": ["laptop", "wireless_mouse"],
      "inquiry_type": "product_recommendation",
      "budget_range": "$800-1200",
      "preferred_contact_time": "evening",
      "notes": "Interested in upgrading to latest model laptop"
    }
  }'

Example Response

{
  "id": 123,
  "call_id": "call_abc123def456",
  "account_id": 1,
  "user_id": 2,
  "agent_id": 5,
  "from": "+1234567890",
  "from_name": "AI Sales Assistant",
  "to": "+19876543210",
  "record": true,
  "processed": false,
  "direction": "outbound",
  "answer_at": null,
  "hangup_at": null,
  "duration": "00:00:00",
  "call_recording": null,
  "trunk_id": null,
  "ai_data": {
    "customer_name": "Sarah Johnson",
    "customer_id": "cust_789012",
    "account_type": "premium",
    "previous_purchases": ["laptop", "wireless_mouse"],
    "inquiry_type": "product_recommendation",
    "budget_range": "$800-1200",
    "preferred_contact_time": "evening",
    "notes": "Interested in upgrading to latest model laptop"
  },
  "created_at": "2025-08-06T15:30:00.000000Z",
  "updated_at": "2025-08-06T15:30:00.000000Z"
}

Get Call Details

Retrieve detailed information about a specific call.

GET /api/v1/call/{call_id}

Example Request

curl -X GET "https://kalem.me/api/v1/call/call_abc123" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

Call Status Reference

Understanding call status values and their meanings.

Status Description
queued Call is waiting to be initiated
ringing Call is being placed, phone is ringing
answered Call was answered and conversation is active
failed Call failed to connect
cancelled Call was cancelled before completion