← Back to Documentation

Calls

Initiate outbound calls, handle inbound routing, and monitor live call state. Aployee manages telephony so you can focus on your product.

Outbound Calls

Start an outbound call by POSTing to /v1/calls:

Terminal
curl https://api.aployee.com/v1/calls \
  -H "Authorization: Bearer $APLOYEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_xyz789",
    "to": "+15551234567",
    "from": "+15559876543",
    "initial_state": {
      "customer_id": "cust_12345",
      "campaign": "renewal_outreach"
    }
  }'

Request Fields

  • assistant_id - Which assistant handles the call
  • to - Destination phone number (E.164 format)
  • from - (Optional) Caller ID to display
  • initial_state - (Optional) State to pass to webhooks

The call begins immediately. You receive a call ID to track status:

Response
{
  "id": "call_abc123",
  "assistant_id": "asst_xyz789",
  "status": "initiated",
  "to": "+15551234567",
  "from": "+15559876543",
  "created_at": "2024-01-15T10:30:00Z"
}

Call Status

Calls progress through these statuses:

StatusDescription
initiatedCall request received, dialing
ringingPhone is ringing on the other end
in_progressCall connected, conversation active
completedCall ended normally
failedCall failed (busy, no answer, error)
transferredCall transferred to another number

Get Call Details

Retrieve full call information including transcript and final state:

Terminal
# Get call details
curl https://api.aployee.com/v1/calls/call_abc123 \
  -H "Authorization: Bearer $APLOYEE_KEY"

# Response
{
  "id": "call_abc123",
  "assistant_id": "asst_xyz789",
  "status": "completed",
  "to": "+15551234567",
  "from": "+15559876543",
  "started_at": "2024-01-15T10:30:05Z",
  "ended_at": "2024-01-15T10:35:42Z",
  "duration_seconds": 337,
  "transcript": [
    { "role": "assistant", "content": "Hi, this is Alex from Acme Corp..." },
    { "role": "user", "content": "Oh hi, I was actually meaning to call you..." }
  ],
  "summary": "Customer confirmed renewal. Follow-up scheduled for next week.",
  "final_state": {
    "customer_id": "cust_12345",
    "outcome": "renewal_confirmed",
    "follow_up_date": "2024-01-22"
  }
}

Live Call State

During an active call, monitor real-time state:

Terminal
# Get live call state during an active call
curl https://api.aployee.com/v1/calls/call_abc123/live-state \
  -H "Authorization: Bearer $APLOYEE_KEY"

# Response
{
  "call_id": "call_abc123",
  "status": "in_progress",
  "duration_seconds": 45,
  "transcript": [
    { "role": "assistant", "content": "How can I help you today?", "timestamp": "2024-01-15T10:30:10Z" },
    { "role": "user", "content": "I need to check my order status", "timestamp": "2024-01-15T10:30:15Z" }
  ],
  "current_state": {
    "customer_id": "cust_12345",
    "intent": "order_status"
  },
  "reasoning_status": {
    "active": true,
    "started_at": "2024-01-15T10:30:16Z"
  }
}

Live State Fields

  • transcript - Real-time conversation transcript
  • current_state - Latest state from webhook/MCP
  • reasoning_status - Whether async reasoning is running

List Calls

Query your call history with filters:

Terminal
# List calls with filters
curl "https://api.aployee.com/v1/calls?assistant_id=asst_xyz789&status=completed&limit=10" \
  -H "Authorization: Bearer $APLOYEE_KEY"

Filter Parameters

  • assistant_id - Filter by assistant
  • status - Filter by status
  • from_date / to_date - Date range
  • limit / offset - Pagination

Inbound Calls

To receive inbound calls:

  1. Provision a phone number from your Aployee dashboard
  2. Assign the number to an assistant
  3. Configure any routing rules (time-based, IVR menu, etc.)
  4. Calls to that number are handled by your assistant automatically

Each inbound call creates a call record just like outbound calls, so you can track and analyze them the same way.

Transfers

Transfer calls to human agents or other numbers:

  • Via webhook: Return { "action": "transfer", "target": "+15551234567" }
  • Via escalation rules: Configure triggers in assistant settings
  • User-initiated: User says "transfer me to a human"

Transfers are warm by default - context is preserved for the receiving party.

Next steps