> ## 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.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Actors Files and Code

> Complete reference for the Actor class, its handlers, connections, storage, and timers

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      You're viewing developer documentation
    </div>

    <div className="dev-docs-banner-text">
      This documentation is for developers working with the Base44 developer
      platform.
    </div>
  </div>
</div>

Complete reference for the `Actor` class that runs in your app's backend. For the client SDK that connects to a session, see the [`actors` SDK reference](/developers/references/sdk/docs/type-aliases/actors).

For actor concepts and terminology, see the [actors overview](/developers/backend/resources/actors/overview).

## Required handlers

The `Actor` class is abstract. Implement the body of each of the following handlers. The handlers respond to events from clients and timers.

| Handler | Events |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | A client connects. |
| [`handleMessage()`](#lifecycle-handlers) | A connected client sends a message. |
| [`handleClose()`](#lifecycle-handlers) | A client disconnects. |
| [`handleTick()`](#timer-handlers-and-settings) | Each tick interval, while ticking is on. |

## Optional handlers

When your actor needs them, implement these handlers.

| Handler | Events |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | The session starts, before Base44 handles a connection. |
| [`shouldTick()`](#timer-handlers-and-settings) | After each connection, message, disconnection, and tick. |
| [`handleWake()`](#timer-handlers-and-settings) | A time set with `schedule()` arrives. |

When the session ticks, set [`tickIntervalMs`](#timer-handlers-and-settings). If you omit `shouldTick()`, the session never ticks.

## Methods to call

The actor class provides built-in functionality. The following are methods that you can use when implementing an actor's handlers.

| Method | Purpose |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Arm a wake at a time you choose. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Clear a scheduled wake. |
| [`conn.send()`](#connections) | Reply to one client. |
| [`conn.reject()`](#connections) | Refuse a connecting client. |
| [`broadcast()`](#connections) | Reach every client in the session. |
| [`getConnections()`](#connections) | List the connected clients. |
| [`this.storage.get()`](#storage) | Read a saved session value. |
| [`this.storage.put()`](#storage) | Save a session value. |
| [`this.storage.delete()`](#storage) | Remove one saved value. |
| [`this.storage.deleteAll()`](#storage) | Clear the session store. |
| [`secrets.get()`](#read-secrets) | Read an app secret. |

Use [`this.client`](#entity-access) to read and write [entities](/developers/backend/resources/entities/overview).

## Class declaration

Import `Actor` from `base44:runtime/actors` and export a class that extends `Actor` as the default export from `base44/actors/<actor-name>/entry.ts`.
The folder name becomes the actor name in the SDK. For setup details, see [create an actor](/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Types the messages the actor receives from connected clients. Applies to the
  `msg` parameter of `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Types the messages the actor sends to connected clients. Applies to
  `conn.send()` and `broadcast()`.
</ResponseField>

## Runtime API

Actors import the `Actor` class from the `base44:runtime/actors` module:

```typescript theme={null}
import { Actor } from "base44:runtime/actors";
```

### Read secrets

Use `secrets.get()` to read your app's environment variables from a handler. The method returns the value as a string, or `undefined` when the secret isn't set.

Import `secrets` from the `base44:runtime` module:

```typescript theme={null}
import { secrets } from "base44:runtime";
```

Configure secrets from the CLI with [`secrets set`](/developers/references/cli/commands/secrets-set).

We recommend calling a [backend function](/developers/backend/resources/backend-functions/overview) for work that needs a secret. The function reads the secret and returns the result, so the actor never receives the secret. For a sample flow, see [call a backend function for secret work](/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Lifecycle handlers

Base44 calls these handlers in response to client activity in the session.
You implement the body for each.
Learn more about [how actors and clients interact](/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
For a sample flow, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  Runs anytime a session activates, such as:

  * When the session is first created.
  * When a client connects to an idle session.
  * When a message arrives on an idle session.
  * When a scheduled time arrives.

  Returns `void` or a `Promise<void>`.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  Runs when a client connects to the session.
  You can send the current session state with `conn.send()`, or refuse the connection with `conn.reject()`.
  Returns `void` or a `Promise<void>`.

  <Expandable title="Parameters">
    <ResponseField name="conn" type="Conn" required>
      Represents the client that connected.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  Runs when a connected client sends a message.
  You can validate the message before changing session state or accessing app data.
  Returns `void` or a `Promise<void>`.

  <Expandable title="Parameters">
    <ResponseField name="conn" type="Conn" required>
      Represents the client that sent the message.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Contains the message sent from the client. The `Incoming` generic defines
      the message type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  Runs when a client disconnects.
  Use this handler to remove any session state associated with the connection ID.
  A reconnect that reuses the same ID replaces the old socket without running `handleClose()`.
  Returns `void` or a `Promise<void>`.

  <Expandable title="Parameters">
    <ResponseField name="conn" type="Conn" required>
      Represents the client that disconnected.
    </ResponseField>
  </Expandable>
</ResponseField>

## Timer handlers and settings

These handlers and settings control timed work in the session.
Base44 calls them when a scheduled time arrives, not in response to client activity.
Learn more about [scheduled work](/developers/backend/resources/actors/overview#scheduled-work).
For sample flows, see [run ticks](/developers/backend/resources/actors/sample-flows#run-ticks) and [schedule wakes](/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  Runs once per interval while `shouldTick()` returns `true` and the session has at least one client.
  Returns `void` or a `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Specifies the interval between ticks in milliseconds. Defaults to `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Returns a `boolean`. Return `true` to keep the session ticking, or `false` to stop it. This method is synchronous.

  Keep this method fast and free of side effects. Base44 calls this method after each connection, message, disconnection, and tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  Runs once when a time set with `schedule()` arrives.
  Returns `void` or a `Promise<void>`.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Contains the key passed to `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Schedules one run of `handleWake()` at a specified time.
  Returns a `Promise` that settles after Base44 stores the schedule.
  The schedule survives an idle period and can start an idle session.
  Calling this method again with the same key replaces the scheduled time.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Identifies the scheduled wake. Passed to `handleWake()` when the wake triggers.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Specifies when `handleWake()` runs. Use a `Date` object or milliseconds
      since January 1, 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Cancels the scheduled wake associated with a key.
  Returns a `Promise` that settles after Base44 clears the schedule.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Specifies the key passed to `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Connections

These properties and methods are available on the `conn` object passed to lifecycle handlers that involve a client.
Use these properties and methods to read client identity, send messages, and manage the connection.
For an overview of messaging, see [realtime messages](/developers/backend/resources/actors/overview#realtime-messages).
For a sample flow, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` is the backend end of the WebSocket, and `Connection` in the client is the other end of the same socket. Use `conn` in the actor class. See the `actors` SDK reference for the client object.
</Note>

<ResponseField name="conn.id" type="string">
  Identifies this connection. Matches the ID the client passed when connecting,
  or an ID the SDK generated.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifies the client on this connection. Present on all
  connections.

  <Expandable title="Properties">
    <ResponseField name="type" type="string" required>
      Contains `authenticated` or `anonymous`.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Identifies the logged-in client. Present when `type` is
      `authenticated`.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifies the anonymous client. Present when `type` is `anonymous`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Sends a message to this connection. Returns `void`.

  <Expandable title="Parameters">
    <ResponseField name="data" type="Outgoing" required>
      Contains the message to send to this connection. The `Outgoing` generic defines the message type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Refuses a connection from `handleConnect()`. Returns `void`.

  <Expandable title="Parameters">
    <ResponseField name="code" type="number" required>
      Specifies the status code sent to the client.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Describes why the actor refused the connection.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Sends a message to every live connection in the session. Returns `void`.

  <Expandable title="Parameters">
    <ResponseField name="data" type="Outgoing" required>
      Contains the message to send to every connection in the session. The `Outgoing` generic defines the message type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Returns an array of live `conn` objects in the session. Use this method in
  `handleStart()` to match restored data with clients that stayed connected
  through an idle period.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Session-level property. Contains the session ID that the client used to reach
  this session.
</ResponseField>

## Storage

Use `this.storage` to read and write session data. Unlike class fields, storage survives idle periods. To choose between storage and class fields, see [storage](/developers/backend/resources/actors/overview#storage). For a sample flow, see [persist session data](/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Retrieves a value by key. Returns a `Promise` that resolves to the stored
  value, or `undefined` when the key doesn't exist.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Specifies the key to retrieve.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Saves a value by key. Replaces the value already stored under the key. Returns
  a `Promise` that settles when the write completes.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Specifies the key to save.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Specifies the JSON-compatible value to save.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Removes a value by key. Returns a `Promise` that resolves to `true` when the
  key existed, and `false` otherwise.

  <Expandable title="Parameters">
    <ResponseField name="key" type="string" required>
      Specifies the key to remove.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Removes all saved data for the session. Returns a `Promise` that settles when
  the store is empty. A later connection starts with the same empty storage as a
  new session.
</ResponseField>

## Entity access

Use `this.client` and `this.client.asServiceRole` to read and write app entities from inside an actor handler. For a sample flow, see [write entity data from a session](/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Provides an app client scoped to this session. This client uses anonymous
  authentication, so entity access follows the same rules as a logged-out
  client, and it reads production data.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Provides elevated access that bypasses row-level security. Validate messages
  before you use this client. Make writes safe to repeat, because the session can run a handler
  again after an error.
</ResponseField>

## See also

* [Actors Overview](/developers/backend/resources/actors/overview): Concepts and terminology
* [Actors: Sample Flows](/developers/backend/resources/actors/sample-flows): Lifecycle, timers, connections, storage, entities, and backend functions
* [`actors` SDK reference](/developers/references/sdk/docs/type-aliases/actors): Client SDK API
* [`secrets set`](/developers/references/cli/commands/secrets-set): Configure environment variables from the CLI


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