Skip to main content

​
Deploy

The first deploy registers the agent and builds it, which typically takes about ten minutes (deploy waits up to 25); every deploy after that is a new revision, and versions lists the earlier ones (rollback is refused today; see Beta Limitations). A project with a phone number, an email inbox or a channel is asked once for the account’s webhook public key, stored as the TELNYX_PUBLIC_KEY secret; in scripts, store it beforehand with telnyx-acp add secret TELNYX_PUBLIC_KEY. With email set, deploy finds or creates the inbox, subscribes its domain to email.received and prints the address. With web set, it prints the page’s URL and the embed tag; the page is public from then on. A phone number’s line ends with what its texting cannot do, when the number’s features say so: domestic texts only: this number cannot receive or send international SMS, so a phone abroad cannot reach it.

​
When a Deploy Fails

Most failures happen before anything ships, as a list of problems that each name the field and the fix:
The same list comes from telnyx-acp validate, so a project can be checked without deploying. A number in phone that is not in the account, or not active yet, stops the deploy and is named. A secret the model or a channel needs, missing from the platform, is named with the add secret command that stores it. A build that fails ends the deploy with exit 1 and the platform’s reason on the first line; agent.json records no new revision (a TELNYX_PUBLIC_KEY stored on the way stays). telnyx-edge ship status <name> --logs has the build’s records, telnyx-acp versions <name> lists the ships and their status, and telnyx-acp status shows which revision is active.

​
Status

The function’s state and active revision (with the note deploy wrote), the actor type, each number with what answers on it, each webhook (✓ when it points at this agent, “changed outside the CLI: now …” when something else repointed it), and the address. --json carries the same as data.

​
Logs

Runtime records are one JSON line per event; logs explains each line. --since is a duration such as 10m, 2h.

​
Versions and Rollback

A revision whose build failed cannot be rolled back to and is shown with the reason.

​
Invoke and RPC

invoke is one text turn: it posts the text to the conversation’s instance over the mount and reads the reply back. A run paused for an approval, a canceled run and a run that completed without saying anything each end invoke with a line that says so instead of a timeout. rpc calls any @rpc method on the instance with its arguments as JSON; a method that is not @rpc is refused as the agent refuses it, with no stack trace.

​
Secrets

Values never touch agent.json or a command line; the error for a rejected secret names it, never its value.

​
Delete

Each wired artifact’s webhook goes back to its pre-deploy value (left alone if something else repointed it), each number goes back where it was and the artifacts deploy created are deleted, the inbox and webhook deploy created are removed, then the function, then the actor type. The actor type is deleted once the function’s teardown has settled; delete retries for about two minutes, and a type still there after that ends delete with exit 1 and the telnyx-edge actors delete command to run, deployed and .telnyx/ already cleared. Project files stay; deployed leaves agent.json and .telnyx/ is removed, so the next deploy registers the agent afresh. A webhook that will not restore stops the verb before the function goes, with two exceptions delete reports and moves past: an artifact already deleted outside the CLI (already gone from the platform; nothing to restore), and one that had no webhook before the agent and whose API refuses a blank one (webhook still points at the agent … clear or delete it in Mission Control; a Call Control application is one). The artifacts deploy created for a bare number are deleted with the number, never restored. --json lists them as gone and unclearable.

​
Beta Limitations

  • Pre-release. @telnyx/acp is a pre-release on npm. Each beta is published as latest until the first stable version ships, and a release can change the behavior these pages describe.
  • No control plane API. telnyx-acp drives deploy, status, logs, versions and rollback from the client, through telnyx-edge. telnyx-acp list is reserved for that API and is not available yet.
  • One address per project. One project is one function with one address, and the active revision is the only one addressable. There is no staging slot or traffic split; separate environments are separate projects with their own names.
  • No rollback. The platform refuses a rollback for a function that owns its actor type, which every agent the CLI deploys does. The way back is the project checked out at the earlier commit, which versions names by its git short SHA, and deployed again.
  • No way to end one conversation. There is no command to end one conversation and clear its state. delete removes the agent and every conversation with it.
  • Bundled packages. deploy links the CLI’s own @telnyx/acp and @telnyx/edge-runtime into the bundle, so the versions pinned in an exported project’s package.json do not change what ships.