Check an owned number before enabling agent voice

Begin with the number you own

An agent voice workflow starts with an active number already owned by the workspace. Save its number ID and project identity before considering a call. A number visible in a provider search result is inventory, not a usable sender. Purchasing a replacement can involve recurring charges, capability checks and separate billing approval. This guide assumes ownership is established; it does not promise that a new number can be purchased and immediately activated. Keep the existing number throughout setup so people retain a stable callback address.

Separate messaging and voice configuration

Telnyx messaging and voice use different configuration. SMS depends on a messaging profile, while voice depends on the configured connection and callback routing. An SMS that arrives successfully therefore proves little about conversational audio. The operator must supply the Telnyx credentials and configure callbacks at /v0/telnyx/webhooks. A missing provider configuration produces an unavailable response. Diagnose that response as a setup issue before retrying requests or rotating the workspace credential; those actions cannot create the absent provider connection.

Read admission status before dialing

Use GET /v0/phone/status with the credential the agent will actually use. Inspect the returned enabled numbers, allowed peers, maximum call duration and remaining monthly seconds. Match the number ID to your saved workspace resource rather than selecting the first item. The current voice path allows one active call per workspace and caps a conversation at two minutes. A spending limit without a verified voice cost ceiling can block new calls even when seconds remain, so quota alone is insufficient evidence of availability.

curl --fail-with-body "https://api.lupin.sh/v0/phone/status" \
  -H "Authorization: Bearer $LUPIN_API_KEY"

Keep profile setup with the operator

A voice profile binds the owned number to a particular agent and supported transport. SIP and the streaming media gateway have separate validation paths; enabling one does not prove the other is working. Operator setup also supplies the exact permitted peer through private metadata and pins the Telnyx verification key. Do not paste those values into public examples or infer a country, language, gender or identity from the phone number. Choose language and voice behavior explicitly with the authenticated account owner.

Distinguish reachability from private access

An incoming call from an allowed peer may reach the conversational system, but caller ID is not private workspace authentication. Lupin directs incoming callers to request an authenticated callback through iMessage or the dashboard for private agent access. Build onboarding around that boundary. For example, a support demonstration can explain public product behavior on an incoming call while reserving mailbox searches and connected application work for an authenticated callback. A familiar sounding caller still needs the same authorization path.

Define a readiness record

Record ownership, project, enabled transport, allowed destination, tested callback configuration and the person responsible for billing. Treat readiness as a dated operational fact because accounts, budgets and provider settings can change. A useful acceptance check is that the delegated credential reads the expected number and admission state without placing a call. If availability is false, preserve the reported reason and ask the operator to resolve that condition. Move to a short, explicitly approved conversation only after the setup record and current status agree.

Work through an unavailable result

Suppose the expected number appears with remaining seconds but available is false and the reason is voice_budget_unpriced. Ownership and allowance have passed useful checks, yet the spending boundary is unresolved. Save that result for the operator and keep the callback unsubmitted. Buying another number would not repair the missing cost ceiling.

Sources & verification

Reviewed against current checked-in Lupin routes, shared contracts and official provider references. No live calls, OAuth authorizations, app actions or purchases were performed.

• Lupin phone, SMS and calls ↗Checked 2026-11-05
• Telnyx programmable voice events ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.