CallResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hail-so/json-schema/hail-so-call-response-schema.json",
  "title": "CallResponse",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hail-so-openapi.json#/components/schemas/CallResponse",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "title": "Id",
      "description": "Unique identifier for this call."
    },
    "organization_id": {
      "type": "string",
      "format": "uuid",
      "title": "Organization Id",
      "description": "Organization that placed or received this call."
    },
    "from_e164": {
      "type": "string",
      "title": "From E164",
      "description": "Caller-id phone number used, E.164 format."
    },
    "to_e164": {
      "type": "string",
      "title": "To E164",
      "description": "Recipient phone number, E.164 format."
    },
    "direction": {
      "type": "string",
      "enum": [
        "outbound",
        "inbound"
      ],
      "title": "Direction",
      "description": "'outbound' for calls Hail placed, 'inbound' for calls received."
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agent Id",
      "description": "Agent that answered (inbound) or placed (outbound) this call. Null when the call was placed with an inline system_prompt."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "dialing",
        "ringing",
        "in_progress",
        "completed",
        "failed",
        "busy",
        "no_answer",
        "canceled"
      ],
      "title": "Status",
      "description": "Current call-progress state: 'queued', 'dialing', 'ringing', 'in_progress', or one of the terminal states 'completed', 'failed', 'busy', 'no_answer', 'canceled'."
    },
    "end_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Reason",
      "description": "Machine-readable reason the call reached a terminal status (e.g. 'normal_hangup', 'user_rejected', 'sip_trunk_failure'). Null while the call is still in progress."
    },
    "provider_call_sid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Call Sid",
      "description": "The telephony provider's identifier for this call leg, if assigned."
    },
    "livekit_room": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Livekit Room",
      "description": "Name of the LiveKit room hosting this call's media session, if one was created."
    },
    "initial_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Initial Prompt",
      "description": "The system_prompt this call was created with, if any."
    },
    "recording_enabled": {
      "type": "boolean",
      "title": "Recording Enabled",
      "description": "Whether the recording-enabled call rate applies, regardless of capture outcome.",
      "default": false
    },
    "recording_status": {
      "type": "string",
      "title": "Recording Status",
      "description": "disabled, requested, starting, recording, processing, ready, unavailable, failed, or erased.",
      "default": "disabled"
    },
    "recording_duration_ms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Recording Duration Ms",
      "description": "Duration of captured audio, independent of billed call duration."
    },
    "recording_s3_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Recording S3 Key",
      "description": "Internal storage key for the call recording. Not a directly fetchable URL."
    },
    "requested_at": {
      "type": "string",
      "format": "date-time",
      "title": "Requested At",
      "description": "When the call was requested, ISO 8601 timestamp."
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Started At",
      "description": "When dialing began, ISO 8601 timestamp. Null until the call starts."
    },
    "answered_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Answered At",
      "description": "When the callee answered, ISO 8601 timestamp. Null if never answered."
    },
    "ended_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ended At",
      "description": "When the call ended, ISO 8601 timestamp. Null while still in progress."
    },
    "failure_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Failure Message",
      "description": "Human-readable explanation for a failed call. Null for other statuses."
    }
  },
  "type": "object",
  "required": [
    "id",
    "organization_id",
    "from_e164",
    "to_e164",
    "direction",
    "status",
    "end_reason",
    "provider_call_sid",
    "livekit_room",
    "initial_prompt",
    "recording_s3_key",
    "requested_at",
    "started_at",
    "answered_at",
    "ended_at"
  ]
}