> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actor Context

> The this.ctx object on a StatefulActor — the instance's identity, per-key storage, single alarm, one-shot init, and its live WebSockets.

`this.ctx` (an `ActorContext`) holds the instance's identity, per-key storage, single alarm, one-shot init, and the instance's live WebSocket connections.

```ts theme={null}
interface ActorContext {
  readonly id: string;             // the name you chose with idFromName(name)
  readonly storage: ActorStorage;  // see Actor Storage
  blockConcurrencyWhile<T>(fn: () => Promise<T>): Promise<T>;
  setAlarm(when: number): Promise<void>;  // alias for ctx.storage.setAlarm(when)
  count(): number;                 // live WebSockets on this instance
  broadcast(data: string | ArrayBuffer | ArrayBufferView): number;  // returns sent count
}
```

## `ctx.id`

The customer-supplied `name` for this actor — opaque string. You chose it via `env.<BINDING>.idFromName(name)`. Common patterns: caller E.164, CRM user id, email, or a composite key.

## `ctx.blockConcurrencyWhile(fn)`

One-shot init primitive. Use it inside a subclass constructor to gate all other calls until init finishes. **30s budget** — a callback that exceeds it fails init (`BlockConcurrencyTimeoutError`), and the activation is torn down and retried on the next call.

```ts theme={null}
class MyActor extends StatefulActor<Env> {
  constructor(ctx: ActorContext, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      // preload state, set up initial alarm, etc.
      // every other method call to this instance waits until this resolves
    });
  }
}
```

## `ctx.setAlarm(when)`

Top-level alias for `ctx.storage.setAlarm(when)`. `when` is **ms since epoch**. See [Alarms](/docs/edge-compute/stateful-actors/alarms).

## `ctx.count()`

The number of WebSocket connections open on **this instance** right now. Synchronous — no `await`. Scoped to the instance: sockets on other names of the same actor class are never counted, and a socket never carries over between names.

Callable from any handler — a socket message handler, an RPC method, or the alarm handler.

## `ctx.broadcast(data)`

Send one frame to every WebSocket open on **this instance**; returns the number of sockets the frame was sent to. A `string` is sent as a text frame; an `ArrayBuffer` or `ArrayBufferView` as a binary frame. Scoped to the instance, like `count()` — a broadcast never reaches another name's sockets. Like `ws.send()`, the write happens immediately; it is not held until the turn's storage writes commit.

Callable from any handler. Calling it from `alarm()` is the server-initiated push pattern — the actor sends with no inbound frame prompting it:

```ts theme={null}
async alarm(): Promise<void> {
  this.ctx.broadcast(JSON.stringify({ type: "tick", at: Date.now() }));
}
```

See [WebSockets](/docs/edge-compute/stateful-actors/websockets) for how sockets reach the actor in the first place.

## Related

* [Actor Storage](/docs/edge-compute/stateful-actors/api-reference/storage) — `ctx.storage`
* [Base Class](/docs/edge-compute/stateful-actors/api-reference/base) — where `this.ctx` comes from
* [Alarms](/docs/edge-compute/stateful-actors/alarms) — the alarm contract
* [WebSockets](/docs/edge-compute/stateful-actors/websockets) — the connection contract behind `count()` and `broadcast()`