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 Dialogflow Integration 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: Dialogflow Connection Operations.
  name: Dialogflow Integration
paths:
  /dialogflow_connections/{connection_id}:
    delete:
      description: Deletes a stored Dialogflow Connection.
      operationId: DeleteDialogflowConnection
      parameters:
      - $ref: '#/components/parameters/media-streaming_ConnectionId'
      responses:
        '204':
          description: The Dialogflow Connection for connection_id was deleted successfully.
        '404':
          $ref: '#/components/responses/media-streaming_NotFoundResponse'
        default:
          $ref: '#/components/responses/media-streaming_GenericErrorResponse'
      summary: Delete stored Dialogflow Connection
      tags:
      - Dialogflow Integration
      x-latency-category: responsive
    get:
      description: Return details of the Dialogflow connection associated with the given CallControl connection.
      operationId: GetDialogflowConnection
      parameters:
      - $ref: '#/components/parameters/media-streaming_ConnectionId'
      responses:
        '200':
          $ref: '#/components/responses/DialogflowConnectionResponseBody'
        '404':
          $ref: '#/components/responses/media-streaming_NotFoundResponse'
        default:
          $ref: '#/components/responses/media-streaming_GenericErrorResponse'
      summary: Retrieve stored Dialogflow Connection
      tags:
      - Dialogflow Integration
      x-latency-category: responsive
    post:
      description: Save Dialogflow Credentiails to Telnyx, so it can be used with other Telnyx services.
      operationId: CreateDialogflowConnection
      parameters:
      - $ref: '#/components/parameters/media-streaming_ConnectionId'
      requestBody:
        $ref: '#/components/requestBodies/DialogflowConnectionRequest'
      responses:
        '201':
          $ref: '#/components/responses/DialogflowConnectionResponseBody'
        '422':
          $ref: '#/components/responses/media-streaming_UnprocessableEntityResponse'
        default:
          $ref: '#/components/responses/media-streaming_GenericErrorResponse'
      summary: Create a Dialogflow Connection
      tags:
      - Dialogflow Integration
      x-latency-category: responsive
    put:
      description: Updates a stored Dialogflow Connection.
      operationId: UpdateDialogflowConnection
      parameters:
      - $ref: '#/components/parameters/media-streaming_ConnectionId'
      requestBody:
        $ref: '#/components/requestBodies/DialogflowConnectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/DialogflowConnectionResponseBody'
        '404':
          $ref: '#/components/responses/media-streaming_NotFoundResponse'
        '422':
          $ref: '#/components/responses/media-streaming_UnprocessableEntityResponse'
        default:
          $ref: '#/components/responses/media-streaming_GenericErrorResponse'
      summary: Update stored Dialogflow Connection
      tags:
      - Dialogflow Integration
      x-latency-category: responsive
components:
  responses:
    media-streaming_UnprocessableEntityResponse:
      content:
        application/json:
          example:
            errors:
            - code: '422'
              detail: The request parameters failed validation.
              source:
                pointer: /service_account
              title: Unprocessable Entity
          schema:
            $ref: '#/components/schemas/media-streaming_Errors'
      description: Unprocessable entity. The request was well-formed but contains semantic errors.
    media-streaming_NotFoundResponse:
      content:
        application/json:
          examples:
            connection_not_found:
              summary: Connection not found
              value:
                errors:
                - code: '10005'
                  detail: The Dialogflow connection for the specified connection_id could not be found.
                  source:
                    pointer: /connection_id
                  title: Resource not found
            not_found:
              summary: Generic not found
              value:
                errors:
                - code: '404'
                  detail: Page not found
                  title: Not Found
          schema:
            $ref: '#/components/schemas/media-streaming_Errors'
      description: Resource not found. The requested resource or URL could not be found.
    DialogflowConnectionResponseBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DialogflowConnectionResponse'
      description: Return details of the Dialogflow connection associated with the given CallControl connection.
    media-streaming_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/media-streaming_Errors'
      description: Unexpected error.
  parameters:
    media-streaming_ConnectionId:
      description: Uniquely identifies a Telnyx application (Call Control).
      in: path
      name: connection_id
      required: true
      schema:
        type: string
  schemas:
    media-streaming_Error:
      properties:
        code:
          type: string
        detail:
          type: string
        meta:
          additionalProperties: true
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    DialogflowConnectionResponse:
      properties:
        data:
          properties:
            connection_id:
              description: Uniquely identifies a Telnyx application (Call Control).
              example: '1234541231'
              type: string
            conversation_profile_id:
              description: The id of a configured conversation profile on your Dialogflow account. (If you use Dialogflow CX, this param is required)
              example: a-VMHLWzTmKjiJw5S6O0-w
              type: string
            environment:
              description: Which Dialogflow environment will be used.
              example: development
              type: string
            record_type:
              example: dialogflow_connections
              type: string
            service_account:
              description: The JSON map to connect your Dialoglow account.
              example: '****'
              type: string
          title: Dialogflow Connection
          type: object
      required:
      - data
      title: Dialogflow Connection Response
      type: object
    DialogflowConnection:
      example:
        conversation_profile_id: a-VMHLWzTmKjiJw5S6O0-w
        dialogflow_api: cx
        environment: development
        location: global
        service_account:
          auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
          auth_uri: https://accounts.google.com/o/oauth2/auth
          client_email: example@example.com
          client_id: your-client-id
          client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/example%40example.iam.gserviceaccount.com
          private_key: '-----BEGIN PRIVATE KEY-----

            -----END PRIVATE KEY-----'
          private_key_id: your-private-key
          project_id: your-project-id
          token_uri: https://oauth2.googleapis.com/token
          type: service_account
      properties:
        conversation_profile_id:
          description: The id of a configured conversation profile on your Dialogflow account. (If you use Dialogflow CX, this param is required)
          example: a-VMHLWzTmKjiJw5S6O0-w
          type: string
        dialogflow_api:
          default: es
          description: Determine which Dialogflow will be used.
          enum:
          - cx
          - es
          example: cx
          type: string
        environment:
          description: Which Dialogflow environment will be used.
          example: development
          type: string
        location:
          description: The region of your agent is. (If you use Dialogflow CX, this param is required)
          example: global
          type: string
        service_account:
          additionalProperties: true
          description: The JSON map to connect your Dialoglow account.
          type: object
      required:
      - service_account
      title: Dialogflow Connection Params
      type: object
    media-streaming_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/media-streaming_Error'
          type: array
      type: object
  requestBodies:
    DialogflowConnectionRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DialogflowConnection'
      description: The params expected to create/update a Dialogflow Connection for given connection_id.
      required: true
  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