Skip to content
Teler Docs

Call events

Call events fire as a call moves through its lifecycle. Use them to update your CRM, log call metadata, or trigger downstream automation.

Every event body’s shape depends on the webhook version pinned on the owning Voice App or SIP Trunk. Each payload below has a version toggle: pick your version once and every example on this page switches to match. Field names change across versions; the API versioning page has the full rename table.

Lifecycle

Section titled “Lifecycle”

Multi-leg operations like dial also emit leg.created → leg.answered → leg.completed on each participant leg. These per-leg events are 2026-06-01-only.

call.initiated

Section titled “call.initiated”

Fires the moment Teler creates the call, before the callee’s phone rings.

{
  "id":           "evt_...",
  "type":         "call.initiated",
  "api_version":  "2026-06-01",
  "occurred_at":  "2026-06-01T11:30:45.100Z",
  "account_id":   "acc_...",
  "voice_app_id": "va_...",
  "sip_trunk_id": null,
  "call_id":      "cs_...",
  "leg_id":       "cl_...",
  "data": {
    "call_id":    "cs_...",
    "from":       "+91XXXXXXXXXX",
    "to":         "+91XXXXXXXXXX",
    "direction":  "outbound",
    "start_time": "2026-06-01T11:30:45.100Z"
  },
  "previous_attributes": null
}

call.answered

Section titled “call.answered”

Fires when the called party picks up. Not delivered if the call fails before answer.

{
  "id":           "evt_...",
  "type":         "call.answered",
  "api_version":  "2026-06-01",
  "occurred_at":  "2026-06-01T11:30:48.412Z",
  "account_id":   "acc_...",
  "voice_app_id": "va_...",
  "sip_trunk_id": null,
  "call_id":      "cs_...",
  "leg_id":       "cl_...",
  "data": {
    "call_id":     "cs_...",
    "from":        "+91XXXXXXXXXX",
    "to":          "+91XXXXXXXXXX",
    "direction":   "outbound",
    "start_time":  "2026-06-01T11:30:45.100Z",
    "answered_at": "2026-06-01T11:30:48.412Z"
  },
  "previous_attributes": null
}

The v1 field is answered_at; legacy uses answer_time.

call.completed

Section titled “call.completed”

Fires when an answered call ends normally.

{
  "id":           "evt_...",
  "type":         "call.completed",
  "api_version":  "2026-06-01",
  "occurred_at":  "2026-06-01T11:32:18.501Z",
  "account_id":   "acc_...",
  "voice_app_id": "va_...",
  "sip_trunk_id": null,
  "call_id":      "cs_...",
  "leg_id":       "cl_...",
  "data": {
    "call_id":          "cs_...",
    "from":             "+91XXXXXXXXXX",
    "to":               "+91XXXXXXXXXX",
    "direction":        "outbound",
    "start_time":       "2026-06-01T11:30:45.100Z",
    "ended_at":         "2026-06-01T11:32:18.501Z",
    "duration_seconds": 90,
    "reason":           "normal",
    "ended_by":         "callee"
  },
  "previous_attributes": null
}

Legacy → v1 field renames: hangup_time → ended_at, duration → duration_seconds, hangup_source → ended_by. New v1 field: reason.

call.failed

Section titled “call.failed”

Fires when a call cannot be completed. Replaces call.completed for unsuccessful calls.

{
  "id":           "evt_...",
  "type":         "call.failed",
  "api_version":  "2026-06-01",
  "occurred_at":  "2026-06-01T11:30:55.220Z",
  "account_id":   "acc_...",
  "voice_app_id": "va_...",
  "sip_trunk_id": null,
  "call_id":      "cs_...",
  "leg_id":       "cl_...",
  "data": {
    "call_id":          "cs_...",
    "from":             "+91XXXXXXXXXX",
    "to":               "+91XXXXXXXXXX",
    "direction":        "outbound",
    "start_time":       "2026-06-01T11:30:45.100Z",
    "ended_at":         "2026-06-01T11:30:55.220Z",
    "duration_seconds": 0,
    "reason":           "no_answer",
    "ended_by":         "system",
    "failure": {
      "reason":      "no_answer",
      "code":        487,
      "description": "Callee did not answer before timeout"
    }
  },
  "previous_attributes": null
}

Per-leg events

Section titled “Per-leg events”
2026-06-01

Multi-leg operations like dial fire these events on each participant leg. Envelope leg_id identifies the leg.

leg.created:

{
  "type": "leg.created",
  "leg_id": "cl_...",
  "data": {
    "role":          "dial_target",
    "direction":     "outbound",
    "from":          "+14155550000",
    "to":            "+14155550123",
    "parent_leg_id": null
  }
}

leg.answered:

{
  "type": "leg.answered",
  "leg_id": "cl_...",
  "data": {
    "answered_at": "2026-06-01T11:30:48.412Z"
  }
}

leg.completed:

{
  "type": "leg.completed",
  "leg_id": "cl_...",
  "data": {
    "ended_at":         "2026-06-01T11:32:18.501Z",
    "reason":           "normal",
    "ended_by":         null,
    "duration_seconds": 87
  }
}

reason values: normal, no_answer, busy, canceled, unreachable, rejected, flow_error, system_failure. A failure object is included when the leg ends abnormally.

Timestamps

Section titled “Timestamps”

All timestamps are ISO-8601 UTC strings (e.g. "2026-06-01T11:30:45.100Z"). Fields may be absent when they don’t apply; treat missing as unset, not as falsy.

Next steps

Section titled “Next steps”
Event envelope The 2026-06-01 wrapper shared by every event on this page.
API versioning 2025-08-01 vs 2026-06-01 wire format and the full field-rename table.
Signing & verification HMAC-SHA256 signature verification.