> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit a new WhatsApp template for Meta approval

> Submit a new WhatsApp template for Meta approval — For when nothing in the org fits.



## OpenAPI

````yaml post /whatsapp/templates
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /whatsapp/templates:
    post:
      summary: Submit a new WhatsApp template for Meta approval
      description: >-
        For when nothing in the org fits. Takes header/body/footer text — the
        components payload is assembled server-side and the WABA resolved — and
        submits it. It comes back PENDING: review takes minutes to hours, work
        can continue meanwhile, and a sequence referencing it can even launch —
        sends start the moment it is APPROVED.
      operationId: createWhatsappTemplateDraft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWhatsAppTemplateDraftDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWhatsAppTemplateDraftResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    CreateWhatsAppTemplateDraftDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/CreateWhatsAppTemplateDraftDtoInput'
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 512
          pattern: ^[a-z0-9_]+$
        language:
          type: string
          minLength: 1
          description: BCP-47 code, e.g. en_US, ar, ar_SA.
        category:
          type: string
          enum:
            - UTILITY
            - MARKETING
            - AUTHENTICATION
          description: >-
            UTILITY for a follow-up on something the person already contacted
            you about; MARKETING for a promotion (opt-out gated, worse
            delivery). Meta re-categorizes what it disagrees with.
        body_text:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            Placeholders as {{1}}, {{2}} in order, or {{named}}. Never mix the
            two styles.
        body_variable_examples:
          default: []
          description: >-
            A realistic sample value per placeholder, in body order. Meta
            REJECTS templates whose placeholders have no examples, so an empty
            list with a placeholder-bearing body is refused here rather than
            hours later.
          maxItems: 20
          type: array
          items:
            type: string
            minLength: 1
        header_text:
          description: Plain text only, no placeholders.
          type: string
          minLength: 1
          maxLength: 60
        footer_text:
          type: string
          minLength: 1
          maxLength: 60
        buttons:
          default: []
          description: >-
            In display order. Quick replies must sit together — all before or
            all after the other kinds (Meta groups them). Up to 10.
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/CreateWhatsAppTemplateDraftButtonDto'
        message_send_ttl_seconds:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Message validity period in seconds. Authentication: 30–900, Utility:
            30–43200, Marketing: 43200–2592000. -1 = explicit 30-day TTL
            (authentication/utility only).
        waba_id:
          description: Only needed when the org has more than one WABA; otherwise resolved.
          type: string
      required:
        - name
        - language
        - category
        - body_text
    CreateWhatsAppTemplateDraftResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/CreateWhatsAppTemplateDraftResponseDto'
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        language:
          type: string
        status:
          type: string
          enum:
            - APPROVED
            - REJECTED
            - PENDING
            - PAUSED
            - DISABLED
            - IN_APPEAL
            - PENDING_DELETION
            - DELETED
            - LIMIT_EXCEEDED
            - ARCHIVED
        category:
          type: string
          enum:
            - UTILITY
            - MARKETING
            - AUTHENTICATION
          description: What Meta FILED it as, which may differ from what was requested.
        variables:
          type: array
          items:
            type: string
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/WhatsAppTemplateButtonOptionDto'
          description: Which indexes take a step binding — see needs_value.
        sendable:
          type: boolean
          description: >-
            Effectively always false on create: Meta review takes minutes to
            hours. Reference it from a step now — a pending template does not
            block launch; sends start the moment it clears.
      required:
        - id
        - name
        - language
        - status
        - category
        - variables
        - buttons
        - sendable
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    CreateWhatsAppTemplateDraftButtonDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/CreateWhatsAppTemplateDraftButtonDtoInput'
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: QUICK_REPLY
            text:
              type: string
              minLength: 1
              maxLength: 25
              description: The label, 25 chars.
          required:
            - type
            - text
        - type: object
          properties:
            type:
              type: string
              const: URL
            text:
              type: string
              minLength: 1
              maxLength: 25
              description: The label, 25 chars.
            url:
              type: string
              minLength: 1
              maxLength: 2000
              description: >-
                Static, or ending in exactly one {{1}} for a per-message suffix
                (https://open.cx/track/{{1}}). A suffix button needs a step
                binding to send.
            url_example:
              description: >-
                REQUIRED when the url ends in {{1}}: the full url with a
                realistic suffix, for review. Omit for a static url.
              type: string
              minLength: 1
              maxLength: 2000
          required:
            - type
            - text
            - url
        - type: object
          properties:
            type:
              type: string
              const: PHONE_NUMBER
            text:
              type: string
              minLength: 1
              maxLength: 25
              description: The label, 25 chars.
            phone_number:
              type: string
              minLength: 1
              maxLength: 20
              description: E.164, e.g. +962790000000.
          required:
            - type
            - text
            - phone_number
        - type: object
          properties:
            type:
              type: string
              const: COPY_CODE
            example:
              type: string
              minLength: 1
              maxLength: 15
              description: >-
                A sample coupon, 15 chars. The real code is bound per message on
                the step.
          required:
            - type
            - example
    WhatsAppTemplateButtonOptionDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/WhatsAppTemplateButtonOptionDto'
      type: object
      properties:
        index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Meta's 0-based button index — the key a step's `buttons` binding
            uses.
        type:
          type: string
          enum:
            - QUICK_REPLY
            - URL
            - PHONE_NUMBER
            - COPY_CODE
            - FLOW
            - MPM
        text:
          description: The label. Null for a copy-code or product button.
          type:
            - string
            - 'null'
        needs_value:
          type: boolean
          description: >-
            True for a URL button whose link ends in a placeholder (the suffix)
            and for a copy-code button (the coupon). Each such index needs a
            binding in the step content; the rest take none.
      required:
        - index
        - type
        - text
        - needs_value
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.