CallState

View as Markdown

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.

node_id
stringRequired

ID for the node this call is on.

call_id
stringRequired

ID for the call.

tag
string[]

Client data this call is tagged with.

device
objectRequired

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

parent
object

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

peer
object

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

call_state
stringRequired

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

start_time
number

The start time of the call in milliseconds since epoch.

answer_time
number

The time the call was answered in milliseconds since epoch.

end_time
number

The time the call ended in milliseconds since epoch.

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:

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5// Build a device with call state webhook configuration
6const devices = new Voice.DeviceBuilder()
7 .add(Voice.DeviceBuilder.Phone({
8 to: "+1yyyyyyyyyy",
9 from: "+1xxxxxxxxxx",
10 timeout: 30,
11 callStateUrl: "https://your-server.com/call-state-webhook",
12 callStateEvents: ["created", "ringing", "answered", "ended"],
13 maxPricePerMinute: 0.50
14 }));
15
16// Dial using the device configuration
17const call = await client.voice.dial(devices);

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

1import express from "express";
2
3const app = express();
4app.use(express.json());
5
6app.post("/call-state-webhook", (req, res) => {
7 const { event_type, timestamp, project_id, space_id, params } = req.body;
8
9 console.log("Event type:", event_type); // "calling.call.state"
10 console.log("Project ID:", project_id);
11 console.log("Call ID:", params.call_id);
12 console.log("Call state:", params.call_state);
13 console.log("Device:", params.device);
14
15 switch (params.call_state) {
16 case "created":
17 console.log("Call created at:", params.start_time);
18 break;
19 case "ringing":
20 console.log("Call is ringing");
21 break;
22 case "answered":
23 console.log("Call answered at:", params.answer_time);
24 break;
25 case "ending":
26 console.log("Call is ending");
27 break;
28 case "ended":
29 console.log("Call ended at:", params.end_time);
30 break;
31 }
32
33 res.status(200).send("OK");
34});
35
36app.listen(3000);

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