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

​
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. Names may contain ASCII letters (A–Z, a–z), digits, -, _, ., :, and spaces. Instance ids — what the name resolves to, and what the platform actually addresses — are built from [A-Za-z0-9._-] plus optional :hex: escape brackets: encodeAgentName escapes every character outside [A-Za-z0-9._-] (including : and spaces) into :hex: form, e.g. encodeAgentName("+15550100") → :2b:15550100. On the wire the : brackets themselves URL-escape to %3A. A literal name passed through untouched can never contain : — that is what keeps encoded ids from colliding with passed-through ones. idFromName itself does not escape: it uses the name as the id verbatim. To pass a name containing : or spaces, encode it first with the Agent SDK’s encodeAgentName and pass the encoded id (the mountAgents mount does this for you) — otherwise the instance id you hand the platform carries an unencoded :/space and cannot be addressed. A name of exactly . or .. is not addressable either (URL path resolution would collapse those segments away); encodeAgentName escapes it in full. Length limit: 225 characters on the escaped id, not the original name — escaping inflates (each escaped run becomes :hex:, and the : brackets themselves URL-escape to three characters on the wire), so a name well under any name-level bound can still encode to an over-limit id. encodeAgentName refuses such names up front; calling idFromName directly with an over-long id does not fail at call time — the instance activates, accepts writes, and only becomes unreachable after its first eviction, so do not rely on the platform to reject it. 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.