Actor Namespace

The env.<BINDING> handle your function calls into — idFromName (deterministic) and newUniqueId (random), both returning an ActorStub.

env.<BINDING> is an ActorNamespace — the handle on env that your function calls into. It’s declared in telnyx.toml:

[[actors]]
binding = "ACCOUNT"    # env.ACCOUNT
type    = "Account"    # the class to instantiate per name

interface ActorNamespace {
  idFromName(name: string, options?: IdFromNameOptions): ActorStub;
  newUniqueId(options?: IdFromNameOptions): ActorStub;
}

interface IdFromNameOptions {
  locationHint?: LocationHint;     // "us-east" | "us-west" | "eu" | "apac" | (string & {})
}

idFromName(name, options?)

Deterministic — the same name always lands on the same actor instance. Pick a stable identity (CRM id, session id, room id, or a phone number with the leading + stripped) and let the platform route to the right state. Allowed characters: ASCII letters (A–Z, a–z), digits, -, _, ., :, and spaces.

locationHint is a placement hint, relevant on first touch only — an actor materializes once, so a hint on a later call can’t move it. The platform may ignore the hint entirely (today it does — the option is accepted and reserved for regional placement). Abstract region codes (the taxonomy can evolve without breaking your code).

newUniqueId(options?)

Random — a fresh, unguessable instance. Use when you want the runtime to mint the identity for you (e.g. a one-shot job actor). The id is generated client-side; keep it (via stub.id) if you’ll need to reach the instance again.

newUniqueId currently fails at call time on the platform (a known runtime issue). Until it’s fixed, mint an identity yourself and pass it to idFromName.

Both return an Actor Stub. Method dispatch on the stub is provided by the runtime via a Proxy; in TypeScript, run telnyx-edge types to type env.<BINDING> against your class’s public method shape, or hand-roll the narrowing — the Actor Stub page shows both.

Related

• Actor Stub — what idFromName / newUniqueId return
• Configuration — declaring the binding
• Addressing — naming and routing