CallState

Payload for call state events that are triggered by the change in state of an active Relay-controlled call.

Obtain instances of this state Callback request by including a call_state_url parameter when starting a call with one of the following methods:

Parameters

event_type

stringrequired

The value will be "calling.call.state".

event_channel

stringrequired

ID for the event channel on which these room session's events are reported.

timestamp

numberrequired

Time of the event.

space_id

stringrequired

ID for the SignalWire space associated with the call.

project_id

stringrequired

ID for the project associated with the call.

params

objectrequired

Event-specific parameters. This object contains the following fields.

params.node_id

stringrequired

ID for the node this call is on.

params.call_id

stringrequired

ID for the call.

params.tag

string[]

Client data this call is tagged with.

params.device

objectrequired

Protocol-specific connection information including the device type, from_number, and to_number.

params.parent

object

Information on the call that created this call including the parent device_type, node_id, and call_id.

params.peer

object

Information on the peer call this call is actively connected with including the peer node_id and call_id.

params.call_state

stringrequired

The current state that triggered this event. Possible values are "created", "ringing", "answered", "ending", and "ended".

params.start_time

number

The start time of the call in milliseconds since epoch.

params.answer_time

number

The time the call was answered in milliseconds since epoch.

params.end_time

number

The time the call ended in milliseconds since epoch.

params.created_by

string

The method associated with this call state change. Possible values are "dial", "connect", and "receive".

Example

To receive call state webhook notifications, specify a callStateUrl when building your device configuration with Voice.DeviceBuilder.Phone:

import { SignalWire, Voice } from "@signalwire/realtime-api";

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

// Build a device with call state webhook configuration
const devices = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Phone({
    to: "+1yyyyyyyyyy",
    from: "+1xxxxxxxxxx",
    timeout: 30,
    callStateUrl: "https://your-server.com/call-state-webhook",
    callStateEvents: ["created", "ringing", "answered", "ended"],
    maxPricePerMinute: 0.50
  }));

// Dial using the device configuration
const call = await client.voice.dial(devices);

Your webhook endpoint will receive POST requests with the CallState payload. Example Express.js handler:

import express from "express";

const app = express();
app.use(express.json());

app.post("/call-state-webhook", (req, res) => {
  const { event_type, timestamp, project_id, space_id, params } = req.body;

  console.log("Event type:", event_type); // "calling.call.state"
  console.log("Project ID:", project_id);
  console.log("Call ID:", params.call_id);
  console.log("Call state:", params.call_state);
  console.log("Device:", params.device);

  switch (params.call_state) {
    case "created":
      console.log("Call created at:", params.start_time);
      break;
    case "ringing":
      console.log("Call is ringing");
      break;
    case "answered":
      console.log("Call answered at:", params.answer_time);
      break;
    case "ending":
      console.log("Call is ending");
      break;
    case "ended":
      console.log("Call ended at:", params.end_time);
      break;
  }

  res.status(200).send("OK");
});

app.listen(3000);

tip

For real-time call state changes within your SDK application without webhooks, use the onStateChanged event on the Call object instead.

Parameters​

Example​

Parameters

Example