Telnyx Whatsapp Message Templates API

openapi: 3.2.0
info:
  title: Telnyx Whatsapp Message Templates API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Whatsapp Message Templates across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Whatsapp Message Templates
  description: Manage Whatsapp message templates
paths:
  /v2/whatsapp/message_templates:
    get:
      tags:
      - Whatsapp Message Templates
      summary: List Whatsapp message templates
      operationId: ListWhatsappTemplates
      parameters:
      - $ref: '#/components/parameters/PageConsolidated'
      - name: filter[waba_id]
        in: query
        schema:
          type: string
        description: Filter by WABA ID
      - name: filter[category]
        in: query
        schema:
          type: string
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
        description: Filter by category
      - name: filter[status]
        in: query
        schema:
          type: string
        description: Filter by template status
      - name: filter[search]
        in: query
        schema:
          type: string
        description: Search templates by name
      responses:
        '200':
          description: Whatsapp templates list
          $ref: '#/components/responses/messaging_WhatsappTemplateListResponse'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Returns WhatsApp message templates owned by the authenticated account, including their current review state.
    post:
      tags:
      - Whatsapp Message Templates
      summary: Create a Whatsapp message template
      operationId: PostWhatsappTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappCreateTemplateRequest'
      responses:
        '201':
          description: Template created
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Creates a WhatsApp message template for review and subsequent use in template messages.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /v2/whatsapp_message_templates/{id}:
    delete:
      tags:
      - Whatsapp Message Templates
      summary: Delete a Whatsapp message template
      operationId: DeleteWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '204':
          description: Deleted
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Deletes the specified WhatsApp message template.
    get:
      tags:
      - Whatsapp Message Templates
      summary: Get a Whatsapp message template by ID
      operationId: GetWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '200':
          description: Template details
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Returns the content, components, language, and current review state of the specified WhatsApp message template.
    patch:
      tags:
      - Whatsapp Message Templates
      summary: Update a Whatsapp message template
      operationId: PatchWhatsappTemplate
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappUpdateTemplateRequest'
      responses:
        '200':
          description: Updated template
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
      description: Updates the editable fields of the specified WhatsApp message template.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /whatsapp/message_templates:
    get:
      tags:
      - Whatsapp Message Templates
      summary: List Whatsapp message templates
      operationId: ListWhatsappTemplates_2
      parameters:
      - $ref: '#/components/parameters/PageConsolidated'
      - name: filter[waba_id]
        in: query
        schema:
          type: string
        description: Filter by WABA ID
      - name: filter[category]
        in: query
        schema:
          type: string
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
        description: Filter by category
      - name: filter[status]
        in: query
        schema:
          type: string
        description: Filter by template status
      - name: filter[search]
        in: query
        schema:
          type: string
        description: Search templates by name
      responses:
        '200':
          description: Whatsapp templates list
          $ref: '#/components/responses/WhatsappTemplateListResponse'
        4XX:
          $ref: '#/components/responses/management_messaging_GenericErrorResponse'
      x-latency-category: responsive
      description: Retrieve the WhatsApp message templates for your WhatsApp Business Accounts.
    post:
      tags:
      - Whatsapp Message Templates
      summary: Create a Whatsapp message template
      operationId: PostWhatsappTemplate_2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappCreateTemplateRequest'
      responses:
        '201':
          description: Template created
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/management_messaging_GenericErrorResponse'
      x-latency-category: responsive
      description: Create a new WhatsApp message template. Templates must be approved by WhatsApp before they can be used in messages.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /whatsapp/message_templates/{id}:
    delete:
      tags:
      - Whatsapp Message Templates
      summary: Delete a Whatsapp message template
      operationId: DeleteWhatsappTemplate_2
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '204':
          description: Deleted
        4XX:
          $ref: '#/components/responses/management_messaging_GenericErrorResponse'
      x-latency-category: responsive
      description: Permanently deletes the specified WhatsApp message template from your account.
    get:
      tags:
      - Whatsapp Message Templates
      summary: Get a Whatsapp message template by ID
      operationId: GetWhatsappTemplate_2
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      responses:
        '200':
          description: Template details
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/management_messaging_GenericErrorResponse'
      x-latency-category: responsive
      description: Retrieve a specific WhatsApp message template by its ID.
    patch:
      tags:
      - Whatsapp Message Templates
      summary: Update a Whatsapp message template
      operationId: PatchWhatsappTemplate_2
      parameters:
      - $ref: '#/components/parameters/WhatsappTemplateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappUpdateTemplateRequest'
      responses:
        '200':
          description: Updated template
          $ref: '#/components/responses/WhatsappTemplateSingleResponse'
        4XX:
          $ref: '#/components/responses/management_messaging_GenericErrorResponse'
      x-latency-category: responsive
      description: Update an existing WhatsApp message template.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    WhatsappTemplateButtonsComponent:
      type: object
      description: Optional interactive buttons. Maximum 3 buttons per template.
      required:
      - type
      - buttons
      properties:
        type:
          type: string
          enum:
          - BUTTONS
        buttons:
          type: array
          items:
            type: object
            required:
            - type
            properties:
              type:
                type: string
                enum:
                - URL
                - PHONE_NUMBER
                - QUICK_REPLY
                - OTP
                - COPY_CODE
                - FLOW
              text:
                type: string
                maxLength: 25
                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).
              url:
                type: string
                description: URL for URL-type buttons. Supports one variable ({{1}}).
              phone_number:
                type: string
                description: Phone number in E.164 format.
              otp_type:
                type: string
                enum:
                - COPY_CODE
                - ONE_TAP
              example:
                type: array
                items:
                  type: string
                description: Sample values for URL variable.
              package_name:
                type: string
                description: Android package name. Required for ONE_TAP OTP buttons.
              signature_hash:
                type: string
                description: Android app signing key hash. Required for ONE_TAP OTP buttons.
              autofill_text:
                type: string
                description: Custom autofill button text for ONE_TAP OTP buttons.
              zero_tap_terms_accepted:
                type: boolean
                description: Whether zero-tap terms have been accepted.
              flow_id:
                type: string
                description: Flow ID for FLOW-type buttons.
              flow_action:
                type: string
                enum:
                - navigate
                - data_exchange
                description: Flow action type for FLOW-type buttons.
              navigate_screen:
                type: string
                description: Target screen name for FLOW buttons with navigate action.
          description: Array of button objects. Meta supports various combinations of button types.
    messaging_Errors:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/messaging_Error'
    WhatsappTemplateCarouselComponent:
      type: object
      description: Carousel component for multi-card templates. Each card can contain its own header, body, and buttons.
      required:
      - type
      - cards
      properties:
        type:
          type: string
          enum:
          - CAROUSEL
        cards:
          type: array
          description: Array of card objects, each with its own components.
          items:
            type: object
            properties:
              components:
                type: array
                items:
                  type: object
    messaging_PaginationMeta_0b38e7044b:
      type: object
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      properties:
        total_pages:
          type: integer
          example: 3
        total_results:
          type: integer
          example: 55
        page_number:
          type: integer
          example: 2
        page_size:
          type: integer
          example: 25
    WhatsappTemplateHeaderComponent:
      type: object
      description: Optional header displayed at the top of the message.
      required:
      - type
      - format
      properties:
        type:
          type: string
          enum:
          - HEADER
        format:
          type: string
          enum:
          - TEXT
          - IMAGE
          - VIDEO
          - DOCUMENT
          - LOCATION
          description: 'Header format type: TEXT (supports one variable), IMAGE, VIDEO, DOCUMENT, or LOCATION.'
        text:
          type: string
          description: Header text. Required when format is TEXT. Supports one variable ({{1}}). Variables cannot be at the start or end.
        example:
          type: object
          description: Sample values for header variables.
          properties:
            header_text:
              type: array
              items:
                type: string
              description: Sample values for text header variables.
            header_handle:
              type: array
              items:
                type: string
              description: Media handle for IMAGE, VIDEO, or DOCUMENT headers.
    messaging_Errors_0b38e7044b:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/messaging_Error_0b38e7044b'
    WhatsappCreateTemplateRequest:
      type: object
      required:
      - waba_id
      - name
      - category
      - language
      - components
      properties:
        waba_id:
          type: string
          description: The WhatsApp Business Account ID.
        name:
          type: string
          description: Template name. Lowercase letters, numbers, and underscores only.
        category:
          type: string
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
          description: 'Template category: AUTHENTICATION, UTILITY, or MARKETING.'
        language:
          type: string
          description: Template language code (e.g. en_US, es, pt_BR).
        components:
          type: array
          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:
            oneOf:
            - $ref: '#/components/schemas/WhatsappTemplateHeaderComponent'
            - $ref: '#/components/schemas/WhatsappTemplateBodyComponent'
            - $ref: '#/components/schemas/WhatsappTemplateFooterComponent'
            - $ref: '#/components/schemas/WhatsappTemplateButtonsComponent'
            - $ref: '#/components/schemas/WhatsappTemplateCarouselComponent'
            description: A template component. Additional Meta component types not listed here are also accepted.
    messaging_PaginationMeta:
      type: object
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      properties:
        total_pages:
          type: integer
          example: 3
        total_results:
          type: integer
          example: 55
        page_number:
          type: integer
          example: 2
        page_size:
          type: integer
          example: 25
    WhatsappTemplateData:
      type: object
      properties:
        id:
          type: string
        record_type:
          type: string
          example: whatsapp_message_template
        template_id:
          type: string
        name:
          type: string
        category:
          type: string
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
        language:
          type: string
        status:
          type: string
          description: Current template status from Meta (e.g. PENDING, APPROVED, REJECTED, PAUSED, DISABLED). Additional statuses may be returned as Meta evolves the template lifecycle.
        rejection_reason:
          type: string
        components:
          type: array
          items:
            type: object
          description: Template components (header, body, footer, buttons) as submitted, including example values.
        whatsapp_business_account:
          type: object
          properties:
            id:
              type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    messaging_Error_0b38e7044b:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: integer
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
    WhatsappTemplateBodyComponent:
      type: object
      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.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - BODY
        text:
          type: string
          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
        example:
          type: object
          description: Sample values for body variables. Required when body text contains parameters.
          properties:
            body_text:
              type: array
              description: Array containing one array of sample values, one per variable in order.
              items:
                type: array
                items:
                  type: string
    WhatsappUpdateTemplateRequest:
      type: object
      properties:
        category:
          type: string
          enum:
          - MARKETING
          - UTILITY
          - AUTHENTICATION
        components:
          type: array
          description: Updated template components. Same structure as the create request.
          items:
            oneOf:
            - $ref: '#/components/schemas/WhatsappTemplateHeaderComponent'
            - $ref: '#/components/schemas/WhatsappTemplateBodyComponent'
            - $ref: '#/components/schemas/WhatsappTemplateFooterComponent'
            - $ref: '#/components/schemas/WhatsappTemplateButtonsComponent'
            - $ref: '#/components/schemas/WhatsappTemplateCarouselComponent'
            description: A template component. Additional Meta component types not listed here are also accepted.
    messaging_Error:
      required:
      - code
      - title
      properties:
        code:
          type: string
          x-format: integer
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
    WhatsappTemplateFooterComponent:
      type: object
      description: Optional footer displayed at the bottom of the message. Does not support variables.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - FOOTER
        text:
          type: string
          description: Footer text. Maximum 60 characters. For non-authentication templates.
          maxLength: 60
        code_expiration_minutes:
          type: integer
          description: OTP code expiration time in minutes. Used in AUTHENTICATION template footers instead of free-form text.
  responses:
    WhatsappTemplateListResponse:
      description: Successful response with Whatsapp template
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/WhatsappTemplateData'
              meta:
                $ref: '#/components/schemas/messaging_PaginationMeta'
    management_messaging_GenericErrorResponse:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
          example:
            errors:
            - code: string
              title: string
              detail: string
              source:
                pointer: /data/attributes/phone_number
                parameter: string
    messaging_GenericErrorResponse_0b38e7044b:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors_0b38e7044b'
          example:
            errors:
            - code: string
              title: string
              detail: string
              source:
                pointer: /data/attributes/phone_number
                parameter: string
    messaging_WhatsappTemplateListResponse:
      description: Successful response with Whatsapp template
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/WhatsappTemplateData'
              meta:
                $ref: '#/components/schemas/messaging_PaginationMeta_0b38e7044b'
    WhatsappTemplateSingleResponse:
      description: Successful response with Whatsapp template
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/WhatsappTemplateData'
    messaging_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
      description: Unexpected error
  parameters:
    PageConsolidated:
      name: page
      in: query
      style: deepObject
      explode: true
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      schema:
        type: object
        properties:
          number:
            type: integer
            minimum: 1
            default: 1
            description: The page number to load
          size:
            type: integer
            minimum: 1
            maximum: 250
            default: 20
            description: The size of the page
    WhatsappTemplateId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Whatsapp message template ID
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt