Actors Overview

An actor is a long-running backend process that multiple clients connect to simultaneously. With actors, you can build live session instances that support the following functionality:

• Realtime messaging: Send and receive messages with clients via WebSockets.
• Persistent storage: Keep session state alive between idle periods.
• Scheduled work: Run logic at a set interval or at a specific time.

Use actors when you’re building features where multiple clients require realtime updates and interaction, such as a chat room or multiplayer game.

​

Actors

Actor is the class you extend in your backend. The actor class defines the behavior of a live session. With actors, you can:

• Manage connections: Accept or reject a client connecting to the session, and identify who is connecting.
• Handle messages: Receive a message from a client, update session state, and reply to one client or broadcast to all.
• Schedule work: Run logic on an interval or at a scheduled time.

​

Sessions

A session is a running instance of an actor, identified by the actor name and a session ID you choose.
Each session manages its own state, storage, and client connections independently.

​

Connections

A connection represents a client’s WebSocket to a session. Each client that joins gets a unique connection. An actor uses that connection to identify who is connecting, manage client connections, and send messages. To learn more, see connections. For a sample flow, see manage client connections.

​

Active and idle sessions

A session is always in one of the following states:

• Active: The session is live and processing events. A session becomes active when a client connects, when a client messages an idle session, or when a scheduled wake time arrives.
• Idle: The session isn’t processing events. A session goes idle shortly after it finishes its last message and all scheduled work stops. The session maintains its stored data, scheduled times, and open connections until it becomes active again.

When a session goes idle, clients with open connections stay connected. Their next message or a scheduled wake activates the session again.

​

Client

Use base44.actors in the JavaScript SDK to connect a client to an actor session and exchange messages. The actors SDK supports the following functionality:

• Connect: Open a WebSocket connection to a session.
• Subscribe: Receive messages from the actor.
• Send: Send messages to the actor.
• Close: Close the WebSocket connection to the actor.

To learn more, see connect a client to a session.

​

How actors and clients interact

The following diagram shows the general interaction between a client and an actor:

1. The client connects to the actor over a WebSocket.
2. The session activates. handleStart() runs on first start and each time the session activates from idle.
3. The actor handles the connection. You can check the client’s identity and reject the connection, or send the current state.
4. The client sends a message.
5. The actor handles the message. You can validate the format and the sender’s permissions before you change session state.
6. The actor broadcasts the update to every connected client, or replies only to the sender.
7. The client closes the connection.
8. The actor handles the disconnect. You can remove per-connection state.

​

Realtime messages

Each connected client belongs to a session and can send messages in realtime via WebSockets. Clients can also listen for incoming messages using subscribe(). With realtime messages, you can:

• Reply to a specific client.
• Broadcast to all connected clients.
• List the clients that are currently connected.
• Identify each client and check whether the client has logged in.

To learn more, see connections. For a sample flow, see manage client connections.

​

Message types

A client and an actor exchange messages over a connection. Messages fall into the following types:

• Incoming messages: What a connected client sends to the actor, such as a text, a move, or a vote. The client sends them with send(), and the actor receives them in handleMessage().
• Outgoing messages: What the actor sends to connected clients, such as a reply to a client, a broadcast to all connected clients, or the current board when someone joins. The actor sends them with conn.send() or broadcast(), and the client receives them in a subscribe() callback.

We recommend typing your messages so the actor and the client agree on each message’s shape:

• Backend: Pass Incoming and Outgoing types as generics to the Actor class. For a complete example, see create an actor.
• Client: Extend the ActorRegistry interface with the same shapes, so TypeScript checks the types of send() and subscribe().

​

Storage

Actors provide several storage options depending on how your session uses and retains data:

• In-memory storage: Working state that lives in class fields while the session is active and resets when the session goes idle.
• Persistent storage: A key-value store for data that needs to survive when the session goes idle.

​

In-memory storage

Class fields hold the working state while the session is active, such as the current board or a round timer. Use in-memory storage when your data changes frequently and doesn’t need to persist when the session goes idle, such as a live score or a cursor position. When a session becomes idle, class fields reset.

​

Persistent storage

Each session has its own key-value store that you can fully manage. Use persistent storage when your data needs to survive when the session goes idle, such as chat history or a game board. To store data that’s available across the entire app, use entities. To learn more about actor storage, see storage.

​

Restoring state

When a session goes idle, in-memory state resets. Persistent storage survives, but the session doesn’t automatically load the stored data back into memory when the session activates. Use handleStart() to restore persistent data, such as the chat history or the game board. For a sample flow, see persist session data.

​

Scheduled work

Actors provide functionality for a session to run logic on a schedule, independent of client messages:

• Ticks: Run code on an interval and keep the session active while they repeat.
• Wakes: Run once at a time you choose, whether the session is active or idle.

​

Ticks

Ticks run code on an interval, and they keep the session active while they repeat. Use shouldTick() to set the conditions for when ticking runs. An actor re-evaluates shouldTick() after every connection, message, disconnection, and tick, so ticking stops as soon as the condition is no longer met. With ticks, you can:

• Choose the length of each interval.
• Define a condition that starts and stops ticking, such as “at least two players are in the session.”
• Write the code that runs each interval.

Use ticks to keep a session active even when clients aren’t sending messages, such as updating a round timer. To learn more about ticks, see timer handlers and settings and run ticks for a sample flow.

​

Wakes

A wake runs once at a time you choose, whether the session is active or idle. With wakes, you can:

• Schedule when a wake runs.
• Implement logic that runs when a wake occurs.

Use a wake to schedule a one-time action, such as ending a game turn, closing an empty lobby, triggering a reminder, or starting an event at a specific time. To learn more about wakes, see timer handlers and settings and schedule wakes for a sample flow.

​

Deploy an actor

Deploy actors with actors deploy. To push all project resources at once, use deploy. Deploying adds and updates remote actors and leaves the rest in place.

​

Delete an actor

To delete an actor:

• Run actors delete to delete the remote actor from Base44.
• Delete the actor directory from your local project.

​

See also

• Create an Actor: Actor files and a minimal class
• Actors: Sample Flows: Lifecycle, timers, connections, storage, entities, and backend functions
• Actors Files and Code: Complete backend class API
• actors SDK reference: Client SDK API