{
  "openapi": "3.1.0",
  "info": {
    "title": "Namirial WhatsApp Gateway API",
    "version": "2.1.0.0",
    "description": "API for sending WhatsApp messages via the Namirial WhatsApp Gateway. Supports template-based messaging, OTP delivery, and template management.\n\nAuthentication requires both Basic Auth credentials and an API key header (`X-Api-Key`). See the [Authentication](#section/Authentication) section for details."
  },
  "externalDocs": {
    "description": "Namirial WhatsApp Gateway documentation",
    "url": "https://docs.namirial.app/products/whatsapp/"
  },
  "servers": [
    {
      "url": "https://wa.namirialtsp.com",
      "description": "Production environment"
    },
    {
      "url": "https://wa.test.namirialtsp.com",
      "description": "Testing environment"
    }
  ],
  "tags": [
    {
      "name": "Services",
      "description": "Send WhatsApp messages to end users.",
      "externalDocs": {
        "description": "WhatsApp Gateway documentation",
        "url": "https://docs.namirial.app/products/whatsapp/"
      }
    },
    {
      "name": "Template",
      "description": "Manage WhatsApp message templates.",
      "externalDocs": {
        "description": "WhatsApp Gateway documentation",
        "url": "https://docs.namirial.app/products/whatsapp/"
      }
    },
    {
      "name": "Public",
      "description": "Public endpoints. No authentication required.",
      "externalDocs": {
        "description": "WhatsApp Gateway documentation",
        "url": "https://docs.namirial.app/products/whatsapp/"
      }
    }
  ],
  "security": [
    {
      "basicAuth": [],
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/services/send": {
      "post": {
        "tags": [
          "Services"
        ],
        "summary": "Send a WhatsApp message",
        "description": "Sends a WhatsApp message to the specified recipient using a pre-approved utility template. Supports body parameters, URL buttons, and an optional reference for tracking. See [Send a message](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/api-references/send-message-apis/send) for details.",
        "operationId": "sendWhatsAppMessage",
        "parameters": [],
        "requestBody": {
          "description": "WhatsApp message request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendRequest"
              },
              "example": {
                "to": "+390000000000",
                "language": "it",
                "templateId": 3,
                "body": {
                  "parameters": [
                    {
                      "text": "Rome"
                    },
                    {
                      "text": "m.rossi"
                    }
                  ]
                },
                "urlButtons": [
                  {
                    "index": 0,
                    "urlPath": "/my/url/path"
                  }
                ],
                "reference": {
                  "service": "DIGITALSIGN",
                  "action": "AUTH",
                  "key": "ext-key-001"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                },
                "example": {
                  "messageId": "3425151601"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — missing or malformed parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidInput": {
                    "summary": "Invalid input",
                    "value": {
                      "type": "ConstraintViolationException",
                      "code": 3,
                      "message": "Parameter 'template' must not be empty and > 0"
                    }
                  },
                  "invalidTemplate": {
                    "summary": "Invalid template",
                    "value": {
                      "type": "InvalidTemplateException",
                      "code": 7,
                      "message": "Template not found or not approved"
                    }
                  },
                  "wrongNumber": {
                    "summary": "Wrong destination number",
                    "value": {
                      "type": "WrongNumberException",
                      "code": 8,
                      "message": "NO_VALID_RECIPIENT"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCredentials": {
                    "summary": "Invalid credentials",
                    "value": {
                      "type": "AuthenticationFailedException",
                      "code": 1,
                      "message": "Invalid credentials"
                    }
                  },
                  "missingApiKey": {
                    "summary": "Missing API key",
                    "value": {
                      "type": "MissingApiKeyException",
                      "code": 9,
                      "message": "Missing API key"
                    }
                  },
                  "invalidApiKey": {
                    "summary": "Invalid API key",
                    "value": {
                      "type": "InvalidApiKeyException",
                      "code": 9,
                      "message": "Invalid API Key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the account does not have the required role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "forbidden": {
                    "summary": "Insufficient role",
                    "value": {
                      "type": "ForbiddenException",
                      "code": 6,
                      "message": "Current role [USER], missing role [ADMIN, TEMPLATE_ADMIN]"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/services/send-otp": {
      "post": {
        "tags": [
          "Services"
        ],
        "summary": "Send a WhatsApp OTP message",
        "description": "Sends a one-time password (OTP) via WhatsApp using a pre-approved authentication template. See [Send an OTP message](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/api-references/send-message-apis/send-otp) for details.",
        "operationId": "sendWhatsAppOtp",
        "parameters": [],
        "requestBody": {
          "description": "WhatsApp OTP request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendOtpRequest"
              },
              "example": {
                "to": "+390000000000",
                "language": "it",
                "templateId": 1,
                "otp": "123456",
                "reference": {
                  "service": "DIGITALSIGN",
                  "action": "2FA",
                  "key": "ext-key-002"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP message sent successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                },
                "example": {
                  "messageId": "3425151601"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — missing or malformed parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingOtp": {
                    "summary": "Missing OTP code",
                    "value": {
                      "type": "ConstraintViolationException",
                      "code": 3,
                      "message": "Parameter 'otp' must not be empty"
                    }
                  },
                  "invalidTemplateId": {
                    "summary": "Invalid template ID",
                    "value": {
                      "type": "ConstraintViolationException",
                      "code": 3,
                      "message": "Template ID not valid"
                    }
                  },
                  "wrongNumber": {
                    "summary": "Wrong destination number",
                    "value": {
                      "type": "WrongNumberException",
                      "code": 8,
                      "message": "NO_VALID_RECIPIENT"
                    }
                  },
                  "templateNotFound": {
                    "summary": "Template not found",
                    "value": {
                      "type": "InvalidTemplateException",
                      "code": 7,
                      "message": "Invalid template"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCredentials": {
                    "summary": "Invalid credentials",
                    "value": {
                      "type": "AuthenticationFailedException",
                      "code": 1,
                      "message": "Invalid credentials"
                    }
                  },
                  "missingApiKey": {
                    "summary": "Missing API key",
                    "value": {
                      "type": "MissingApiKeyException",
                      "code": 9,
                      "message": "Missing API key"
                    }
                  },
                  "invalidApiKey": {
                    "summary": "Invalid API key",
                    "value": {
                      "type": "InvalidApiKeyException",
                      "code": 9,
                      "message": "Invalid API Key"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/template/create": {
      "post": {
        "tags": [
          "Template"
        ],
        "summary": "Create a template",
        "description": "Creates a new WhatsApp message template. Templates must be approved by WhatsApp before they can be used for sending messages.",
        "operationId": "createTemplate",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template created successfully."
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidCategory": {
                    "summary": "Invalid category",
                    "value": {
                      "type": "ConstraintViolationException",
                      "code": 3,
                      "message": "Allowed category are: UTILITY, MARKETING",
                      "errorDetails": [
                        {
                          "field": "createTemplate.template.validCategory",
                          "message": "Allowed category are: UTILITY, MARKETING"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials."
          },
          "403": {
            "description": "Forbidden — the account is not authorized to perform this operation."
          }
        }
      }
    },
    "/api/template/{templateId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TemplateIdPath"
        }
      ],
      "get": {
        "tags": [
          "Template"
        ],
        "summary": "Get a template",
        "description": "Retrieves a specific template by its ID and language.",
        "operationId": "getTemplate",
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "required": true,
            "description": "Language code of the template (e.g. `it`, `en`).",
            "schema": {
              "type": "string",
              "example": "it"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Template"
                },
                "examples": {
                  "utilityTemplate": {
                    "summary": "Utility template",
                    "value": {
                      "body": {
                        "text": "Questa notifica conferma che il plugin è stato configurato correttamente."
                      },
                      "urlButtons": [],
                      "textHeader": {
                        "text": "Notifica di prova"
                      },
                      "language": "it",
                      "status": "APPROVED",
                      "category": "UTILITY",
                      "name": "example_utility_template",
                      "description": "Test notification",
                      "templateId": "2",
                      "default": false
                    }
                  },
                  "authenticationTemplate": {
                    "summary": "Authentication template",
                    "value": {
                      "body": {
                        "text": "*{{1}}* è il tuo codice di verifica. Per garantire la tua sicurezza, ti consigliamo di non condividere questo codice.",
                        "parameters": [
                          {
                            "text": "123456"
                          }
                        ]
                      },
                      "urlButtons": [
                        {
                          "index": 0,
                          "urlPath": "123456",
                          "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code_expiration_minutes=10&code=otp{{1}}",
                          "text": "Copia codice"
                        }
                      ],
                      "footer": {
                        "text": "Scade tra 10 minuti.",
                        "codeExpirationMinutes": 10
                      },
                      "language": "it",
                      "status": "APPROVED",
                      "category": "AUTHENTICATION",
                      "name": "authentication_template",
                      "description": "auth",
                      "templateId": "1",
                      "default": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials.",
            "content": {
              "application/json": {
                "examples": {
                  "invalidCredentials": {
                    "summary": "Invalid credentials",
                    "value": {
                      "type": "AuthenticationFailedException",
                      "code": 1,
                      "message": "Invalid credentials"
                    }
                  },
                  "missingApiKey": {
                    "summary": "Missing API key",
                    "value": {
                      "type": "MissingApiKeyException",
                      "code": 9,
                      "message": "Missing API key"
                    }
                  },
                  "invalidApiKey": {
                    "summary": "Invalid API key",
                    "value": {
                      "type": "InvalidApiKeyException",
                      "code": 9,
                      "message": "Invalid API Key"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the account does not have the required role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "forbidden": {
                    "summary": "Insufficient role",
                    "value": {
                      "type": "ForbiddenException",
                      "code": 6,
                      "message": "Current role [USER], missing role [ADMIN, TEMPLATE_ADMIN]"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found.",
            "content": {
              "application/json": {
                "example": {
                  "type": "UnavailableTemplateException",
                  "code": 7,
                  "message": "Invalid template"
                }
              }
            }
          }
        }
      }
    },
    "/api/template/{templateId}/language": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TemplateIdPath"
        }
      ],
      "post": {
        "tags": [
          "Template"
        ],
        "summary": "Add a language to a template",
        "description": "Adds a new language variant to an existing template.",
        "operationId": "addTemplateLanguage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddLanguageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Language added successfully."
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "languageExists": {
                    "summary": "Language already exists",
                    "value": {
                      "type": "InvalidLanguageException",
                      "code": 14,
                      "message": "The language 'en' already exists for template '61'"
                    }
                  },
                  "invalidLanguage": {
                    "summary": "Language not supported by Meta",
                    "value": {
                      "type": "ClientWebApplicationException",
                      "code": 12,
                      "message": "Invalid parameter"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials."
          },
          "403": {
            "description": "Forbidden — the account is not authorized to perform this operation."
          },
          "404": {
            "description": "Template not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "type": "UnavailableTemplateException",
                  "code": 7,
                  "message": "Template not found"
                }
              }
            }
          }
        }
      }
    },
    "/api/template/{templateId}/languages": {
      "parameters": [
        {
          "$ref": "#/components/parameters/TemplateIdPath"
        }
      ],
      "get": {
        "tags": [
          "Template"
        ],
        "summary": "Get all template languages",
        "description": "Returns all available language variants for a specific template.",
        "operationId": "getTemplateLanguages",
        "responses": {
          "200": {
            "description": "List of template languages retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "de",
                    "en",
                    "fr",
                    "it"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing credentials."
          },
          "403": {
            "description": "Forbidden — the account does not have the required role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "forbidden": {
                    "summary": "Insufficient role",
                    "value": {
                      "type": "ForbiddenException",
                      "code": 6,
                      "message": "Current role [USER], missing role [ADMIN, TEMPLATE_ADMIN]"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Template not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "type": "UnavailableTemplateException",
                  "code": 7,
                  "message": "Invalid template"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/status": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Check service status",
        "description": "Returns the current operational status of the WhatsApp Gateway service. No authentication required. The response body is empty — an HTTP 200 indicates the service is up.",
        "operationId": "getServiceStatus",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is operational.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": ""
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "TemplateIdPath": {
        "name": "templateId",
        "in": "path",
        "required": true,
        "description": "Unique identifier of the template.",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 1
        }
      }
    },
    "schemas": {
      "SendResponse": {
        "type": "object",
        "description": "Response returned when a message is sent successfully.",
        "properties": {
          "messageId": {
            "type": "string",
            "description": "Unique identifier of the sent message.",
            "example": "3425151601"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response returned when a request fails.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Exception type identifier."
          },
          "code": {
            "type": "integer",
            "format": "int32",
            "description": "Numeric error code. See [Error codes](https://docs.namirial.app/products/whatsapp/) for the full list."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description."
          },
          "errorDetails": {
            "type": [
              "array",
              "null"
            ],
            "description": "Additional validation error details, present on constraint violations.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The field that failed validation."
                },
                "message": {
                  "type": "string",
                  "description": "Validation error message."
                }
              }
            }
          }
        }
      },
      "SendRequest": {
        "type": "object",
        "required": [
          "to",
          "language",
          "templateId"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "Recipient phone number in E.164 format (e.g. `+390000000000`).",
            "example": "+390000000000"
          },
          "language": {
            "type": "string",
            "description": "Language code of the template to use (e.g. `it`, `en`). See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages). Falls back to the template's default language if not found.",
            "example": "it"
          },
          "templateId": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Identifier of the WhatsApp template to use.",
            "example": 3
          },
          "businessRelationId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional business relation identifier for internal tracking."
          },
          "lra": {
            "type": [
              "string",
              "null"
            ],
            "description": "Local Registration Authority (LRA) identifier."
          },
          "reference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReferenceService"
              }
            ],
            "description": "Optional reference object for tracking. See [Reference Attribute](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference) for details."
          },
          "body": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BodyComponent"
              }
            ],
            "description": "Template body component with dynamic parameters. See [Body component](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/api-references/send-message-apis#body-component) for details on how to use placeholders."
          },
          "urlButtons": {
            "type": [
              "array",
              "null"
            ],
            "description": "List of URL button components with dynamic URL paths.",
            "items": {
              "$ref": "#/components/schemas/UrlButtonTypeComponent"
            }
          }
        }
      },
      "SendOtpRequest": {
        "type": "object",
        "required": [
          "to",
          "language",
          "otp",
          "templateId"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "Recipient phone number in E.164 format (e.g. `+390000000000`).",
            "example": "+390000000000"
          },
          "language": {
            "type": "string",
            "description": "Language code of the authentication template to use (e.g. `it`, `en`). See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages). Falls back to the template's default language if not found.",
            "example": "it"
          },
          "templateId": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "Identifier of the authentication template to use.",
            "example": 1
          },
          "otp": {
            "type": "string",
            "minLength": 1,
            "description": "The one-time password to include in the message (max 15 characters, as per Meta authentication template restrictions).",
            "example": "123456"
          },
          "businessRelationId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional One Platform Business Relation ID. If specified, consumption is attributed to this BRI."
          },
          "lra": {
            "type": [
              "string",
              "null"
            ],
            "description": "Local Registration Authority (LRA) identifier."
          },
          "reference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReferenceService"
              }
            ],
            "description": "Optional reference object for tracking. See [Reference Attribute](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference) for details."
          }
        }
      },
      "Template": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template description."
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "description": "Language code of the template (e.g. `it`, `en`). See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for the full list of valid values.",
            "example": "it"
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "WhatsApp template category.",
            "enum": [
              "UTILITY",
              "MARKETING",
              "AUTHENTICATION"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template approval status (e.g. `APPROVED`, `PENDING`, `REJECTED`)."
          },
          "templateId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unique identifier of the template."
          },
          "default": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this is the default language variant for the template."
          },
          "body": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BodyComponent"
              }
            ],
            "description": "Template body component."
          },
          "textHeader": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TextHeaderComponent"
              }
            ],
            "description": "Template text header component."
          },
          "footer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FooterComponent"
              }
            ],
            "description": "Template footer component."
          },
          "urlButtons": {
            "type": [
              "array",
              "null"
            ],
            "description": "List of URL button components.",
            "items": {
              "$ref": "#/components/schemas/UrlButtonTypeComponent"
            }
          }
        }
      },
      "ReferenceService": {
        "type": "object",
        "description": "Optional reference object to track messages and associate them with specific services or actions. `service` is required if `action` or `key` are specified.",
        "properties": {
          "service": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifies the product or service sending the message. Required if `action` or `key` are specified.",
            "maxLength": 50
          },
          "action": {
            "type": [
              "string",
              "null"
            ],
            "description": "Describes the specific action for the selected service (e.g. `2FA`, `AUTH`).",
            "maxLength": 50
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Custom tracking key for internal processes.",
            "maxLength": 255
          }
        }
      },
      "BodyComponent": {
        "type": "object",
        "description": "Template body component containing dynamic text parameters.",
        "properties": {
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Static body text."
          },
          "parameters": {
            "type": [
              "array",
              "null"
            ],
            "description": "List of dynamic text parameters to substitute in the template body.",
            "items": {
              "$ref": "#/components/schemas/TextTypeParameter"
            }
          }
        }
      },
      "TextHeaderComponent": {
        "type": "object",
        "description": "Template text header component.",
        "properties": {
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Header text."
          }
        }
      },
      "FooterComponent": {
        "type": "object",
        "description": "Template footer component.",
        "properties": {
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Footer text."
          },
          "codeExpirationMinutes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "OTP code expiration time in minutes."
          }
        }
      },
      "UrlButtonTypeComponent": {
        "type": "object",
        "description": "URL button component with a dynamic URL path suffix.",
        "properties": {
          "index": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Zero-based index of the URL button in the template."
          },
          "urlPath": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dynamic path suffix appended to the button's base URL."
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full URL override for the button."
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Button label text."
          }
        }
      },
      "TextTypeParameter": {
        "type": "object",
        "description": "A single dynamic text parameter for template substitution.",
        "properties": {
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parameter value to substitute in the template."
          }
        }
      },
      "CreateTemplateRequest": {
        "type": "object",
        "required": [
          "language",
          "category",
          "name",
          "description",
          "body"
        ],
        "properties": {
          "language": {
            "type": "string",
            "description": "Default template language. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages).",
            "example": "en"
          },
          "category": {
            "type": "string",
            "description": "Template category. For `AUTHENTICATION` templates, contact Namirial support for the accepted parameters.",
            "enum": [
              "UTILITY",
              "MARKETING",
              "AUTHENTICATION"
            ]
          },
          "name": {
            "type": "string",
            "description": "Template name. Only alphabetic characters and underscores (max 100 characters).",
            "example": "signature_template"
          },
          "description": {
            "type": "string",
            "description": "Template description.",
            "example": "sign a doc using a link"
          },
          "body": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BodyComponent"
              }
            ],
            "description": "Template body component."
          },
          "urlButtons": {
            "type": [
              "array",
              "null"
            ],
            "description": "URL button components. Max 2 buttons.",
            "items": {
              "$ref": "#/components/schemas/UrlButtonTypeComponent"
            }
          },
          "textHeader": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TextHeaderComponent"
              }
            ],
            "description": "Template text header component."
          },
          "footer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FooterComponent"
              }
            ],
            "description": "Template footer component."
          }
        }
      },
      "AddLanguageRequest": {
        "type": "object",
        "required": [
          "language",
          "body"
        ],
        "properties": {
          "language": {
            "type": "string",
            "description": "The new language to add. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages).",
            "example": "it"
          },
          "body": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BodyComponent"
              }
            ],
            "description": "Template body component in the new language."
          },
          "urlButtons": {
            "type": [
              "array",
              "null"
            ],
            "description": "URL button components for the new language version. Max 2 buttons.",
            "items": {
              "$ref": "#/components/schemas/UrlButtonTypeComponent"
            }
          },
          "textHeader": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TextHeaderComponent"
              }
            ],
            "description": "Template text header component in the new language."
          },
          "footer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FooterComponent"
              }
            ],
            "description": "Template footer component in the new language."
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic Authentication using account credentials.\n\n**Format**: `Authorization: Basic base64(username:password)`\n\n**How to obtain credentials**:\n1. Contact Namirial support to create a WhatsApp Gateway account\n2. Receive username and password via secure channel\n3. Test credentials in TEST environment first\n\nSee [Authentication documentation](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/authentication) for details."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "HTTP API Key authentication using account credentials.\n\n**Format**: `X-Api-Key: YOUR_API_KEY`\n\n**How to obtain credentials**:\n1. Contact Namirial support to create a WhatsApp Gateway account\n2. Receive API key via secure channel\n3. Test credentials in TEST environment first\n\nSee [Authentication documentation](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/authentication) for details."
      }
    }
  }
}