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

# Criar Template

> Crie um novo template HSM e envie-o ao WhatsApp para aprovação

Crie templates HSM personalizados com parâmetros posicionais, botões interativos e mídia. Opcionalmente, envie o template diretamente ao WhatsApp para aprovação.

```
POST /v1/bots/{botId}/templates
```

<Tip>
  **Templates** devem ser aprovados pela equipe do WhatsApp antes de poderem ser usados. Siga as diretrizes da Meta para evitar rejeições.
</Tip>

***

## Parâmetros de Path

| Propriedade | Tipo   | Descrição                             |
| ----------- | ------ | ------------------------------------- |
| **botId**   | string | ID único do bot. Exemplo: `123456789` |

***

## Parâmetros de Query

| Propriedade      | Tipo    | Descrição                                                         |
| ---------------- | ------- | ----------------------------------------------------------------- |
| **sendToAprove** | boolean | Define se o template deve ser enviado ao WhatsApp para aprovação. |

***

## Corpo da Requisição

| Propriedade           | Tipo    | Descrição                                                                                                                                           |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **category**          | string  | Categoria do template HSM. Valores: `UTILITY`, `MARKETING`, `AUTHENTICATION`                                                                        |
| **language**          | string  | Idioma do template.                                                                                                                                 |
| **isVisible**         | boolean | Define se o template deve ser exibido para os operadores.                                                                                           |
| **params**            | array   | Estrutura de parâmetros. Para a categoria de autenticação, a Meta restringiu a um parâmetro.                                                        |
| **paramsNumber**      | number  | Número de parâmetros. Para a categoria de autenticação, a Meta restringiu a um parâmetro.                                                           |
| **elementName**       | string  | Identificador único do template. Pode conter apenas letras minúsculas, underscores (`_`) e números.                                                 |
| **displayName**       | string  | Nome de exibição do template.                                                                                                                       |
| **template**          | string  | Corpo do template. Para a categoria de autenticação, a Meta restringiu o conteúdo.                                                                  |
| **type**              | string  | Tipo de HSM. Valores: `HSM`, `IMAGE`, `VIDEO`, `DOCUMENT`                                                                                           |
| **mediaUrl**          | string  | URL da mídia. Obrigatório quando o tipo de HSM é `IMAGE`, `VIDEO`, `DOCUMENT`. Não aplicável para a categoria de autenticação.                      |
| **interactiveAction** | string  | Ação interativa do HSM. Valores: `NONE`, `CALL_TO_ACTION`, `QUICK_REPLY`, `OTP`                                                                     |
| **buttons**           | array   | Estrutura de botões. Obrigatório quando a ação interativa do HSM é `CALL_TO_ACTION`, `QUICK_REPLY` ou `OTP`.                                        |
| **header**            | string  | Cabeçalho do template. Aplicável apenas para templates do tipo texto. Não aplicável para a categoria de autenticação e tem limite de 60 caracteres. |
| **exampleHeader**     | string  | Exemplo de cabeçalho. Obrigatório apenas se o template tiver um cabeçalho.                                                                          |
| **headerParams**      | array   | Estrutura de parâmetros. O cabeçalho suporta no máximo um parâmetro.                                                                                |
| **example**           | string  | Exemplo do template. Se o template tiver um parâmetro, ele deve ser substituído por um exemplo.                                                     |
| **extraSettings**     | object  | Configurações opcionais para o template.                                                                                                            |

***

## Exemplos de Requisição

<AccordionGroup>
  <Accordion title="Texto">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "text_template_utility",
        "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, contact support.",
        "example": "Thank you for your order, Maria! Your confirmation number is 71936. If you have any questions, contact support.",
        "elementName": "text_template_utility",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"},
          {"param": "2", "label": "order", "example": "71936"}
        ],
        "paramsNumber": 2,
        "type": "HSM",
        "language": "en",
        "category": "UTILITY",
        "interactiveAction": "NONE"
      }'
    ```
  </Accordion>

  <Accordion title="Texto com botões de resposta rápida">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "template_quick_reply",
        "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. Use the buttons to contact us.",
        "example": "Thank you for your order, Maria! Your confirmation number is 57893. Use the buttons to contact us.",
        "elementName": "template_quick_reply",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"},
          {"param": "2", "label": "order", "example": "57893"}
        ],
        "paramsNumber": 2,
        "type": "HSM",
        "language": "en",
        "category": "UTILITY",
        "interactiveAction": "QUICK_REPLY",
        "buttons": [
          {"text": "Contact Support", "type": "QUICK_REPLY"},
          {"text": "Contact Sales", "type": "QUICK_REPLY"}
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Texto com botões CTA">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "template_call_action",
        "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. Use the buttons to contact us.",
        "example": "Thank you for your order, Maria! Your confirmation number is 67996. Use the buttons to contact us.",
        "elementName": "template_call_action",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"},
          {"param": "2", "label": "order", "example": "67996"}
        ],
        "paramsNumber": 2,
        "type": "HSM",
        "language": "en",
        "category": "UTILITY",
        "interactiveAction": "CALL_TO_ACTION",
        "buttons": [
          {"text": "Contact Support", "type": "URL", "url": "https://apps.jelou.ai", "example": "https://apps.jelou.ai"},
          {"text": "Call", "type": "PHONE_NUMBER", "phone_number": "+PHONE_NUMBER"}
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Imagem">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "image_template",
        "template": "Hello {{1}}. We invite you to check out our promotions.",
        "example": "Hello Maria. We invite you to check out our promotions.",
        "elementName": "image_template",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"}
        ],
        "paramsNumber": 1,
        "type": "IMAGE",
        "language": "en",
        "category": "MARKETING",
        "mediaUrl": "https://cdn.example.com/image.jpeg",
        "interactiveAction": "NONE"
      }'
    ```
  </Accordion>

  <Accordion title="Documento">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "document_template",
        "template": "Hello {{1}}. Please find your requested document attached.",
        "example": "Hello Maria. Please find your requested document attached.",
        "elementName": "document_template",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"}
        ],
        "paramsNumber": 1,
        "type": "DOCUMENT",
        "language": "en",
        "category": "MARKETING",
        "mediaUrl": "https://cdn.example.com/document.pdf",
        "interactiveAction": "NONE"
      }'
    ```
  </Accordion>

  <Accordion title="Vídeo">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
      --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
      --header 'Content-Type: application/json' \
      --data '{
        "displayName": "video_template",
        "template": "Hello {{1}}. Watch our new video.",
        "example": "Hello Maria. Watch our new video.",
        "elementName": "video_template",
        "params": [
          {"param": "1", "label": "customer", "example": "Maria"}
        ],
        "paramsNumber": 1,
        "type": "VIDEO",
        "language": "en",
        "category": "MARKETING",
        "mediaUrl": "https://cdn.example.com/video.mp4",
        "interactiveAction": "NONE"
      }'
    ```
  </Accordion>
</AccordionGroup>

***

## Respostas

<AccordionGroup>
  <Accordion title="200 - Resposta bem-sucedida">
    ```json theme={null}
    {
      "message": ["Template has been created."],
      "status": "success",
      "data": {
        "template": "Hello! We are *Jelou*. \nWelcome _{{1}}_. Soon {{2}} from the team will reach out to you.",
        "displayName": "Welcome",
        "elementName": "test_hsm_api",
        "params": [
          {"label": "Customer name", "param": "1"},
          {"label": "Agent name", "param": "2"}
        ],
        "paramsNumber": 2,
        "isVisible": false,
        "language": "EN",
        "createdAt": "2021-01-28T15:08:38.492Z",
        "updatedAt": "2021-01-28T15:08:38.492Z",
        "botId": "BOT_ID",
        "companyId": 100,
        "status": "APPROVED"
      }
    }
    ```
  </Accordion>

  <Accordion title="400 - Requisição Inválida">
    ```json theme={null}
    {
      "message": ["Template name already exists"],
      "status": "failed"
    }
    ```
  </Accordion>

  <Accordion title="401 - Não Autorizado">
    ```json theme={null}
    {
      "message": "Authentication failed"
    }
    ```
  </Accordion>

  <Accordion title="404 - Não Encontrado">
    ```json theme={null}
    {
      "message": ["The Bot could not be found at the moment."],
      "statusMessage": "failed",
      "error": {
        "code": "E1019",
        "key": "BOT_NOT_FOUND"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  O campo `status` na resposta indica se o seu template foi aprovado pelo WhatsApp.
</Note>

***

## Idioma

O idioma suportado pelo WhatsApp está detalhado na página oficial. Por favor, revise cuidadosamente no [seguinte link](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages-).

***

## Restrições de Conteúdo (Categoria de Autenticação)

A Meta restringiu o conteúdo para a categoria de autenticação. O conteúdo será de acordo com o idioma do template. A Meta está restrita a um único parâmetro.

### Idioma

| Idioma             | Código | Conteúdo                              |
| ------------------ | ------ | ------------------------------------- |
| **Inglês**         | en     | `{{1}}` is your verification code.    |
| **Português (BR)** | pt\_BR | Seu código de verificação é `{{1}}`.  |
| **Espanhol**       | es     | Tu código de verificación es `{{1}}`. |

***

## Estrutura de Parâmetros

Use a seguinte estrutura no campo `params` ao criar um template:

```json theme={null}
[
  {"label": "Customer name", "param": "1"},
  {"label": "Order number", "param": "2"}
]
```

***

## Estrutura de Botões

Use a seguinte estrutura no campo `buttons` quando as ações interativas forem `CALL_TO_ACTION`, `QUICK_REPLY` ou `OTP`.

### QUICK\_REPLY

Usado para obter respostas rápidas. É um array de objetos e pode ter no máximo 3 botões.

| Propriedade | Descrição                                           |
| ----------- | --------------------------------------------------- |
| **text**    | Texto do botão; este valor não pode ser atualizado. |
| **type**    | Tipo do botão. Valor: `QUICK_REPLY`                 |

```json theme={null}
[
  {"text": "More information", "type": "QUICK_REPLY"},
  {"text": "Talk to an operator", "type": "QUICK_REPLY"},
  {"text": "Sales", "type": "QUICK_REPLY"}
]
```

### CALL\_TO\_ACTION

Usado para oferecer uma chamada para ação. Pode ter no máximo 2 botões e no máximo 1 botão de cada tipo.

| Propriedade       | Descrição                                                   |
| ----------------- | ----------------------------------------------------------- |
| **text**          | Texto do botão; este valor não pode ser atualizado.         |
| **type**          | Tipo do botão. Valores: `PHONE_NUMBER`, `URL`               |
| **phone\_number** | Número de telefone do botão.                                |
| **url**           | URL do botão.                                               |
| **example**       | Exemplo de URL. Obrigatório quando o tipo de botão é `URL`. |

```json theme={null}
[
  {"text": "Sales", "phone_number": "+PHONE_NUMBER", "type": "PHONE_NUMBER"},
  {"type": "URL", "text": "View site", "url": "https://apps.jelou.ai/{{1}}", "example": "https://apps.jelou.ai/offers"}
]
```

### OTP

Usado para obter uma "Senha de Uso Único". Pode ter no máximo 1 botão.

| Propriedade | Descrição                                           |
| ----------- | --------------------------------------------------- |
| **text**    | Texto do botão; este valor não pode ser atualizado. |
| **type**    | Tipo do botão. Valor: `OTP`                         |

```json theme={null}
[
  {"text": "COPY CODE", "type": "OTP"}
]
```

***

## Estrutura de extraSettings

| Propriedade                   | Tipo    | Descrição                                                                                         |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| **addSecurityRecommendation** | boolean | Adiciona uma mensagem de segurança adicional em templates de autenticação.                        |
| **codeExpirationMinutes**     | number  | Adiciona uma mensagem de rodapé com o tempo de expiração do código. Valores entre 1 e 90 minutos. |
| **allowChangeCategory**       | boolean | Permite que a Meta atualize a categoria do template se necessário.                                |


## OpenAPI

````yaml POST /v1/bots/{botId}/templates
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
paths:
  /v1/bots/{botId}/templates:
    post:
      tags:
        - Campaigns
      summary: Crear Plantilla
      description: >-
        Crea una nueva plantilla HSM y opcionalmente envíala a WhatsApp para
        aprobación.
      operationId: createTemplate
      parameters:
        - name: botId
          in: path
          required: true
          schema:
            type: string
        - name: sendToAprove
          in: query
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
      responses:
        '200':
          description: Plantilla creada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CreateTemplateRequest:
      type: object
      required:
        - elementName
        - template
        - category
        - language
      properties:
        category:
          type: string
          enum:
            - UTILITY
            - MARKETING
            - AUTHENTICATION
        language:
          type: string
        isVisible:
          type: boolean
        params:
          type: array
          items:
            $ref: '#/components/schemas/TemplateParam'
        paramsNumber:
          type: integer
        elementName:
          type: string
          pattern: ^[a-z0-9_]+$
        displayName:
          type: string
        template:
          type: string
        type:
          type: string
          enum:
            - HSM
            - IMAGE
            - VIDEO
            - DOCUMENT
        mediaUrl:
          type: string
          format: uri
        interactiveAction:
          type: string
          enum:
            - NONE
            - CALL_TO_ACTION
            - QUICK_REPLY
            - OTP
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/TemplateButton'
        header:
          type: string
          maxLength: 60
        exampleHeader:
          type: string
        headerParams:
          type: array
          items:
            type: object
        example:
          type: string
        extraSettings:
          $ref: '#/components/schemas/TemplateExtraSettings'
    TemplateResponse:
      type: object
      properties:
        message:
          type: array
          items:
            type: string
        status:
          type: string
        data:
          type: object
    TemplateParam:
      type: object
      properties:
        param:
          type: string
        label:
          type: string
        example:
          type: string
    TemplateButton:
      type: object
      properties:
        text:
          type: string
        type:
          type: string
          enum:
            - QUICK_REPLY
            - URL
            - PHONE_NUMBER
            - OTP
        url:
          type: string
        phone_number:
          type: string
        example:
          type: string
    TemplateExtraSettings:
      type: object
      properties:
        addSecurityRecommendation:
          type: boolean
        codeExpirationMinutes:
          type: integer
          minimum: 1
          maximum: 90
        allowChangeCategory:
          type: boolean
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
  responses:
    BadRequest:
      description: Bad request - Invalid format or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret

````