> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Telnyx

> Give a workspace calling and SMS capabilities with a human-owned Telnyx account, secure credentials, readiness checks, and confirmed number purchases.

Contact Button uses a bring-your-own-carrier model for phone and SMS features. The human or organization keeps its own Telnyx account; Contact Button provisions and operates workspace-scoped resources through that account.

<Info>
  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.
</Info>

## What the human needs

1. A [Telnyx account](https://telnyx.com/sign-up) with billing enabled.
2. Any identity or regulatory verification Telnyx requires for the countries and number types they intend to use.
3. A [Telnyx API V2 key](https://developers.telnyx.com/development/api-fundamentals/create-api-keys). Telnyx displays the value once.
4. The account Ed25519 public key from **Mission Control → Keys & Credentials**. This is not the API key; Contact Button uses it to verify webhook signatures.

For programmable voice, Telnyx documents an account, API key, E.164 caller and receiver numbers, a Voice API Application, an outbound voice profile for outbound traffic, and webhooks as the core requirements. Contact Button creates and configures the applicable Telnyx resources after the account is connected.

## 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:

```bash theme={null}
CONTACTBUTTON_TOKEN=...
TELNYX_API_KEY=...
TELNYX_WEBHOOK_PUBLIC_KEY=...
```

Do not print these variables, include them in command output, write them to source control, or put them in Page content. The webhook public key is not secret, but keeping all carrier configuration in the same secure setup flow reduces mistakes.

## 1. Check the current connection

```bash theme={null}
curl https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/telephony \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN"
```

A new workspace returns `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:

```bash theme={null}
jq -n \
  --arg api_key "$TELNYX_API_KEY" \
  --arg public_key "$TELNYX_WEBHOOK_PUBLIC_KEY" \
  '{
    api_key: $api_key,
    webhook_public_key: $public_key,
    inbound_calls: true,
    call_forwarding: false,
    outbound_calling: false,
    sms_lead_alerts: false
  }' |
curl -X PATCH https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/telephony \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: telnyx-connect-$WORKSPACE_ID" \
  --data-binary @-
```

Contact Button verifies the API key against the Telnyx balance endpoint. It then attempts to create or update:

* 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

It also checks whether Telnyx AI Assistants can be listed for the account.

## 3. Read readiness

Do not treat a saved credential as a working phone connection. Inspect the response:

```json theme={null}
{
  "data": {
    "provider": "telnyx",
    "status": "configured",
    "api_key_hint": "••••1234",
    "public_key_configured": true,
    "readiness": {
      "call_control_application": true,
      "browser_calling": true,
      "outbound_voice_profile": true,
      "ai_assistants": true,
      "sms": false
    }
  }
}
```

`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.

| Capability                               | Required readiness                               |
| ---------------------------------------- | ------------------------------------------------ |
| Inbound calling and voice messages       | `call_control_application`                       |
| Browser click-to-call                    | `call_control_application` and `browser_calling` |
| Forwarding and outbound callback bridges | `outbound_voice_profile`                         |
| Telnyx AI Agent flow                     | `ai_assistants`                                  |
| SMS lead alerts                          | `sms` and an SMS-capable number                  |

## 4. Create a call flow

A call flow determines what an assigned phone number or click-to-call app does. Modes are `voicemail`, `callback`, `forwarding`, and `ai_agent`.

```bash theme={null}
curl -X POST https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/call-flows \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call-flow-main-$WORKSPACE_ID" \
  -d '{
    "name": "Main callback line",
    "mode": "callback",
    "greeting": "Tell us how to reach you and we will call you back.",
    "language": "en-US",
    "tts_voice": "Telnyx.NaturalHD.astra",
    "max_recording_seconds": 120,
    "missed_call_sms_delay_seconds": 30,
    "fallback_to_voicemail": true,
    "is_active": true
  }'
```

Keep the returned call-flow UUID.

## 5. Search, approve, and order a number

Searching does not buy a number:

```bash theme={null}
curl -X POST https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/phone-numbers/search \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: number-search-nl-$WORKSPACE_ID" \
  -d '{"country_code":"NL","area_code":"20","sms":false}'
```

Each result includes an opaque quote ID, phone number, monthly price, upfront price, currency, capabilities, and expiration. Before ordering, the agent must show those values to the human and ask for explicit approval.

<Warning>
  A phone-number order can create recurring and upfront charges. Never infer approval from the original setup request. Do not order after the quote expires, and do not replace the shown quote with another number.
</Warning>

After approval:

```bash theme={null}
curl -X POST https://api.contactbutton.com/v1/workspaces/$WORKSPACE_ID/phone-numbers/order \
  -H "Authorization: Bearer $CONTACTBUTTON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: number-order-$QUOTE_ID" \
  -d "{
    \"quote\":\"$QUOTE_ID\",
    \"label\":\"Main line\",
    \"call_flow_id\":\"$CALL_FLOW_ID\",
    \"confirm_price\":true
  }"
```

An order may remain `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.

## Updating and rollback

Omit `api_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.


## Related topics

- [Connect Telnyx or update phone capabilities](/api-reference/telephony/connect-telnyx-or-update-phone-capabilities.md)
- [Get the workspace Telnyx connection and readiness](/api-reference/telephony/get-the-workspace-telnyx-connection-and-readiness.md)
- [Get Stripe Connect readiness](/api-reference/commerce/get-stripe-connect-readiness.md)
- [Synchronize Stripe Connect readiness](/api-reference/commerce/synchronize-stripe-connect-readiness.md)
- [Purchase a quoted Telnyx number](/api-reference/telephony/purchase-a-quoted-telnyx-number.md)