Phone numbers (Telnyx)

AgentOwl uses Telnyx for phone numbers. This page covers the operator setup for a self-hosted deployment. On the hosted service, AgentOwl does this for you; see Text messages.

Phone bindings require an active owning account with a current paid entitlement (pro or enterprise); a plan label alone does not establish eligibility. Free accounts get 403 billing.phone_plan_required. Hosted live billing is unreleased, so contact support for phone availability. Sandbox payments do not enable production provisioning.

Worker configuration

Set these Worker secrets:

Telnyx should send webhooks to:

• Messaging profile: <ingress-base-url>/ingress/sms
• Call Control application: <ingress-base-url>/ingress/voice

Bind a number

# Use a number already in your Telnyx account
agentowl messaging import-number acme +12125550142 --capability sms mms voice

# Same owned-number behaviour, using bind
agentowl messaging bind acme --number +12125550142 --capability sms voice

# Purchase and assign a new number
agentowl messaging bind acme --capability sms

import-number and bind --number look up that exact number in your Telnyx account; they never order one. bind without --number purchases a number. Assign each number to only one active binding.

Then route the binding and publish:

agentowl route create --tenant acme --binding <binding_id> --endpoint <endpoint_id>
agentowl config publish acme
agentowl provider sync acme
agentowl drift check acme

provider sync asks the reconciler to attach the number to an AgentOwl messaging profile and Call Control application. drift check reports any difference between your bindings and Telnyx.

For a voicemail inbox, route the number to a hosted-page endpoint. A voice-runtime endpoint uses its own call handling instead of voicemail; see Voice.

Set up an existing voice number

From the repository's npm workspace, preview the Telnyx setup for a number you already own:

npm run setup:telnyx -- +12125550142

Add --apply to create or reuse the AgentOwl voice application and attach it to the number. The script reads TELNYX_API_KEY from the environment or the repository-root .env.local and uses AGENTOWL_INGRESS_BASE_URL (default https://api.agentowl.dev). It never orders numbers and doesn't replace unrelated connections. Calls still need the binding, route, published config, and the matching TELNYX_PUBLIC_KEY.

Removing a number

Unbinding detaches AgentOwl's messaging profile and Call Control application but keeps the number in your Telnyx account. Release it in Telnyx if you no longer need it.

agentowl messaging unbind b_abc123 --plan
agentowl messaging unbind b_abc123 --confirm

Serialize setup of the same number; retries reuse the same application name.