{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hypamoon-com/json-schema/hypamoon-com-call-timeline-schema.json",
  "title": "CallTimeline",
  "description": "The timeline of a call: its legs, its events, the outcome and who answered.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hypamoon-com-openapi.json#/components/schemas/CallTimeline",
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "format": "uuid",
      "description": "The call you asked for."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "answered",
        "missed",
        "no_answer",
        "voicemail",
        "assistant",
        "in_progress",
        "failed",
        "unknown"
      ],
      "description": "How the call went, the same way the portal says it: answered, missed (inbound and nobody picked up), no_answer (outbound and nobody picked up), voicemail, assistant (the voice AI handled it), in_progress, failed or unknown."
    },
    "answered_by": {
      "anyOf": [
        {
          "anyOf": [
            {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "number"
                    },
                    "number": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The number the call was forwarded to, in E.164."
                    }
                  },
                  "required": [
                    "type",
                    "number"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "device"
                    },
                    "user_id": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The member whose app or web phone it was (the user_id from list_members), or null when it is not known."
                    }
                  },
                  "required": [
                    "type",
                    "user_id"
                  ],
                  "additionalProperties": false
                }
              ],
              "description": "Where a leg went: a phone number, or the app or web phone of a member."
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "assistant"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "Who on your side picked up: the first forward that was answered, else the assistant when it handled the call, else null."
    },
    "legs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "leg_id": {
            "type": "string",
            "format": "uuid",
            "description": "The id of this leg. For the primary leg and a forward to a number this is also a call id in GET /calls."
          },
          "role": {
            "type": "string",
            "enum": [
              "primary",
              "forward"
            ],
            "description": "primary: the caller (inbound) or the person called (outbound). forward: a forward by the call plan or a transfer."
          },
          "direction": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "inbound",
              "outbound",
              null
            ],
            "description": "The direction of this leg."
          },
          "target": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "number"
                      },
                      "number": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The number the call was forwarded to, in E.164."
                      }
                    },
                    "required": [
                      "type",
                      "number"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "device"
                      },
                      "user_id": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The member whose app or web phone it was (the user_id from list_members), or null when it is not known."
                      }
                    },
                    "required": [
                      "type",
                      "user_id"
                    ],
                    "additionalProperties": false
                  }
                ],
                "description": "Where a leg went: a phone number, or the app or web phone of a member."
              },
              {
                "type": "null"
              }
            ],
            "description": "Where a forward went. Null for the primary leg."
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "The status of this leg, like the status of a call."
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this leg started ringing."
          },
          "answered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this leg was answered."
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this leg ended."
          },
          "hangup_cause": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why this leg ended, as reported by the carrier, like normal_clearing or timeout."
          }
        },
        "required": [
          "leg_id",
          "role",
          "direction",
          "target",
          "status",
          "started_at",
          "answered_at",
          "ended_at",
          "hangup_cause"
        ],
        "additionalProperties": false,
        "description": "One leg of a call."
      },
      "description": "The legs, primary first, then the forwards oldest first."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "call.started",
              "call.answered",
              "call.ended",
              "forward.started",
              "forward.answered",
              "forward.ended"
            ],
            "description": "call.started, call.answered (the platform picked up; with a call plan it always does first), call.ended, and per forward forward.started, forward.answered (someone picked up there) and forward.ended."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened."
          },
          "leg_id": {
            "type": "string",
            "format": "uuid",
            "description": "The leg it happened on (legs[].leg_id)."
          },
          "hangup_cause": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only on call.ended and forward.ended."
          }
        },
        "required": [
          "type",
          "occurred_at",
          "leg_id"
        ],
        "additionalProperties": false
      },
      "description": "What happened, oldest first."
    }
  },
  "required": [
    "call_id",
    "outcome",
    "answered_by",
    "legs",
    "events"
  ],
  "additionalProperties": false
}