Telnyx is optional. You do not need it for Pages, buttons, apps, forms, bookings, callback-request capture, newsletter subscriptions, or knowledge. You need it for click-to-call, automated callback bridges, voice messages, call forwarding, Telnyx SMS, and Telnyx AI Assistant call flows.
What the human needs
- A Telnyx account with billing enabled.
- Any identity or regulatory verification Telnyx requires for the countries and number types they intend to use.
- A Telnyx API V2 key. Telnyx displays the value once.
- The account Ed25519 public key from Mission Control → Keys & Credentials. This is not the API key; Contact Button uses it to verify webhook signatures.
Secret handling for agents
Never ask the human to paste the Telnyx API key into a prompt or chat message. Ask them to add it through the coding agent host’s secret manager or environment configuration:1. Check the current connection
status: not_configured. An existing connection returns only the last four API-key characters, whether a public key is configured, enabled capabilities, balance metadata, and readiness. Contact Button never returns the full Telnyx API key.
2. Connect the account
The initial request requires both the Telnyx API key and account public key:- A Voice API Call Control Application using Contact Button’s signed webhook endpoint
- A credentials-based SIP connection for short-lived browser-calling credentials
- An outbound voice profile when call forwarding or outbound calling is enabled
- A messaging profile when SMS lead alerts are enabled
3. Read readiness
Do not treat a saved credential as a working phone connection. Inspect the response:configured means the core Call Control application and webhook signature key are ready. Individual capabilities can still require another readiness field. Explain every *_error value to the human instead of retrying indefinitely or claiming success.
4. Create a call flow
A call flow determines what an assigned phone number or click-to-call app does. Modes arevoicemail, callback, forwarding, and ai_agent.
5. Search, approve, and order a number
Searching does not buy a number:provisioning or report regulatory_status: action_required. In that case, direct the human to the Telnyx Mission Control Portal. Do not bypass Telnyx identity, emergency-address, messaging-registration, or other regulatory requirements.
Browser calling
The workspace dialer usesPOST /v1/workspaces/{workspace_id}/dialer/sessions with a Contact UUID in contact_id and an optional active workspace voice-number UUID in caller_id. It requires engagements:manage, a Contact with an international phone number, and ready outbound browser calling.
The response contains temporary session_token and login_token credentials, destination, caller number, and expiration. Keep them in the browser’s current call flow and out of logs or model context. Session creation intentionally bypasses idempotency replay; do not blindly repeat a request after an uncertain response. Finish or dismiss the current session before creating another.
Update presence with POST /dialer/presence using session_id and state connect, ready, busy, or offline. End the current user’s session with DELETE /dialer/sessions/{session_id}. These paths are under the same workspace prefix and require engagements:manage.
Updating and rollback
Omitapi_key and webhook_public_key on later updates to retain the saved values. Disable individual capabilities through the same workspace telephony endpoint. This does not cancel a rented Telnyx number or remove carrier-side resources.
If the human wants to stop all carrier access, first disable the Contact Button phone features and confirm no active call depends on them. Then have the human rotate or revoke the Telnyx API key in Mission Control. Number cancellation and carrier-resource deletion remain explicit Telnyx account actions.
Agent completion checklist
- The connection status and required readiness fields are reported accurately.
- No secret appeared in model context, logs, files, or command output.
- The human explicitly approved any number purchase after seeing current prices.
- The chosen number is attached to the intended call flow.
- Required Telnyx regulatory actions are complete or clearly handed back to the human.
- A real inbound or outbound smoke test is run only with the human’s permission.