openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Messaging API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- name: Messaging
paths:
  /alphanumeric_sender_ids:
    get:
      description: List all alphanumeric sender IDs for the authenticated user.
      operationId: ListAlphanumericSenderIds
      parameters:
      - description: Filter by messaging profile ID.
        in: query
        name: filter[messaging_profile_id]
        required: false
        schema:
          format: uuid
          type: string
      - description: Page number.
        in: query
        name: page[number]
        required: false
        schema:
          default: 1
          type: integer
      - description: Page size.
        in: query
        name: page[size]
        required: false
        schema:
          default: 20
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/ListAlphanumericSenderIdsResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '422':
          $ref: '#/components/responses/messaging_UnprocessableEntityResponse'
      summary: List alphanumeric sender IDs
      tags:
      - Messaging
      x-latency-category: responsive
    post:
      description: Create a new alphanumeric sender ID associated with a messaging profile.
      operationId: CreateAlphanumericSenderId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlphanumericSenderIdRequest'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/AlphanumericSenderIdResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '422':
          $ref: '#/components/responses/messaging_UnprocessableEntityResponse'
      summary: Create an alphanumeric sender ID
      tags:
      - Messaging
      x-latency-category: responsive
  /alphanumeric_sender_ids/{id}:
    delete:
      description: Delete an alphanumeric sender ID and disassociate it from its messaging profile.
      operationId: DeleteAlphanumericSenderId
      parameters:
      - description: The identifier of the alphanumeric sender ID.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/AlphanumericSenderIdResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Delete an alphanumeric sender ID
      tags:
      - Messaging
      x-latency-category: responsive
    get:
      description: Retrieve a specific alphanumeric sender ID.
      operationId: GetAlphanumericSenderId
      parameters:
      - description: The identifier of the alphanumeric sender ID.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/AlphanumericSenderIdResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Retrieve an alphanumeric sender ID
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_hosted_numbers:
    get:
      description: List all hosted numbers associated with the authenticated user.
      operationId: ListMessagingHostedNumbers
      parameters:
      - description: Filter by messaging profile ID.
        in: query
        name: filter[messaging_profile_id]
        required: false
        schema:
          format: uuid
          type: string
      - description: Filter by exact phone number.
        in: query
        name: filter[phone_number]
        required: false
        schema:
          type: string
      - description: Filter by phone number substring.
        in: query
        name: filter[phone_number][contains]
        required: false
        schema:
          type: string
      - description: Sort by phone number.
        in: query
        name: sort[phone_number]
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
      - in: query
        name: page[number]
        required: false
        schema:
          default: 1
          type: integer
      - in: query
        name: page[size]
        required: false
        schema:
          default: 20
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PhoneNumberWithMessagingSettings'
                    type: array
                  meta:
                    $ref: '#/components/schemas/messaging_PaginationMeta'
                type: object
          description: Successful response with a list of hosted numbers.
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
      summary: List messaging hosted numbers
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_hosted_numbers/{id}:
    get:
      description: Retrieve a specific messaging hosted number by its ID or phone number.
      operationId: GetMessagingHostedNumber
      parameters:
      - description: The ID or phone number of the hosted number.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PhoneNumberWithMessagingSettings'
                type: object
          description: Successful response with a hosted number.
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Retrieve a messaging hosted number
      tags:
      - Messaging
      x-latency-category: responsive
    patch:
      description: Update the messaging settings for a hosted number.
      operationId: UpdateMessagingHostedNumber
      parameters:
      - description: The ID or phone number of the hosted number.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumberMessagingSettingsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/PhoneNumberWithMessagingSettings'
                type: object
          description: Successful response with the updated hosted number.
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Update a messaging hosted number
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_profile_metrics:
    get:
      description: List high-level metrics for all messaging profiles belonging to the authenticated user.
      operationId: GetProfileMetrics
      parameters:
      - description: The time frame for metrics.
        in: query
        name: time_frame
        required: false
        schema:
          $ref: '#/components/schemas/MessagingMetricsTimeFrame'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ProfileMetricsHighLevel'
                    type: array
                  meta:
                    $ref: '#/components/schemas/messaging_PaginationMeta'
                type: object
          description: Successful response with high-level profile metrics.
        '400':
          $ref: '#/components/responses/messaging_BadRequestResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
      summary: List high-level messaging profile metrics
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_profiles/{id}/actions/regenerate_secret:
    post:
      description: Regenerate the v1 secret for a messaging profile.
      operationId: RegenerateMessagingProfileSecret
      parameters:
      - description: The identifier of the messaging profile.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MessagingProfileResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Regenerate messaging profile secret
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_profiles/{id}/alphanumeric_sender_ids:
    get:
      description: List all alphanumeric sender IDs associated with a specific messaging profile.
      operationId: ListProfileAlphanumericSenderIds
      parameters:
      - description: The identifier of the messaging profile.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - in: query
        name: page[number]
        required: false
        schema:
          default: 1
          type: integer
      - in: query
        name: page[size]
        required: false
        schema:
          default: 20
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/ListAlphanumericSenderIdsResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: List alphanumeric sender IDs for a messaging profile
      tags:
      - Messaging
      x-latency-category: responsive
  /messaging_profiles/{id}/metrics:
    get:
      description: Get detailed metrics for a specific messaging profile, broken down by time interval.
      operationId: GetDetailedProfileMetrics
      parameters:
      - description: The identifier of the messaging profile.
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: The time frame for metrics.
        in: query
        name: time_frame
        required: false
        schema:
          $ref: '#/components/schemas/MessagingMetricsTimeFrame'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProfileMetrics'
                type: object
          description: Successful response with detailed profile metrics.
        '400':
          $ref: '#/components/responses/messaging_BadRequestResponse'
        '401':
          $ref: '#/components/responses/messaging_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/messaging_NotFoundResponse'
      summary: Get detailed messaging profile metrics
      tags:
      - Messaging
      x-latency-category: responsive
components:
  responses:
    messaging_UnprocessableEntityResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unprocessable Entity
    AlphanumericSenderIdResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/AlphanumericSenderId'
            type: object
      description: Successful response with a single alphanumeric sender ID.
    messaging_BadRequestResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Bad Request
    messaging_UnauthorizedResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unauthorized
    MessagingProfileResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/MessagingProfile'
            title: Messaging Profile Response
            type: object
      description: Successful response with details about a messaging profile.
    messaging_NotFoundResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Not Found
    ListAlphanumericSenderIdsResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/AlphanumericSenderId'
                type: array
              meta:
                $ref: '#/components/schemas/messaging_PaginationMeta'
            type: object
      description: Successful response with a list of alphanumeric sender IDs.
  schemas:
    ProfileMetrics:
      additionalProperties: true
      description: Detailed metrics for a messaging profile.
      type: object
    AlphanumericSenderId:
      properties:
        alphanumeric_sender_id:
          description: The alphanumeric sender ID string.
          example: MyCompany
          type: string
        id:
          description: Uniquely identifies the alphanumeric sender ID resource.
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          format: uuid
          type: string
        messaging_profile_id:
          description: The messaging profile this sender ID belongs to.
          format: uuid
          type: string
        organization_id:
          description: The organization that owns this sender ID.
          type: string
        record_type:
          enum:
          - alphanumeric_sender_id
          example: alphanumeric_sender_id
          type: string
        us_long_code_fallback:
          description: A US long code number to use as fallback when sending to US destinations.
          example: '+15551234567'
          type: string
      type: object
    MessagingFeatureSet:
      description: 'The set of features available for a specific messaging use case (SMS or MMS). Features

        can vary depending on the characteristics the phone number, as well as its current

        product configuration.

        '
      example:
        domestic_two_way: true
        international_inbound: false
        international_outbound: true
      properties:
        domestic_two_way:
          description: Send messages to and receive messages from numbers in the same country.
          type: boolean
        international_inbound:
          description: Receive messages from numbers in other countries.
          type: boolean
        international_outbound:
          description: Send messages to numbers in other countries.
          type: boolean
      required:
      - domestic_two_way
      - international_inbound
      - international_outbound
      type:
      - object
      - 'null'
    NumberPoolSettings:
      description: 'Number Pool allows you to send messages from a pool of numbers of different types, assigning

        weights to each type. The pool consists of all the long code and toll free numbers

        assigned to the messaging profile.


        To disable this feature, set the object field to `null`.

        '
      example:
        geomatch: false
        long_code_weight: 1
        skip_unhealthy: true
        sticky_sender: false
        toll_free_weight: 10
      properties:
        geomatch:
          default: false
          description: 'If set to true, Number Pool will try to choose a sending number with the same area code as the destination

            number. If there are no such numbers available, a nunber with a different area code will be chosen. Currently

            only NANP numbers are supported.

            '
          type: boolean
        long_code_weight:
          description: 'Defines the probability weight for a Long Code number to be selected when sending a message.

            The higher the weight the higher the probability. The sum of the weights for all number types

            does not necessarily need to add to 100.  Weight must be a non-negative number, and when equal

            to zero it will remove the number type from the pool.

            '
          example: 1
          type: number
        skip_unhealthy:
          description: 'If set to true all unhealthy numbers will be automatically excluded from the pool.

            Health metrics per number are calculated on a regular basis, taking into account the deliverability

            rate and the amount of messages marked as spam by upstream carriers.

            Numbers with a deliverability rate below 25% or spam ratio over 75% will be considered unhealthy.

            '
          example: true
          type: boolean
        sticky_sender:
          default: false
          description: 'If set to true, Number Pool will try to choose the same sending number for all messages to a particular

            recipient. If the sending number becomes unhealthy and `skip_unhealthy` is set to true, a new

            number will be chosen.

            '
          type: boolean
        toll_free_weight:
          description: 'Defines the probability weight for a Toll Free number to be selected when sending a message.

            The higher the weight the higher the probability. The sum of the weights for all number types

            does not necessarily need to add to 100. Weight must be a non-negative number, and when equal

            to zero it will remove the number type from the pool.

            '
          example: 10
          type: number
      required:
      - toll_free_weight
      - long_code_weight
      - skip_unhealthy
      type:
      - object
      - 'null'
    MessagingProfile:
      example:
        created_at: '2019-01-23T18:10:02.574Z'
        daily_spend_limit: '100.00'
        daily_spend_limit_enabled: false
        enabled: true
        health_webhook_url: null
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        mms_fall_back_to_sms: false
        mms_transcoding: false
        mobile_only: false
        name: Profile for Messages
        number_pool_settings:
          geomatch: false
          long_code_weight: 2
          skip_unhealthy: false
          sticky_sender: true
          toll_free_weight: 10
        record_type: messaging_profile
        redaction_enabled: false
        redaction_level: 2
        updated_at: '2019-01-23T18:10:02.574Z'
        url_shortener_settings:
          domain: example.ex
          prefix: cmpny
          replace_blacklist_only: true
          send_webhooks: false
        v1_secret: rP1VamejkU2v0qIUxntqLW2c
        webhook_api_version: '2'
        webhook_failover_url: https://backup.example.com/hooks
        webhook_url: https://www.example.com/hooks
        whitelisted_destinations:
        - US
      properties:
        ai_assistant_id:
          description: The AI assistant ID associated with this messaging profile.
          type:
          - string
          - 'null'
        alpha_sender:
          description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
          pattern: ^[A-Za-z0-9 ]{1,11}$
          type:
          - string
          - 'null'
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          format: date-time
          readOnly: true
          type: string
        daily_spend_limit:
          description: The maximum amount of money (in USD) that can be spent by this profile before midnight UTC.
          pattern: ^[0-9]+(?:\.[0-9]+)?$
          type: string
        daily_spend_limit_enabled:
          description: Whether to enforce the value configured by `daily_spend_limit`.
          type: boolean
        enabled:
          description: Specifies whether the messaging profile is enabled or not.
          type: boolean
        health_webhook_url:
          description: 'DEPRECATED: health check url service checking'
          format: url
          type:
          - string
          - 'null'
        id:
          description: Identifies the type of resource.
          format: uuid
          readOnly: true
          type: string
        mms_fall_back_to_sms:
          default: false
          description: enables SMS fallback for MMS messages.
          type: boolean
        mms_transcoding:
          default: false
          description: enables automated resizing of MMS media.
          type: boolean
        mobile_only:
          default: false
          description: Send messages only to mobile phone numbers.
          type: boolean
        name:
          description: A user friendly name for the messaging profile.
          type: string
        number_pool_settings:
          $ref: '#/components/schemas/NumberPoolSettings'
        organization_id:
          description: The organization that owns this messaging profile.
          type: string
        record_type:
          description: Identifies the type of the resource.
          enum:
          - messaging_profile
          readOnly: true
          type: string
        redaction_enabled:
          default: false
          description: Indicates whether message content redaction is enabled for this profile.
          type: boolean
        redaction_level:
          default: 2
          description: Determines how much information is redacted in messages for privacy or compliance purposes.
          type: integer
        resource_group_id:
          description: The resource group ID associated with this messaging profile.
          type:
          - string
          - 'null'
        smart_encoding:
          default: false
          description: Enables automatic character encoding optimization for SMS messages. When enabled, the system automatically selects the most efficient encoding (GSM-7 or UCS-2) based on message content to maximize character limits and minimize costs.
          type: boolean
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          format: date-time
          readOnly: true
          type: string
        url_shortener_settings:
          $ref: '#/components/schemas/UrlShortenerSettings'
        v1_secret:
          description: Secret used to authenticate with v1 endpoints.
          type: string
        webhook_api_version:
          description: Determines which webhook format will be used, Telnyx API v1, v2, or a legacy 2010-04-01 format.
          enum:
          - '1'
          - '2'
          - '2010-04-01'
          type: string
        webhook_failover_url:
          description: The failover URL where webhooks related to this messaging profile will be sent if sending to the primary URL fails.
          format: url
          type:
          - string
          - 'null'
        webhook_url:
          description: The URL where webhooks related to this messaging profile will be sent.
          format: url
          type:
          - string
          - 'null'
        whitelisted_destinations:
          description: Destinations to which the messaging profile is allowed to send. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed.
          items:
            description: ISO 3166-1 alpha-2 country code.
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      type: object
    ProfileMetricsHighLevel:
      additionalProperties: true
      description: High-level metrics summary for a messaging profile.
      type: object
    UrlShortenerSettings:
      description: 'The URL shortener feature allows automatic replacement of URLs that were generated using

        a public URL shortener service. Some examples include bit.do, bit.ly, goo.gl, ht.ly,

        is.gd, ow.ly, rebrand.ly, t.co, tiny.cc, and tinyurl.com. Such URLs are replaced with

        with links generated by Telnyx. The use of custom links can improve branding and message

        deliverability.


        To disable this feature, set the object field to `null`.

        '
      example:
        domain: example.ex
        prefix: ''
        replace_blacklist_only: true
        send_webhooks: false
      properties:
        domain:
          description: 'One of the domains provided by the Telnyx URL shortener service.

            '
          example: acct.fyi
          type: string
        prefix:
          description: 'Optional prefix that can be used to identify your brand, and will appear in the Telnyx generated URLs after the domain name.

            '
          example: ''
          type: string
        replace_blacklist_only:
          description: 'Use the link replacement tool only for links that are specifically blacklisted by Telnyx.

            '
          example: true
          type: boolean
        send_webhooks:
          description: 'Receive webhooks for when your replaced links are clicked. Webhooks are sent to the webhooks on the messaging profile.

            '
          example: false
          type: boolean
      required:
      - domain
      type:
      - object
      - 'null'
    MessagingMetricsTimeFrame:
      default: 24h
      description: The time frame for metrics aggregation.
      enum:
      - 1h
      - 3h
      - 24h
      - 3d
      - 7d
      - 30d
      title: Messaging Metrics Time Frame
      type: string
    messaging_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/messaging_Error'
          type: array
    UpdatePhoneNumberMessagingSettingsRequest:
      example:
        messaging_product: P2P
        messaging_profile_id: dd50eba1-a0c0-4563-9925-b25e842a7cb6
      properties:
        messaging_product:
          description: 'Configure the messaging product for this number:


            * Omit this field or set its value to `null` to keep the current value.

            * Set this field to a quoted product ID to set this phone number to that product'
          example: P2P
          type: string
        messaging_profile_id:
          description: 'Configure the messaging profile this phone number is assigned to:


            * Omit this field or set its value to `null` to keep the current value.

            * Set this field to `""` to unassign the number from its messaging profile

            * Set this field to a quoted UUID of a messaging profile to assign this number to that messaging profile'
          type: string
        tags:
          description: Tags to set on this phone number.
          items:
            type: string
          type: array
      type: object
    messaging_PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      type: object
    messaging_Error:
      properties:
        code:
          type: string
          x-format: integer
        detail:
          type: string
        meta:
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              format: json-pointer
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
    CreateAlphanumericSenderIdRequest:
      properties:
        alphanumeric_sender_id:
          description: The alphanumeric sender ID string.
          example: MyCompany
          type: string
        messaging_profile_id:
          description: The messaging profile to associate the sender ID with.
          format: uuid
          type: string
        us_long_code_fallback:
          description: A US long code number to use as fallback when sending to US destinations.
          example: '+15551234567'
          type: string
      required:
      - alphanumeric_sender_id
      - messaging_profile_id
      type: object
    PhoneNumberWithMessagingSettings:
      example:
        country_code: US
        created_at: '2019-01-23T18:10:02.574Z'
        eligible_messaging_products:
        - A2P
        features:
          mms: null
          sms:
            domestic_two_way: true
            international_inbound: true
            international_outbound: true
        health:
          inbound_outbound_ratio: 0.43
          message_count: 122
          spam_ratio: 0.06
          success_ratio: 0.94
        id: '1293384261075731499'
        messaging_product: A2P
        messaging_profile_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        phone_number: '+18005550001'
        record_type: messaging_settings
        traffic_type: A2P
        type: tollfree
        updated_at: '2019-01-23T18:10:02.574Z'
      properties:
        country_code:
          description: ISO 3166-1 alpha-2 country code.
          example: US
          pattern: ^[A-Z]{2}$
          readOnly: true
          type: string
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          format: date-time
          readOnly: true
          type: string
        eligible_messaging_products:
          description: The messaging products that this number can be registered to use
          items:
            type: string
          readOnly: true
          type: array
        features:
          properties:
            mms:
              $ref: '#/components/schemas/MessagingFeatureSet'
            sms:
              $ref: '#/components/schemas/MessagingFeatureSet'
          readOnly: true
          type: object
        health:
          $ref: '#/components/schemas/NumberHealthMetrics'
        id:
          description: Identifies the type of resource.
          readOnly: true
          type: string
        messaging_product:
          description: The messaging product that the number is registered to use
          example: P2P
          type: string
        messaging_profile_id:
          description: Unique identifier for a messaging profile.
          type:
          - string
          - 'null'
        organization_id:
          description: The organization that owns this phone number.
          type: string
        phone_number:
          description: +E.164 formatted phone number.
          readOnly: true
          type: string
          x-format: e164
        record_type:
          description: Identifies the type of the resource.
          enum:
          - messaging_phone_number
          - messaging_settings
          example: messaging_settings
          readOnly: true
          type: string
        tags:
          description: Tags associated with this phone number.
          items:
            type: string
          type: array
        traffic_type:
          description: The messaging traffic or use case for which the number is currently configured.
          example: P2P
          readOnly: true
          type: string
        type:
          description: The type of the phone number
          enum:
          - long-code
          - toll-free
          - short-code
          - longcode
          - tollfree
          - shortcode
          readOnly: true
          type: string
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          format: date-time
          readOnly: true
          type: string
      type: object
    NumberHealthMetrics:
      description: 'High level health metrics about the number and it''s messaging sending patterns.

        '
      example:
        inbound_outbound_ratio: 1
        message_count: 10
        spam_ratio: 10
        success_ratio: 2
      properties:
        inbound_outbound_ratio:
          description: The ratio of messages received to the number of messages sent.
          format: float
          type: number
        message_count:
          description: The number of messages analyzed for the health metrics.
          type: integer
        spam_ratio:
          description: The ratio of messages blocked for spam to the number of messages attempted.
          format: float
          type: number
        success_ratio:
          description: The ratio of messages sucessfully delivered to the number of messages attempted.
          format: float
          type: number
      required:
      - message_count
      - inbound_outbound_ratio
      - success_ratio
      - spam_ratio
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http