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 Opt-Out Management 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:
- description: Opt-Out Management
  name: Opt-Out Management
paths:
  /messaging_optouts:
    get:
      description: Retrieve a list of opt-out blocks.
      operationId: ListOptOuts
      parameters:
      - description: If receiving address (+E.164 formatted phone number) should be redacted
        example: +447766****
        in: query
        name: redaction_enabled
        required: false
        schema:
          type: string
          x-format: boolean
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[messaging_profile_id], filter[from]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            from:
              description: The sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code) to retrieve opt-outs for
              type: string
            messaging_profile_id:
              description: The ID of the messaging profile to retrieve opt-outs for
              type: string
          type: object
        style: deepObject
      - $ref: '#/components/parameters/PageConsolidated'
      - description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
        explode: true
        in: query
        name: created_at
        schema:
          properties:
            gte:
              description: Filter opt-outs created after this date (ISO-8601 format)
              format: date-time
              type: string
            lte:
              description: Filter opt-outs created before this date (ISO-8601 format)
              format: date-time
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutListResponse'
          description: Successful response with opt-out list data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Error'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Error'
          description: Unauthorized
      summary: List opt-outs
      tags:
      - Opt-Out Management
      x-latency-category: responsive
  /messaging_profiles/{profile_id}/autoresp_configs:
    get:
      operationId: GetAutorespConfigs
      parameters:
      - in: path
        name: profile_id
        required: true
        schema:
          format: uuid
          title: Profile Id
          type: string
      - in: query
        name: country_code
        required: false
        schema:
          title: Country Code
          type: string
      - description: 'Consolidated created_at parameter (deepObject style). Originally: created_at[gte], created_at[lte]'
        explode: true
        in: query
        name: created_at
        schema:
          properties:
            gte:
              title: Created At[Gte]
              type: string
            lte:
              title: Created At[Lte]
              type: string
          type: object
        style: deepObject
      - description: 'Consolidated updated_at parameter (deepObject style). Originally: updated_at[gte], updated_at[lte]'
        explode: true
        in: query
        name: updated_at
        schema:
          properties:
            gte:
              title: Updated At[Gte]
              type: string
            lte:
              title: Updated At[Lte]
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - country_code: US
                  created_at: '2023-03-21T23:37:45.858535+00:00'
                  id: 677ec1cb-949e-4aeb-a1c3-6d9ddffc1409
                  keywords:
                  - START
                  - BEGIN
                  op: start
                  resp_text: Thank you for subscribing US customer.
                  updated_at: '2023-03-21T23:37:45.858535+00:00'
                - country_code: US
                  created_at: '2023-03-10T21:54:46.293380+00:00'
                  id: 54b7e19f-98a8-416f-81d1-a2782eade48b
                  keywords:
                  - END
                  - STOP
                  op: stop
                  resp_text: You have unsubscribed.
                  updated_at: '2023-03-10T21:54:46.293380+00:00'
                - country_code: '*'
                  created_at: '2023-03-14T14:46:21.097735+00:00'
                  id: cfe07be1-2369-433f-be00-eb176008e834
                  keywords:
                  - START
                  op: start
                  resp_text: Thank you for subscribing.
                  updated_at: '2023-03-14T14:46:21.097735+00:00'
                meta:
                  page_number: 1
                  page_size: 5
                  total_pages: 1
                  total_results: 3
              schema:
                $ref: '#/components/schemas/AutorespConfigsResponseSchema'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: List Auto-Response Settings
      tags:
      - Opt-Out Management
      x-latency-category: responsive
    post:
      operationId: CreateAutorespConfig
      parameters:
      - in: path
        name: profile_id
        required: true
        schema:
          title: Profile Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRespConfigCreateSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  country_code: US
                  created_at: '2023-03-22T00:06:49.068817+00:00'
                  id: c2298f86-a4dc-4cac-b6b6-4a3d01c290fa
                  keywords:
                  - START
                  op: start
                  resp_text: Hello there!
                  updated_at: '2023-03-22T00:06:49.068817+00:00'
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Create auto-response setting
      tags:
      - Opt-Out Management
      x-latency-category: responsive
  /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}:
    delete:
      operationId: DeleteAutorespConfig
      parameters:
      - in: path
        name: profile_id
        required: true
        schema:
          format: uuid
          title: Profile Id
          type: string
      - in: path
        name: autoresp_cfg_id
        required: true
        schema:
          format: uuid
          title: Autoresp Cfg Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                example: OK
                type: string
          description: Successful Response
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Delete Auto-Response Setting
      tags:
      - Opt-Out Management
      x-latency-category: responsive
    get:
      operationId: GetAutorespConfig
      parameters:
      - in: path
        name: profile_id
        required: true
        schema:
          format: uuid
          title: Profile Id
          type: string
      - in: path
        name: autoresp_cfg_id
        required: true
        schema:
          format: uuid
          title: Autoresp Cfg Id
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  country_code: US
                  created_at: '2023-03-13T17:51:03.826453+00:00'
                  id: adc37adf-d110-4355-9e9a-262847e68e89
                  keywords:
                  - UNSTOP
                  op: start
                  resp_text: Hello there!
                  updated_at: '2023-03-13T17:51:03.826453+00:00'
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Get Auto-Response Setting
      tags:
      - Opt-Out Management
      x-latency-category: responsive
    put:
      operationId: UpdateAutoRespConfig
      parameters:
      - in: path
        name: profile_id
        required: true
        schema:
          format: uuid
          title: Profile Id
          type: string
      - in: path
        name: autoresp_cfg_id
        required: true
        schema:
          format: uuid
          title: Autoresp Cfg Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRespConfigCreateSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  country_code: '*'
                  created_at: '2023-03-10T21:54:46.293380+00:00'
                  id: 54b7e19f-98a8-416f-81d1-a2782eade48b
                  keywords:
                  - START
                  - BEGIN
                  op: start
                  resp_text: Hello there!
                  updated_at: '2023-03-10T21:54:46.293380+00:00'
              schema:
                $ref: '#/components/schemas/AutorespConfigResponseSchema'
          description: Successful Response
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Update Auto-Response Setting
      tags:
      - Opt-Out Management
      x-latency-category: responsive
components:
  schemas:
    AutorespConfigSchema:
      properties:
        country_code:
          example: '*'
          title: Country Code
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        id:
          example: b8f9c1c0-5b5a-4b1e-8c1c-0b5a4b1e8c1c
          title: Id
          type: string
        keywords:
          example:
          - START
          - BEGIN
          items:
            type: string
          title: Keywords
          type: array
        op:
          enum:
          - start
          - stop
          - info
          example: start
          title: Op
          type: string
        resp_text:
          example: Thank you for subscribing to our service.
          title: Resp Text
          type: string
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
      - op
      - keywords
      - country_code
      - id
      - created_at
      - updated_at
      title: AutorespConfigSchema
      type: object
    OptOutListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/OptOutItem'
          type: array
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta'
      type: object
    messaging_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/messaging_Error'
          type: array
    AutorespConfigResponseSchema:
      properties:
        data:
          $ref: '#/components/schemas/AutorespConfigSchema'
      required:
      - data
      title: AutorespConfigResponseSchema
      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
    AutorespConfigsResponseSchema:
      description: List of Auto-Response Settings
      properties:
        data:
          items:
            $ref: '#/components/schemas/AutorespConfigSchema'
          title: Data
          type: array
        meta:
          $ref: '#/components/schemas/messaging_PaginationMeta'
      required:
      - data
      - meta
      title: AutorespConfigsResponseSchema
      type: object
    AutoRespConfigCreateSchema:
      properties:
        country_code:
          example: US
          title: Country Code
          type: string
        keywords:
          example:
          - keyword1
          - keyword2
          items:
            type: string
          title: Keywords
          type: array
        op:
          enum:
          - start
          - stop
          - info
          title: Op
          type: string
        resp_text:
          example: Thank you for your message
          title: Resp Text
          type: string
      required:
      - op
      - keywords
      - country_code
      title: AutoRespConfigCreateSchema
      type: object
    ToNumber:
      description: Receiving address (+E.164 formatted phone number or short code).
      example: +E.164
      type: string
      x-format: address
    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
    OptOutItem:
      properties:
        created_at:
          description: The timestamp when the opt-out was created
          example: '2025-04-28 12:00:38.631252+00:00'
          format: date-time
          type: string
        from:
          description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
          type: string
          x-format: address
        keyword:
          description: The keyword that triggered the opt-out.
          example: STOP
          type:
          - string
          - 'null'
        messaging_profile_id:
          description: Unique identifier for a messaging profile.
          type:
          - string
          - 'null'
        to:
          $ref: '#/components/schemas/ToNumber'
      type: object
  responses:
    messaging_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unexpected error
  parameters:
    PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      explode: true
      in: query
      name: page
      schema:
        properties:
          number:
            default: 1
            description: The page number to load
            minimum: 1
            type: integer
          size:
            default: 20
            description: The size of the page
            maximum: 250
            minimum: 1
            type: integer
        type: object
      style: deepObject
  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