> This page is for APIs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Events and subscriptions

> How Relay pushes events to your backend connection, and how to subscribe to inbound events with contexts.

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.

> **Note**
>
> 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:

```json
{
  "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](/docs/apis/relay/server/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.

> **Note**
>
> 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:

```json
{
  "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

#### [Connection lifecycle](/docs/apis/relay/server/connection-lifecycle)

Detect a dropped connection, rotate your API token, and reconnect cleanly.

#### [Overview](/docs/apis/relay/server)

How a Relay connection works end to end, and what each service does.