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

# actors

***

## Overview

Actors module for interacting with [actors](https://docs.base44.com/developers/backend/resources/actors/overview.md) from your app.

An actor is a long-running backend process that multiple clients connect to simultaneously. A session
is a running instance of an actor, identified by the actor name and a session ID. Each
session manages its own state, storage, and client connections independently.

The actors module provides the functionality to:

* Manage connections: [Open](#connect) and [close](#close) a WebSocket connection to a session.
* Exchange messages: [Send](#send) and [listen](#subscribe) for messages to and from an actor.
* Manage subscriptions: [Subscribe](#subscribe) and [unsubscribe](#unsubscribe) from actor messages without closing the connection.
* Call methods: run one of an actor's callable methods on a session, without connecting.

For a sample flow, see
[connect a client to a session](https://docs.base44.com/developers/backend/resources/actors/sample-flows.md#connect-a-client-to-a-session).

### Authentication modes

This module is available to use with a client in anonymous or user authentication mode. Access it
through `base44.actors`. In
[service role authentication mode](https://docs.base44.com/developers/references/sdk/getting-started/client.md#service-role),
`base44.asServiceRole.actors` only calls methods.

The actor receives each client's [identity](https://docs.base44.com/developers/backend/resources/actors/reference.md#connections)
when the client connects or calls a method. A client that hasn't logged in is anonymous, a client that
has [logged in](https://docs.base44.com/developers/references/sdk/docs/interfaces/auth.md) is authenticated, and server
code calling with the service role is `service`.

## Actor methods

Represents a reference to an actor session, identified by actor name and session ID.

Call [`connect()`](#connect) to open the WebSocket and get a [connection](https://docs.base44.com/developers/backend/resources/actors/overview.md#connections),
or call one of the actor's callable methods by name, such as `ref.kick({ userId })`: it runs
the actor's method with your identity, even when no client is connected, and resolves to
its return value. A refusal rejects with a `Base44Error` carrying the actor's status (404 for
a method the actor doesn't list in `static callable`).

A call takes one argument, any JSON value: pass several values as an object, such as
`ref.videoReady({ id, url })`, or an array. Further arguments are dropped, so `ref.m(a, b)`
sends only `a`. Arguments and the reply are JSON-encoded: a `Date` arrives as a string,
`undefined` is dropped (`null` inside an array), and functions, `Map` and `Set` values don't
survive. A request is at most 64 KB and calls are rate-limited per caller.

#### Example

```typescript Call a method on a session theme={null}
const { kicked } = await base44.actors.chatRoom("session-1").kick({ userId });
```

### connect()

> **connect**(`options?`): `Connection`\<`N`>

Creates or returns the connection for this session.

Calling `connect()` again on the same session reference returns the same
connection until it closes.

For a sample flow, see
[connect a client to a session](https://docs.base44.com/developers/backend/resources/actors/sample-flows.md#connect-a-client-to-a-session).

#### Parameters

**options** `ActorConnectOptions`

Optional connection settings, such as a stable connection ID.

> [accordion] Properties
>
> **id** `string`
>
> Connection ID that the actor receives as `conn.id`.
>
> To let the actor recognize a client when it reconnects, use a stable
> value, such as an ID stored per browser tab. If you omit this property, the
> SDK generates a new connection ID.

#### Returns

[`Connection`](#connection-methods)

The connection for this actor session.

> [accordion] Properties
>
> **id** `string` *required*
>
> Connection ID that the actor receives as `conn.id`.

#### Example

```typescript Connect to a session theme={null}
const conn = base44.actors.chatRoom("session-1").connect({ id: "tab-1" });
```

## Connection methods

Represents a client's [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) connection to an actor session, returned after calling
[`connect()`](#connect). The WebSocket queues messages you send before it opens.

Learn more about
[connections](https://docs.base44.com/developers/backend/resources/actors/reference.md#connections).

### subscribe()

> **subscribe**(`callback`): `ActorSubscription`

Registers a listener for messages from the actor.

You can register multiple listeners on the same connection.

#### Parameters

**callback** `(data) =\> void` *required*

Callback that runs for each message the actor sends to this connection.

#### Returns

[`ActorSubscription`](#subscription-methods)

A subscription handle. Call `unsubscribe()` on it to remove this listener without closing the socket.

#### Example

```typescript Listen for messages from the actor theme={null}
const sub = conn.subscribe((msg) => {
  console.log(msg);
});

// Stop listening without closing the socket.
sub.unsubscribe();
```

***

### send()

> **send**(`data`): `void`

Sends a message to the actor.

The WebSocket queues messages until it opens. When you call [`close()`](#close),
the WebSocket drops any messages you send afterward.

#### Parameters

**data** `ToServerFor\<N\>` *required*

Message to send to the actor. The type comes from [`ActorRegistry`](#actorregistry) when you register the actor there.

#### Returns

`void`

#### Example

```typescript Send a message to the actor theme={null}
conn.send({ type: "message", text: "Hello" });
```

***

### close()

> **close**(): `void`

Closes the connection and removes all listeners.

You can call this method more than once. A connection also closes itself
when it fails permanently.

#### Returns

`void`

#### Example

```typescript Close the connection theme={null}
conn.close();
```

## Subscription methods

Represents a listener for messages from the actor, registered with
[`subscribe()`](#subscribe).

### unsubscribe()

> **unsubscribe**(): `void`

Removes this listener. Other listeners and the socket stay open.

#### Returns

`void`

#### Example

```typescript Remove a listener theme={null}
sub.unsubscribe();
```

## Type Definitions

### ActorClient

Selects a session for a named actor.

TypeScript infers message types when you register the actor in
[`ActorRegistry`](#actorregistry). [`ActorNameRegistry`](#actornameregistry)
provides autocomplete for actor names only.

#### Parameters

#### instanceId

`string`

Session ID that identifies which session to connect to.

#### Returns

[`ActorRef`](#actor-methods)\<`N`>

A reference to the actor session.

#### Example

```typescript Select a session theme={null}
const session = base44.actors.chatRoom("session-1");
```

### ActorRegistry

Maps actor names to their incoming and outgoing message types.

Extend this interface when you want typed actor
messages without generating types with the CLI:

* `toServer`: Defines incoming messages that a client sends to the actor.
* `toClient`:  Defines outgoing messages that the actor sends to connected clients.

To generate types from deployed actors, use the
[`types generate`](https://docs.base44.com/developers/references/cli/commands/types-generate) CLI command.

To learn how incoming and outgoing messages work, see
[message types](https://docs.base44.com/developers/backend/resources/actors/overview.md#message-types).

#### Example

```typescript Type messages for an actor theme={null}
declare module "@base44/sdk" {
  interface ActorRegistry {
    chatRoom: {
      toClient: { type: "joined" | "left" | "message"; userId?: string; from?: string; text?: string };
      toServer: { type: "message"; text: string };
      methods: { kick: (args: { userId: string }) => { kicked: boolean } };
    };
  }
}
```

### ActorNameRegistry

Lists actor names when your project includes types generated by the CLI
with [`types generate`](https://docs.base44.com/developers/references/cli/commands/types-generate).

The generated names provide autocomplete for deployed actors. To define
incoming and outgoing message types manually, augment [`ActorRegistry`](#actorregistry).

### ServiceRoleActorRef

> **ServiceRoleActorRef**\<`N`> = `ActorMethods`\<`N`>

Represents a reference to an actor session for server code running with the
[service role](https://docs.base44.com/developers/references/sdk/getting-started/client.md#service-role).
Server code can't hold a connection, so it only calls methods; the actor sees the
`service` identity.

#### Example

```typescript Tell a user's session that their video is ready theme={null}
await base44.asServiceRole.actors.VideoRoom(userId).videoReady({ id });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.