Calls

Every call a receptionist handles, inbound or outbound, is available through the API: filterable history, full transcripts, recordings, and a structured outcome.

Call history

GET /api/v1/receptionists/:id/calls returns paginated call history for a receptionist.

Query parameters

Parameter	Description
limit	Results per page (1-100, default 20)
cursor	Pagination cursor from the previous response
direction	Filter by inbound or outbound
date_from	Filter calls after this ISO date
date_to	Filter calls before this ISO date

Response

{
  "data": [
    {
      "id": "uuid",
      "direction": "inbound",
      "status": "completed",
      "from": "+12125551234",
      "to": null,
      "customer_name": "Jane Doe",
      "duration_seconds": 180,
      "outcome": "booked",
      "started_at": "2026-03-11T14:30:00Z",
      "ended_at": "2026-03-11T14:33:00Z",
      "has_transcript": true,
      "has_recording": true,
      "booking": {
        "date": "2026-03-15",
        "time": "10:00",
        "service_type": "AC Repair"
      }
    }
  ],
  "has_more": true,
  "cursor": "eyJjcmVhdGVkX2F0Ijo..."
}

Call outcomes

The outcome field takes one of these values:

Outcome	Meaning
completed	Call finished normally
failed	Call failed
abandoned	Caller hung up before the conversation completed
no_answer	The other party did not answer
busy	The line was busy
booked	An appointment was booked on the call
handoff	The call was handed off (callback request)
unknown	Outcome could not be determined

Place an outbound call

POST /api/v1/receptionists/:id/calls initiates an outbound call. Returns 202 Accepted while the call is queued. Always send an Idempotency-Key header; a retry without one would dial twice.

Request body

{
  "to": "+12125551234",
  "customer_name": "Jane Doe",
  "purpose": "appointment_reminder",
  "system_prompt": "You are a...",
  "context": {
    "company_name": "Acme HVAC",
    "business_type": "HVAC",
    "city": "Tampa",
    "appointment_date": "2026-03-15",
    "appointment_time": "10:00 AM",
    "service_type": "AC Repair",
    "custom_instructions": "Ask about the filter size"
  }
}

Only to is required (E.164 format). All other fields are optional.

Response (202 Accepted)

{
  "id": "uuid",
  "status": "queued",
  "to": "+12125551234"
}

Per-call system_prompt override

Pass a system_prompt to completely replace the receptionist's default script for this single call. Useful for running a closer script, a follow-up call, or any custom conversation without creating a separate receptionist.

The optional context object passes structured facts (company name, appointment details, custom instructions) that the AI references during the call.

Call detail: transcript, recording, structured outcome

GET /api/v1/receptionists/:id/calls/:callId returns the full call detail including transcript, recording, booking, and cost.

Response

{
  "id": "uuid",
  "direction": "inbound",
  "status": "completed",
  "from": "+12125551234",
  "to": null,
  "customer_name": "Jane Doe",
  "customer_phone": "+12125551234",
  "duration_seconds": 180,
  "outcome": "booked",
  "started_at": "2026-03-11T14:30:00Z",
  "ended_at": "2026-03-11T14:33:00Z",
  "transcript": [
    { "role": "assistant", "content": "Thank you for calling...", "timestamp": "0.5" },
    { "role": "user", "content": "Hi, I need to schedule...", "timestamp": "3.2" }
  ],
  "transcript_summary": "Customer called to schedule AC repair...",
  "recording_url": "https://...",
  "booking": {
    "confirmation": "BK-20260315-ABC",
    "date": "2026-03-15",
    "time": "10:00",
    "service_type": "AC Repair",
    "address": "123 Main St, Columbus, OH",
    "notes": null
  },
  "cost": {
    "minutes_used": 3,
    "billable": true,
    "within_plan": true
  },
  "summary": "Customer called to schedule AC repair for unit not blowing cold air. Booked for March 15 at 10 AM.",
  "duration_sec": 180,
  "structured_data": {
    "caller_name": "Jane Doe",
    "caller_address": "123 Main St",
    "service_requested": "AC Repair",
    "call_outcome": "booked"
  },
  "customer_data_collected": {
    "name": "Jane Doe",
    "phone": "+12125551234",
    "address": "123 Main St, Columbus, OH 43068",
    "issue_description": "AC not blowing cold air"
  }
}

• transcript is a role-tagged turn list with per-turn timestamps.
• structured_data is the AI's structured extraction of the call (caller name, address, service requested, outcome).
• customer_data_collected carries the contact details the receptionist gathered.

recording_url expires

The recording link may be a presigned URL valid for roughly 30 minutes. Request the call detail again whenever you need a fresh link, and do not store recording_url in your own database.