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 Whatsapp Message Templates 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: Manage Whatsapp message templates
  name: Whatsapp Message Templates
paths:
  /v2/whatsapp/message_templates:
    get:
      operationId: ListWhatsappTemplates
      parameters:
      - $ref: '#/components/parameters/PageConsolidated'
      - description: Filter by WABA ID
        in: query
        name: filter[waba_id]
        schema:
          type: string
      - description: Filter by category
        in: query
        name: filter[category]
        schema:
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
          type: string
      - description: Filter by template status
        in: query
        name: filter[status]
        schema:
          type: string
      - description: Search templates by name
        in: query
        name: filter[search]
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/WhatsappTemplateListResponse'
          description: Whatsapp templates list
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: List Whatsapp message templates
      tags:
      - Whatsapp Message Templates
      x-latency-category: responsive
    post:
      operationId: PostWhatsappTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappCreateTemplateRequest'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
          description: Template created
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Create a Whatsapp message template
      tags:
      - Whatsapp Message Templates
      x-latency-category: responsive
  /v2/whatsapp_message_templates/{id}:
    delete:
      operationId: DeleteWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '204':
          description: Deleted
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Delete a Whatsapp message template
      tags:
      - Whatsapp Message Templates
      x-latency-category: responsive
    get:
      operationId: GetWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '200':
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
          description: Template details
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Get a Whatsapp message template by ID
      tags:
      - Whatsapp Message Templates
      x-latency-category: responsive
    patch:
      operationId: PatchWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappUpdateTemplateRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
          description: Updated template
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
      summary: Update a Whatsapp message template
      tags:
      - Whatsapp Message Templates
      x-latency-category: responsive
components:
  parameters:
    WhatsappTemplateId:
      description: Whatsapp message template ID
      in: path
      name: id
      required: true
      schema:
        type: string
    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
  schemas:
    messaging_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/messaging_Error'
          type: array
    WhatsappTemplateFooterComponent:
      description: Optional footer displayed at the bottom of the message. Does not support variables.
      properties:
        code_expiration_minutes:
          description: OTP code expiration time in minutes. Used in AUTHENTICATION template footers instead of free-form text.
          type: integer
        text:
          description: Footer text. Maximum 60 characters. For non-authentication templates.
          maxLength: 60
          type: string
        type:
          enum:
          - FOOTER
          type: string
      required:
      - type
      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
    WhatsappTemplateBodyComponent:
      description: The main text content of the message. Supports multiple variable parameters ({{1}}, {{2}}, etc.). Variables cannot be at the start or end. Maximum 1024 characters.
      properties:
        example:
          description: Sample values for body variables. Required when body text contains parameters.
          properties:
            body_text:
              description: Array containing one array of sample values, one per variable in order.
              items:
                items:
                  type: string
                type: array
              type: array
          type: object
        text:
          description: Body text content. Use {{1}}, {{2}}, etc. for variable placeholders. Required for MARKETING and UTILITY templates. Optional for AUTHENTICATION templates where Meta provides the built-in OTP body.
          maxLength: 1024
          type: string
        type:
          enum:
          - BODY
          type: string
      required:
      - type
      type: object
    WhatsappTemplateButtonsComponent:
      description: Optional interactive buttons. Maximum 3 buttons per template.
      properties:
        buttons:
          description: Array of button objects. Meta supports various combinations of button types.
          items:
            properties:
              autofill_text:
                description: Custom autofill button text for ONE_TAP OTP buttons.
                type: string
              example:
                description: Sample values for URL variable.
                items:
                  type: string
                type: array
              flow_action:
                description: Flow action type for FLOW-type buttons.
                enum:
                - navigate
                - data_exchange
                type: string
              flow_id:
                description: Flow ID for FLOW-type buttons.
                type: string
              navigate_screen:
                description: Target screen name for FLOW buttons with navigate action.
                type: string
              otp_type:
                enum:
                - COPY_CODE
                - ONE_TAP
                type: string
              package_name:
                description: Android package name. Required for ONE_TAP OTP buttons.
                type: string
              phone_number:
                description: Phone number in E.164 format.
                type: string
              signature_hash:
                description: Android app signing key hash. Required for ONE_TAP OTP buttons.
                type: string
              text:
                description: Button label text. Maximum 25 characters. Required for URL, PHONE_NUMBER, and QUICK_REPLY buttons. Not required for OTP buttons (Meta supplies the label).
                maxLength: 25
                type: string
              type:
                enum:
                - URL
                - PHONE_NUMBER
                - QUICK_REPLY
                - OTP
                - COPY_CODE
                - FLOW
                type: string
              url:
                description: URL for URL-type buttons. Supports one variable ({{1}}).
                type: string
              zero_tap_terms_accepted:
                description: Whether zero-tap terms have been accepted.
                type: boolean
            required:
            - type
            type: object
          type: array
        type:
          enum:
          - BUTTONS
          type: string
      required:
      - type
      - buttons
      type: object
    WhatsappUpdateTemplateRequest:
      properties:
        category:
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
          type: string
        components:
          description: Updated template components. Same structure as the create request.
          items:
            description: A template component. Additional Meta component types not listed here are also accepted.
            oneOf:
            - $ref: '#/components/schemas/WhatsappTemplateHeaderComponent'
            - $ref: '#/components/schemas/WhatsappTemplateBodyComponent'
            - $ref: '#/components/schemas/WhatsappTemplateFooterComponent'
            - $ref: '#/components/schemas/WhatsappTemplateButtonsComponent'
            - $ref: '#/components/schemas/WhatsappTemplateCarouselComponent'
          type: array
      type: object
    WhatsappCreateTemplateRequest:
      properties:
        category:
          description: 'Template category: AUTHENTICATION, UTILITY, or MARKETING.'
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
          type: string
        components:
          description: Template components defining message structure. Passed through to Meta Graph API. Templates with variables must include example values. Supports HEADER, BODY, FOOTER, BUTTONS, CAROUSEL and any future Meta component types.
          items:
            description: A template component. Additional Meta component types not listed here are also accepted.
            oneOf:
            - $ref: '#/components/schemas/WhatsappTemplateHeaderComponent'
            - $ref: '#/components/schemas/WhatsappTemplateBodyComponent'
            - $ref: '#/components/schemas/WhatsappTemplateFooterComponent'
            - $ref: '#/components/schemas/WhatsappTemplateButtonsComponent'
            - $ref: '#/components/schemas/WhatsappTemplateCarouselComponent'
          type: array
        language:
          description: Template language code (e.g. en_US, es, pt_BR).
          type: string
        name:
          description: Template name. Lowercase letters, numbers, and underscores only.
          type: string
        waba_id:
          description: The WhatsApp Business Account ID.
          type: string
      required:
      - waba_id
      - name
      - category
      - language
      - components
      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
    WhatsappTemplateHeaderComponent:
      description: Optional header displayed at the top of the message.
      properties:
        example:
          description: Sample values for header variables.
          properties:
            header_handle:
              description: Media handle for IMAGE, VIDEO, or DOCUMENT headers.
              items:
                type: string
              type: array
            header_text:
              description: Sample values for text header variables.
              items:
                type: string
              type: array
          type: object
        format:
          description: 'Header format type: TEXT (supports one variable), IMAGE, VIDEO, DOCUMENT, or LOCATION.'
          enum:
          - TEXT
          - IMAGE
          - VIDEO
          - DOCUMENT
          - LOCATION
          type: string
        text:
          description: Header text. Required when format is TEXT. Supports one variable ({{1}}). Variables cannot be at the start or end.
          type: string
        type:
          enum:
          - HEADER
          type: string
      required:
      - type
      - format
      type: object
    WhatsappTemplateCarouselComponent:
      description: Carousel component for multi-card templates. Each card can contain its own header, body, and buttons.
      properties:
        cards:
          description: Array of card objects, each with its own components.
          items:
            properties:
              components:
                items:
                  type: object
                type: array
            type: object
          type: array
        type:
          enum:
          - CAROUSEL
          type: string
      required:
      - type
      - cards
      type: object
    WhatsappTemplateData:
      properties:
        category:
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
          type: string
        components:
          description: Template components (header, body, footer, buttons) as submitted, including example values.
          items:
            type: object
          type: array
        created_at:
          format: date-time
          type: string
        id:
          type: string
        language:
          type: string
        name:
          type: string
        record_type:
          example: whatsapp_message_template
          type: string
        rejection_reason:
          type: string
        status:
          description: Current template status from Meta (e.g. PENDING, APPROVED, REJECTED, PAUSED, DISABLED). Additional statuses may be returned as Meta evolves the template lifecycle.
          type: string
        template_id:
          type: string
        updated_at:
          format: date-time
          type: string
        whatsapp_business_account:
          properties:
            id:
              type: string
          type: object
      type: object
  responses:
    messaging_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unexpected error
    WhatsappTemplateSingleResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/WhatsappTemplateData'
            type: object
      description: Successful response with Whatsapp template
    WhatsappTemplateListResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/WhatsappTemplateData'
                type: array
              meta:
                $ref: '#/components/schemas/messaging_PaginationMeta'
            type: object
      description: Successful response with Whatsapp template
  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