Componentes do modelo

Os modelos são feitos de quatro componentes principais, definidos no momento da criação: cabeçalho, corpo, rodapé e botões. Estes componentes são escolhidos com base nas necessidades dos seus negócios, sendo que o único componente obrigatório é o corpo.

Alguns componentes são compatíveis com variáveis, cujos valores você pode fornecer ao usar a API de envio de mensagem de notificação. Quando as variáveis forem usadas, será preciso incluir valores de exemplo para elas no momento da criação do modelo.

Cabeçalhos

Os cabeçalhos são componentes opcionais que aparecem na parte superior dos modelos de mensagem. Eles são compatíveis com texto, mídia (imagens, vídeos, documentos) e localizações. Os modelos podem ter apenas um componente de cabeçalho.

Cabeçalhos com texto

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "<TEXT>",

  # Required if <TEXT> string contains variables
  "example": {
    "header_text": [
      "<HEADER_TEXT>"
    ]
  }
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
HEADER_TEXT	Exemplo de cabeçalho com texto.	Summer Sale
TEXT	Texto a ser exibido no cabeçalho do modelo enviado. Compatível com 1 variável. Se a string contiver uma variável, você deverá incluir a propriedade example e um valor de exemplo. Pode ter, no máximo, 60 caracteres.	Our {{1}} is on!

Exemplo

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our {{1}} is on!",
  "example": {
    "header_text": [
      "Summer Sale"
    ]
  }
}

Cabeçalhos com mídia

O cabeçalho com mídia pode ser uma imagem, um vídeo ou um documento, como um PDF. Todas as mídias devem ser carregadas com a API de envio de mídia. A sintaxe para definir um cabeçalho com mídia é a mesma para todos os tipos de mídia.

{
  "type": "HEADER",
  "format": "<FORMAT>",
  "example": {
    "header_handle": [
      <HEADER_HANDLE>
    ]
  }
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
FORMAT	Indica o tipo de ativo de mídia. Defina como IMAGE, VIDEO ou DOCUMENT.	IMAGE
HEADER_HANDLE	Identificador do ativo de mídia carregado. Use a API de envio de mídia para gerar um identificador de ativo.	4::aW...

Exemplo

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": [
      4::aW...
    ]
  }
}

Cabeçalhos com localização

Os cabeçalhos com localização aparecem como mapas genéricos na parte superior do modelo e são úteis para rastreamento de pedidos, atualizações sobre entregas, embarque e desembarque no transporte por caronas, localização de lojas físicas etc. Quando o usuário toca neles, o app de mapas padrão do usuário é aberto e carrega a localização especificada. As localizações são especificadas quando você envia o modelo usando a API de envio de notificação.

Os cabeçalhos com localização só podem ser usados em modelos categorizados como UTILITY ou MARKETING. A localização em tempo real não é compatível.

{
  "type": "HEADER",
  "format": "LOCATION"
}

Propriedades Os valores de propriedade não podem ser personalizados.

Exemplo

{
  "type": "HEADER",
  "format": "LOCATION"
}

2. Corpo

Os componentes do tipo corpo são somente de texto e são obrigatórios em todos os modelos. Os modelos podem ter apenas um componente de corpo.

{
  "type": "BODY",
  "text": "<TEXT>",

  # Required if <TEXT> string contains variables
  "example": {
    "body_text": [
      [
        <BODY_TEXT>
      ]
    ]
  }
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
BODY_TEXT	Matriz de exemplos de strings. O número de strings deve corresponder ao número de variáveis incluídas na string.	"the end of August","25OFF","25%"
TEXT	String de texto. Compatível com mais de uma variável. Se a string contiver variáveis, você deverá incluir a propriedade example e valores de exemplo. Pode ter, no máximo, 1.024 caracteres.	Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.

Exemplo

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
    "example": {
      "body_text": [
        [
          "the end of August","25OFF","25%"
        ]
      ]
    }
}

3. Rodapé

Os rodapés são componentes opcionais somente de texto que são exibidos imediatamente após o componente corpo. Os modelos podem ter apenas um componente de rodapé.

{
  "type": "FOOTER",
  "text": "<TEXT>"
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
TEXT	Texto a ser exibido no rodapé do modelo enviado. Pode ter, no máximo, 60 caracteres.	Use the buttons below to manage your marketing subscriptions

Exemplo

{
  "type": "FOOTER",
  "text": "Use the buttons below to manage your marketing subscriptions"
}

4. Botões

Os botões são componentes interativos opcionais que executam ações específicas quando tocados. Os modelos podem combinar até 10 componentes de botão no total, embora haja limitações para botões do mesmo tipo, bem como para combinações. Essas limitações estão descritas abaixo.

Se o modelo tiver mais de três botões, dois deles aparecerão na mensagem entregue e os restantes serão substituídos por um botão Ver todas as opções. Os botões restantes são exibidos quando o usuário toca em Ver todas as opções.

Botões de número de telefone

Botões de número de telefone ligam para os telefones comerciais especificados quando o usuário do app clica neles. Os modelos podem ter apenas um componente de botão de número de telefone.

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "<TEXT>",
      "phone_number": "<PHONE_NUMBER>"
    }
  ]
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
PHONE_NUMBER	String alfanumérica. O número de telefone comercial a ser chamado (número de telefone de exibição) quando o usuário toca no botão. Pode ter, no máximo, 20 caracteres.	15550051310
TEXT	Texto da etiqueta do botão. Pode ter, no máximo, 25 caracteres.	Call

Exemplo

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "Call",
      "phone_number": "15550051310"
    }
  ]
}

Botões URL

Botões URL carregam a URL especificada no navegador da web padrão do dispositivo quando o usuário do app clica neles. Os modelos podem ter até dois botões URL.

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "<TEXT>",
      "url": "<URL>",

      # Required if <URL> contains a variable
      "example": [
        "<EXAMPLE>"
      ]
    }
  ]
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
EXAMPLE	URL do site. Compatível com 1 variável. Se usar uma variável, adicione um exemplo de propriedade de variável ao final da string da URL. A URL é carregada no navegador da web para celular padrão do dispositivo quando o cliente toca no botão. Pode ter, no máximo, 2.000 caracteres.	https://www.luckyshrub.com/shop?promo=summer2023
TEXT	Texto da etiqueta do botão. Compatível com 1 variável. Se usar uma variável, você deverá incluir a propriedade "example" e um valor de exemplo. Pode ter, no máximo, 25 caracteres.	Shop Now
URL	URL do site que é carregada no navegador da web para celular padrão do dispositivo quando o usuário do app toca no botão. Compatível com 1 variável, adicionada ao final da string da URL. Pode ter, no máximo, 2.000 caracteres.	https://www.luckyshrub.com/shop?promo={{1}}

Exemplo

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Shop Now",
      "url": "https://www.luckyshrub.com/shop?promo={{1}}",
      "example": [
        "summer2023"
      ]
    }
  ]
}

Botões de resposta rápida

Os botões de resposta rápida são botões personalizados somente de texto que, quando tocados pelo usuário, enviam imediatamente a você uma mensagem com a string especificada. Um caso de uso comum é um botão para o usuário cancelar com facilidade a assinatura de mensagens de marketing.

Os modelos podem ter até 10 botões de resposta rápida. Caso você use botões de resposta rápida com outros tipos de botão, será preciso organizá-los em dois grupos: botões de resposta rápida e outros botões. Se eles forem agrupados incorretamente, a API retornará um erro informando uma combinação inválida.

Exemplos de agrupamentos válidos:

• Resposta rápida, resposta rápida
• Resposta rápida, resposta rápida, URL, telefone
• URL, telefone, resposta rápida, resposta rápida

Exemplos de agrupamentos inválidos:

• Resposta rápida, URL, resposta rápida
• URL, resposta rápida, URL Se você enviar um modelo que tenha mais de um botão de resposta rápida, utilize a propriedade "index" para definir a ordem em que os botões aparecerão no modelo de mensagem.

{
  "type":"BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "<TEXT>"
    }
}

Propriedades

Espaço reservado	Descrição	Exemplo de valor
TEXT	Texto da etiqueta do botão. Pode ter, no máximo, 25 caracteres.	Unsubscribe

Exemplo Este exemplo inclui dois botões de resposta rápida.

{
  "type":"BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Unsubscribe from Promos"
    },
    {
      "type":"QUICK_REPLY",
      "text": "Unsubscribe from All"
    }
  ]
}

Botões de senha descartável

Os botões de senha descartável são um tipo especial de botão URL usado com modelos de autenticação. Consulte Modelos de autenticação.

Depois de ser criado, o type do botão de um modelo de autenticação será definido como URL. Para verificar essa configuração, solicite o campo type no modelo de autenticação recém-criado.

Exemplos de solicitação

Promoção sazonal

Um exemplo de solicitação para criar um modelo de marketing com os seguintes componentes:

• Um cabeçalho com texto com uma variável e um valor de exemplo
• Um corpo com texto com variáveis e valores de exemplo
• Um rodapé com texto
• Dois botões de resposta rápida

  curl -L 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates' \
  -H 'Authorization: Bearer EAAJB...' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "seasonal_promotion",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
      {
        "type": "HEADER",
        "format": "TEXT",
        "text": "Our {{1}} is on!",
        "example": {
          "header_text": [
            "Summer Sale"
          ]
        }
      },
      {
        "type": "BODY",
        "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
        "example": {
          "body_text": [
            [
              "the end of August","25OFF","25%"
            ]
          ]
        }
      },
      {
        "type": "FOOTER",
        "text": "Use the buttons below to manage your marketing subscriptions"
      },
      {
        "type":"BUTTONS",
        "buttons": [
          {
            "type": "QUICK_REPLY",
            "text": "Unsubscribe from Promos"
          },
          {
            "type":"QUICK_REPLY",
            "text": "Unsubscribe from All"
          }
        ]
      }
    ]
  }'
  

Oferta por tempo limitado

Um exemplo de solicitação para criar um modelo de marketing com os seguintes componentes:

• Um cabeçalho com imagem com um valor de exemplo
• Um corpo com texto com variáveis e valores de exemplo
• Um rodapé com texto
• Um botão de número de telefone
• Um botão URL

  curl -L 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates' \
  -H 'Authorization: Bearer EAAJB...' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "limited_time_offer_tuscan_getaway_2023",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": [
            "4::aW..."
          ]
        }
      },
      {
        "type": "BODY",
        "text": "Hi {{1}}! For a limited time only you can get our {{2}} for as low as {{3}}. Tap the Offer Details button for more information.",
        "example": {
          "body_text": [
            [
              "Pablo","Tuscan Getaway package","800"
            ]
          ]
        }
      },
      {
        "type": "FOOTER",
        "text": "Offer valid until May 31, 2023"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "PHONE_NUMBER",
            "text": "Call",
            "phone_number": "15550051310"
          },
          {
            "type": "URL",
            "text": "Shop Now",
            "url": "https://www.luckyshrub.com/shop?promo={{1}}",
            "example": [
              "summer2023"
             ]
          }
        ]
      }
    ]
  }'
  

Confirmação de pedido

Um exemplo de solicitação para criar um modelo de utilidade com os seguintes componentes:

• Um cabeçalho com documento com um valor de exemplo
• Um corpo com texto com variáveis e valores de exemplo
• Um botão de número de telefone
• Um botão URL

  curl -L 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates' \
  -H 'Authorization: Bearer EAAJB...' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "order_confirmation",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "HEADER",
        "format": "DOCUMENT",
        "example": {
          "header_handle": [
            "4::YX..."
          ]
        }
      },
      {
        "type": "BODY",
        "text": "Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
        "example": {
          "body_text": [
            [
              "Pablo","860198-230332"
            ]
          ]
        }
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "PHONE_NUMBER",
            "text": "Call",
            "phone_number": "15550051310"
          },
          {
            "type": "URL",
            "text": "Contact Support",
            "url": "https://www.luckyshrub.com/support"
          }
        ]
      }
    ]
  }'
  

Atualização sobre entrega do pedido

Um exemplo de solicitação para criar um modelo de utilidade com os seguintes componentes:

• Um cabeçalho com localização
• Um corpo com texto com variáveis e valores de exemplo
• Um rodapé
• Um botão de resposta rápida

  curl 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer EAAJB...' \
  -d '
  {
    "name": "order_delivery_update",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "HEADER",
        "format": "LOCATION"
      },
      {
        "type": "BODY",
        "text": "Good news {{1}}! Your order #{{2}} is on its way to the location above. Thank you for your order!",
        "example": {
          "body_text": [
            [
              "Mark",
              "566701"
            ]
          ]
        }
      },
      {
        "type": "FOOTER",
        "text": "To stop receiving delivery updates, tap the button below."
      },
      {
        "type":"BUTTONS",
        "buttons": [
          {
            "type": "QUICK_REPLY",
            "text": "Stop Delivery Updates"
          }
        ]
      }
    ]
  }'