{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/conduyt-com/json-schema/conduyt-com-dialer-history-page-schema.json",
  "title": "DialerHistoryPage",
  "description": "The `data` member of the response envelope.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/conduyt-com-dialer-api-openapi.yml#/components/schemas/DialerHistoryPage",
  "type": "object",
  "required": [
    "data",
    "meta",
    "stats"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DialerCallListItem"
      }
    },
    "meta": {
      "type": "object",
      "required": [
        "page",
        "per_page",
        "total"
      ],
      "properties": {
        "page": {
          "type": "integer"
        },
        "per_page": {
          "type": "integer"
        },
        "total": {
          "type": "integer"
        },
        "incomplete": {
          "type": "boolean",
          "description": "True only when the NUMBER branch of a search matched more than 5,000 calls and only the newest 5,000 of those were used. Name, agent and transcript matches are never capped; `total` is then a lower bound. Narrow the period."
        },
        "incompleteReason": {
          "type": "string",
          "enum": [
            "number_matches_capped"
          ],
          "description": "Present with `incomplete`; names which branch was capped."
        }
      }
    },
    "stats": {
      "type": "object",
      "required": [
        "total",
        "inbound",
        "outbound"
      ],
      "properties": {
        "total": {
          "type": "integer"
        },
        "inbound": {
          "type": "integer"
        },
        "outbound": {
          "type": "integer"
        },
        "avgTalkSeconds": {
          "type": "integer"
        }
      }
    }
  },
  "$defs": {
    "DialerCallAddedLeg": {
      "type": "object",
      "description": "One number a rep added to a call (#498).",
      "required": [
        "callSid",
        "number",
        "addedAt",
        "joinedAt",
        "leftAt",
        "endReason"
      ],
      "properties": {
        "callSid": {
          "type": "string",
          "description": "The added leg's provider call SID."
        },
        "number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The number dialed (E.164); null only when the add was not recorded."
        },
        "addedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the rep added the number."
        },
        "joinedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the leg answered; null if it never answered or was not recorded."
        },
        "leftAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the leg ended; null while it is on the call or when not recorded."
        },
        "endReason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "removed",
            "completed",
            "busy",
            "no-answer",
            "failed",
            "canceled",
            null
          ],
          "description": "Why the leg ended: removed (the rep dropped it), or the provider's final status; null when unknown."
        }
      }
    },
    "DialerCallListItem": {
      "type": "object",
      "required": [
        "id",
        "direction",
        "fromNumber",
        "toNumber",
        "status",
        "hasRecording",
        "hasVoicemail",
        "createdAt"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "contactId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "userId": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "direction": {
          "type": "string"
        },
        "fromNumber": {
          "type": "string"
        },
        "toNumber": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "duration": {
          "type": [
            "integer",
            "null"
          ]
        },
        "notes": {
          "type": [
            "string",
            "null"
          ]
        },
        "hasRecording": {
          "type": "boolean"
        },
        "recordings": {
          "type": "array",
          "description": "Every recording of the call (#419), in the order they were recorded; [] when hasRecording is false. A received call upgraded into its conference has two: the part before the conference and the conference. hasRecording is unchanged.",
          "items": {
            "$ref": "#/$defs/DialerCallRecording"
          }
        },
        "hasVoicemail": {
          "type": "boolean"
        },
        "voicemailReadAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "voicemailDeletedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "transcriptionText": {
          "type": [
            "string",
            "null"
          ]
        },
        "transcriptionUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "disposition": {
          "type": [
            "string",
            "null"
          ]
        },
        "dncOverride": {
          "type": "boolean"
        },
        "destinationCallSid": {
          "type": [
            "string",
            "null"
          ]
        },
        "transferCallSid": {
          "type": [
            "string",
            "null"
          ]
        },
        "transferStatus": {
          "type": [
            "string",
            "null"
          ]
        },
        "transferTargetNumber": {
          "type": [
            "string",
            "null"
          ]
        },
        "conferenceSid": {
          "type": [
            "string",
            "null"
          ]
        },
        "startedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "endedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "participants": {
          "type": "array",
          "description": "GET /dialer/history only (#498): the numbers a rep added to the call (consult / conference), in the order they were added; empty when nobody was added. Read from the dialer's own records, never the provider. A call from before 2026-10-26 has the number and addedAt only (joinedAt, leftAt and endReason null).",
          "items": {
            "$ref": "#/$defs/DialerCallAddedLeg"
          }
        },
        "contact": {
          "type": [
            "object",
            "null"
          ],
          "description": "The linked contact, or null (no contact, or one the caller may not see)."
        },
        "user": {
          "type": [
            "object",
            "null"
          ],
          "description": "The agent, or null."
        },
        "match": {
          "description": "Present only when `q` was sent. Null when the row matched by a rule that has nothing to show.",
          "oneOf": [
            {
              "$ref": "#/$defs/DialerCallMatch"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "DialerCallMatch": {
      "type": "object",
      "description": "Why this row matched the search `q` (the best match; name, number, agent, transcript in that order).",
      "required": [
        "field"
      ],
      "properties": {
        "field": {
          "type": "string",
          "enum": [
            "name",
            "number",
            "agent",
            "transcript"
          ]
        },
        "snippet": {
          "type": "string",
          "description": "Transcript matches only. About 90 characters around the first hit; a leading or trailing ellipsis marks a cut side."
        },
        "ranges": {
          "type": "array",
          "description": "[start, end) offsets in Unicode CODE POINTS (not UTF-16 units) of the matched words. For a transcript match they index into `snippet`; for a name or agent match they index into the contact's / agent's \"First Last\" name.",
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "items": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    },
    "DialerCallRecording": {
      "type": "object",
      "description": "One recording of a call (#419). Play it through `mediaUrl` (the authenticated media proxy; add `&download=1` to download).",
      "required": [
        "sid",
        "part",
        "startedAt",
        "durationSeconds",
        "primary",
        "mediaUrl"
      ],
      "properties": {
        "sid": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Twilio RecordingSid; null only on a call recorded before the sid was kept."
        },
        "part": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "bridge",
            "conference",
            null
          ],
          "description": "bridge: before the conference; conference: the conference; null: the call was never upgraded into a conference."
        },
        "startedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "durationSeconds": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Seconds, when known; null otherwise."
        },
        "primary": {
          "type": "boolean",
          "description": "The call's own recording (the one transcribed)."
        },
        "mediaUrl": {
          "type": "string",
          "description": "GET /api/v1/dialer/call/{id}/media?type=recording[&sid=...]"
        }
      }
    }
  }
}