{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/telnyx/json-schema/telnyx-whatsapp-create-template-request-schema.json",
  "title": "WhatsappCreateTemplateRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/telnyx-whatsapp-message-templates-api-openapi.yml#/components/schemas/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": "#/$defs/WhatsappTemplateHeaderComponent"
          },
          {
            "$ref": "#/$defs/WhatsappTemplateBodyComponent"
          },
          {
            "$ref": "#/$defs/WhatsappTemplateFooterComponent"
          },
          {
            "$ref": "#/$defs/WhatsappTemplateButtonsComponent"
          },
          {
            "$ref": "#/$defs/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",
  "$defs": {
    "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": {
        "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"
              },
              "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"
    },
    "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"
    },
    "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"
    },
    "WhatsappTemplateHeaderComponent": {
      "description": "Optional header displayed at the top of the message.",
      "properties": {
        "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"
    }
  }
}