Events & lifecycle - ApifyCloud Docs

The widget emits a stream of lifecycle events during a call. You can consume them in three places:

Parent page — via postMessage from the iframe (see Embedding)
Custom code — via window.c2c.on(name, handler) inside injected scripts (see Custom code)
Integrations — forwarded server-side to your webhooks (see Integrations)

Common payload shape

Every event carries a common envelope:

{
  name: string;            // e.g. "call_started"
  data: {                  // event-specific fields (see below)
    ...
    context: {             // URL context — always included
      [key: string]: string;
    };
  };
  timestamp: string;       // ISO 8601
}

The context object is the URL context you passed to the widget (see Embedding — URL context). It’s attached to every event so downstream systems always have correlation data like orderId or customerTier.

Event catalogue

`widget_loaded`

Fired once, when the widget finishes initial render. Useful to verify the widget is actually present on pages where it should be, or to fire a pageview-equivalent in analytics.

{
  "name": "widget_loaded",
  "data": {
    "isPreview": false,
    "context": { "orderId": "A-12345" }
  }
}

isPreview — true when rendered inside the Call Studio preview, false in production.

`call_started`

Fired when the user taps the call button and the outbound call request has been accepted.

{
  "name": "call_started",
  "data": {
    "destinationId": "dest_xyz",
    "routingKey": null,
    "hasFormValues": false,
    "context": { "orderId": "A-12345" }
  }
}

destinationId — the profile the call is routed to, or null for the default profile.
routingKey — routing key supplied via the session, if any.
hasFormValues — true if the pre-call form was used.

`call_ended`

Fired when the call is terminated cleanly — either the visitor tapped hang-up or the agent (or IVR / queue) hung up. This is the most important event for most integrations. If the call fails because of a network or media issue, you get call_error instead — call_ended is not emitted on error paths.

{
  "name": "call_ended",
  "data": {
    "duration": 187,
    "reason": "user_hangup",
    "context": { "orderId": "A-12345" }
  }
}

duration — call length in seconds. Measured from the moment the visitor started the call.
reason — one of:

Value	Meaning
`user_hangup`	The visitor tapped hang-up
`remote_hangup`	The agent, IVR, or queue ended the call

`call_error`

Fired when the call fails to start, or when it drops mid-call because of a media failure. A spike in these events is your early warning sign that something is wrong on the infrastructure or network side.

{
  "name": "call_error",
  "data": {
    "errorCode": "media_failed",
    "errorMessage": "Media connection lost",
    "context": { "orderId": "A-12345" }
  }
}

errorCode — machine-readable label. Currently one of:
- media_failed — the WebRTC media connection dropped
- other codes may surface depending on the failure path; always check errorMessage for details.
errorMessage — human-readable description.

`survey_submitted`

Fired when the visitor completes the post-call survey.

{
  "name": "survey_submitted",
  "data": {
    "rating": 5,
    "answerCount": 2,
    "hasComment": true,
    "context": { "orderId": "A-12345" }
  }
}

rating — average rating across the visitor’s answers (1–5).
answerCount — how many survey questions the visitor answered.
hasComment — whether the visitor added free-text feedback.

The actual answers and comment text are stored server-side on the call record and are available through the console — they are not included in the event payload to keep events small.

`custom_button_clicked`

Fired when the visitor interacts with a custom button you added in Call Studio.

{
  "name": "custom_button_clicked",
  "data": {
    "label": "Open chat",
    "action": "link",
    "context": { "orderId": "A-12345" }
  }
}

label — the label configured on the button in Call Studio.
action — the action type configured (e.g. link, copy, etc.).

State transitions

The widget has a finite state machine:

idle ──▶ calling ──▶ ended ──▶ survey ──▶ survey_submitted ──▶ closed
              │
              └──▶ error

From → to	Triggers event
`idle` → `calling`	`call_started`
`calling` → `ended`	`call_ended`
`calling` → `error`	`call_error`
`ended` → `survey`	(transition only, no event)
`survey` → `survey_submitted`	`survey_submitted`

Forwarding to your server

Every event above can be forwarded to your webhook endpoints through Integrations. Unlike postMessage or window.c2c.on (both client-only), integrations are delivered server-side with retries and a circuit breaker. See Integrations for setup.

​Common payload shape

​Event catalogue

​widget_loaded

​call_started

​call_ended

​call_error

​survey_submitted

​custom_button_clicked

​State transitions

​Forwarding to your server

​What’s next

Custom code

Integrations

Common payload shape

Event catalogue

`widget_loaded`

`call_started`

`call_ended`

`call_error`

`survey_submitted`

`custom_button_clicked`

State transitions

Forwarding to your server

What’s next