Skip to navigation

Events and subscriptions

View as MarkdownOpen in Claude

Relay is event-driven. Once your connection is open, SignalWire pushes events to it as things happen — a call changes state, a recording finishes, a new message or call arrives — so you react to them instead of polling. This page covers the two kinds of events you receive and how to subscribe to the ones that need it.

Two kinds of events

Every event reaches you the same way — pushed over the open socket — but they fall into two groups, and only one of them needs a subscription.

Command-lifecycle events report progress on a command you started. When you begin an action like calling.play or calling.record, its later state changes (playing, finished, and so on) come back as events keyed to the control_id you set on the request. These flow to you automatically — there’s nothing to subscribe to.

Inbound events happen without you asking — an inbound call, an incoming message, a task handed to your client. SignalWire can’t know which connection should handle them, so you first subscribe to a context (below). The clearest example is calling.call.receive, which only reaches clients subscribed to the inbound call’s context.

Every event is documented on its own receive-only channel in the API reference under this tab — calling.call.state, calling.call.receive, messaging.receive, and the rest.

Subscribe to inbound events with contexts

A context is a label you attach to a resource — a phone number, for example — so its inbound events route to the right place. A number configured with the support context sends its inbound calls to whichever connections have subscribed to support.

Subscribe by passing contexts in your signalwire.connect message, at connect time:

{
"version": { "major": 2, "minor": 0, "revision": 0 },
"authentication": {
"project": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"token": "PT9a8b7c6d5e4f3a2b1c..."
},
"contexts": ["support", "sales"]
}

From then on, inbound events for those contexts arrive on your connection. See Authentication for the full connect message.

To change your subscriptions after connecting, send signalwire.receive with the contexts to add, or signalwire.unreceive with the contexts to drop.

Calling events reach a connection only when it was opened with a protocol major version below 4 — send 2.0.0, as the Server SDKs do. Command-lifecycle events such as calling.call.play and calling.call.state are not delivered to a 4.0.0 connection.

What an event looks like

Every event arrives as a JSON-RPC request with the method signalwire.event. Its params is an envelope: event_type names the event, and the inner params holds the payload, whose fields depend on the event. This calling.call.state event is shortened to a few payload fields:

{
"jsonrpc": "2.0",
"id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
"method": "signalwire.event",
"params": {
"event_type": "calling.call.state",
"event_channel": "signalwire_c1d2e3f4a5b6",
"timestamp": 1712345678.842,
"project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"space_id": "c3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f",
"params": {
"call_id": "c1a2b3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"node_id": "a3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"call_state": "answered"
}
}
}

Events are notifications, so you don’t reply to them. Some services shape the envelope slightly differently: inbound events routed by context, such as calling.call.receive and messaging.receive, carry the context they were routed to, and Tasking events put their fields directly under params. The exact envelope and payload for each event live on that event’s page in the API reference. If you use an SDK, you don’t parse this shape by hand — the SDK delivers each event as a typed object or a callback.

Correlate events to your requests

Events echo the identifiers you set, so you can tie each one back to the request or call it belongs to:

  • control_id — the identifier you set when you started a command (calling.play, calling.record, calling.detect, and so on). Its lifecycle events carry the same control_id.
  • tag — your label on a call; call events such as calling.call.state carry it so you can match them to the call you placed.

Next steps