> ## 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 or update phone capabilities

> Initial bring-your-own-carrier setup requires both the Telnyx API V2 key and the account Ed25519 public key.
Later updates may omit either credential to keep the stored value. The API key is encrypted and never returned.




## OpenAPI

````yaml /openapi.yaml patch /workspaces/{workspace}/telephony
openapi: 3.1.0
info:
  title: Contact Button API
  version: 1.0.0-alpha.1
  description: >
    API-first management and public agent actions for Contact Buttons and
    button.contact pages.

    API v1 is the first public contract. Existing private legacy API and browser
    workflows remain supported.
  contact:
    name: Contact Button
    url: https://learn.contactbutton.com
servers:
  - url: https://api.contactbutton.com/v1
    description: Production (canonical)
  - url: https://app.contactbutton.com/v1
    description: Backwards-compatible application-domain alias
security:
  - bearerAuth: []
tags:
  - name: Onboarding
    description: Human-verified agent onboarding.
  - name: Workspaces
  - name: Team
  - name: Pages
  - name: Domains
  - name: Buttons
  - name: Forms
  - name: Surveys
  - name: Apps
  - name: Knowledge
  - name: Booking
  - name: Telephony
    description: >-
      Bring-your-own-Telnyx setup, call flows, phone numbers, and voice
      interactions.
  - name: Reviews
    description: >-
      Send consented review requests through workspace-owned email, SMS, and
      WhatsApp channels.
  - name: Commerce
  - name: Engagement inbox
  - name: Public actions
    description: Public, rate-limited actions that may require human confirmation.
paths:
  /workspaces/{workspace}/telephony:
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
    patch:
      tags:
        - Telephony
      summary: Connect Telnyx or update phone capabilities
      description: >
        Initial bring-your-own-carrier setup requires both the Telnyx API V2 key
        and the account Ed25519 public key.

        Later updates may omit either credential to keep the stored value. The
        API key is encrypted and never returned.
      operationId: updateTelephonyConnection
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelephonyConnectionInput'
      responses:
        '200':
          $ref: '#/components/responses/Data'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
components:
  parameters:
    WorkspaceId:
      name: workspace
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Stable 8–120 character key for safe mutation retries.
      schema:
        type: string
        minLength: 8
        maxLength: 120
  schemas:
    TelephonyConnectionInput:
      type: object
      description: >-
        Initial setup requires both credentials. Omit saved credentials on later
        capability updates.
      properties:
        api_key:
          type: string
          minLength: 20
          maxLength: 500
          writeOnly: true
          description: Telnyx API V2 key. Keep this out of model context and logs.
        webhook_public_key:
          type: string
          minLength: 32
          maxLength: 2000
          writeOnly: true
          description: Telnyx account Ed25519 public key used to verify webhook signatures.
        inbound_calls:
          type: boolean
        call_forwarding:
          type: boolean
        outbound_calling:
          type: boolean
        sms_lead_alerts:
          type: boolean
        default_sms_sender:
          type: string
          pattern: ^\+[1-9][0-9]{7,14}$
          description: Required when SMS lead alerts are enabled.
    DataResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data: {}
        meta:
          type: object
          properties:
            request_id:
              type: string
            next_cursor:
              type:
                - string
                - 'null'
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - detail
        - instance
        - request_id
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        request_id:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  responses:
    Data:
      description: Successful data envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataResponse'
    Problem:
      description: RFC 9457-style problem details.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum personal access token
      description: >
        A Contact Button scoped bearer key. Send `Authorization: Bearer
        <token>`.

        Token abilities are enforced independently of workspace membership; both
        checks must pass.

        OAuth 2.0 authorization-code flows are not currently available.
      x-contact-button-token-abilities:
        workspaces:read: Read workspaces, teams, domains, settings, and connections.
        workspaces:write: >-
          Create and manage workspaces, teams, domains, settings, and
          connections.
        content:read: Read buttons, forms, lists, pages, booking types, and knowledge.
        content:write: Create, update, publish, and remove content.
        engagements:read: >-
          Read submissions, subscribers, bookings, callbacks, calls, reviews,
          and conversations.
        engagements:manage: Reply to and manage engagement records.
        actions:request: Request protected actions that can still require human confirmation.

````

## Related topics

- [Connect Telnyx](/guides/telnyx.md)
- [Update a call flow](/api-reference/telephony/update-a-call-flow.md)
- [Update and resynchronize a channel connection](/api-reference/engagement-inbox/update-and-resynchronize-a-channel-connection.md)
- [Get the workspace Telnyx connection and readiness](/api-reference/telephony/get-the-workspace-telnyx-connection-and-readiness.md)
- [Purchase a quoted Telnyx number](/api-reference/telephony/purchase-a-quoted-telnyx-number.md)