Ir para o conteúdo

Criar e gerenciar modelos

O número de modelos que uma conta do WhatsApp Business pode ter é determinado pela empresa principal. Caso a conta principal não tenha sido verificada, cada uma das contas do WhatsApp Business pode ter 250 modelos. Entretanto, se a conta principal tiver sido verificada e pelo menos uma das contas tiver um número de telefone comercial com um nome de exibição aprovado, cada conta do WhatsApp Business poderá ter até 6.000 modelos.

Antes de começar

Você precisará do seguinte:

  • Um token de acesso de usuário do sistema vinculado à empresa.
  • A permissão whatsapp_business_management.
  • A identificação da conta do WhatsApp Business da empresa.
  • O nome de usuário do ativo de mídia cujos documentos e arquivos de imagem ou vídeo serão usados no modelo de mídia. Para obter o nome de usuário, carregue o ativo de mídia por meio da API de Carregamento Retomável.

Limitações

  • O campo de nome do modelo de mensagem tem um limite de 512 caracteres.
  • O campo de conteúdo do modelo de mensagem tem um limite de 1.024 caracteres.
  • Os modelos podem ser editados apenas quando estiverem no estado Aprovado, Rejeitado ou Pausado. É possível editar cada modelo de mensagem somente uma vez por dia, até 10 vezes por mês.
  • As contas do WhatsApp Business podem criar apenas 100 modelos de mensagem por hora.
  • Os valores de variável fornecidos tem um limite de 15 caracteres.
  • Os valores de variável fornecidos não podem conter links ou emojis.
  • O componente de texto do corpo do modelo não pode conter um link.

Localização

Ao criar um modelo de mensagem, você pode adicionar um idioma específico. Esses modelos serão contabilizados no seu limite. Forneça traduções consistentes.

Criar modelos

Envie uma solicitação POST ao ponto de extremidade abaixo para criar um modelo.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates
Método: POST

Corpo da publicação

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": "<ALLOW_CATEGORY_CHANGE>",
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Propriedades

Espaço reservado Descrição Exemplo de valor
NAME (String) Obrigatório. O nome do modelo. Máximo de 512 caracteres. order_confirmation
CATEGORY (Enumeração) Obrigatório. A categoria do modelo. Consulte Categorias abaixo. UTILITY
ALLOW_CATEGORY_CHANGE (Booleano) Opcional. Defina como true para permitir que designemos a categoria com base no conteúdo e nas diretrizes de modelos. Isso pode impedir que o modelo seja rejeitado por categorização incorreta. Consulte Categorias abaixo. Se omitida, o modelo não será atribuído automaticamente a uma categoria e poderá ser rejeitado por categorização incorreta. true
LANGUAGE (Enumeração) Obrigatório. O código de localidade e idioma do modelo. en_US
COMPONENTS (Matriz de objetos) Obrigatório. Componentes que fazem parte do modelo. Consulte Componentes abaixo. Consulte Componentes abaixo.

Categorias

Os modelos precisam ser categorizados. A categoria escolhida no momento da criação será validada durante a análise do modelo, que poderá ser rejeitado se houver incompatibilidade entre a categoria selecionada e a determinada com base no conteúdo.

Consulte o documento sobre categorização de modelos para ver como os categorizamos e saber como selecionar a opção adequada ao criá-los, de modo a evitar uma possível rejeição.

Estas são as categorias compatíveis:

  • AUTHENTICATION
  • MARKETING
  • UTILITY

É possível incluir a propriedade allow_category_change definida como true no corpo do POST de criação do modelo para permitir a categorização automática do seu modelo com base no conteúdo e nas nossas diretrizes de categorização de modelos. Isso pode impedir que o modelo seja rejeitado por categorização incorreta.

É possível usar modelos para conversas abertas, e as categorias afetam os preços.

Componentes

Conforme as necessidades da empresa, os modelos podem incluir texto, mídia e componentes interativos. Ao criar um modelo, defina os componentes atribuindo uma matriz de objetos à propriedade components no corpo da solicitação.

Por exemplo, esta matriz contém um componente de corpo com texto contendo duas variáveis e exemplos de valores, um componente de botão de número de telefone e um componente de botão de URL: 

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. 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"
      }
    ]
  }
]
Consulte a lista com todas as possibilidades de componentes e os respectivos requisitos, além de amostras e exemplos de consulta em Componentes do modelo.

Observe que os modelos categorizados como AUTHENTICATION têm requisitos únicos de componente. Consulte Modelos de autenticação.

Exemplo de solicitação

Veja um exemplo de solicitação para criar um modelo de promoção sazonal com os seguintes componentes:

  • Um cabeçalho com texto
  • Um corpo com texto
  • Um rodapé
  • Dois botões de resposta rápida

Veja mais exemplos aqui.

curl '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"
        }
      ]
    }
  ]
}'

Enviar mensagem com modelo

Consulte a página Como enviar mensagens de notificação (com template).

Boas práticas para modelos de marketing

Botão para desativação de marketing

Recomendamos incluir um botão de resposta rápida em mensagens categorizadas como MARKETING para que os usuários possam cancelar com facilidade o recebimento de mensagens de marketing. Assim, os clientes terão a opção de desativar essas mensagens sem precisar bloquear a sua empresa. Como resultado, será possível dimensionar o volume de mensagens com mais rapidez. Consulte este artigo para ver mais informações sobre os benefícios do botão para desativação em modelos de marketing.

Sua empresa deve realizar as ações necessárias com o objetivo de parar de enviar mensagens de marketing a clientes que desativaram o recebimento delas. Caso isso não seja feito, a taxa de bloqueio e a pontuação de qualidade serão impactadas negativamente.

Obter modelos

Envie uma solicitação GET ao ponto de extremidade abaixo para obter uma lista de modelos de propriedade de uma conta do WhatsApp Business.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates
Método: GET

Parâmetros da string de consulta

Utilize parâmetros ou filtros para obter o modelo que você quer que seja retornado.
Filtros (opcionais): name, status, category, content, language, name_or_content, quality_score

Exemplo de solicitação

curl 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates' \
-H 'Authorization: Bearer EAAJB...'

Editar modelos

Não existe edição de modelos. O modelo deverá ser excluído e deverá ser criado um novo modelo, com outro nome. Os nomes de modelos aprovados que foram excluídos não poderão ser usados novamente por 30 dias.

Excluir modelos

Use os pontos de extremidades abaixo para excluir um modelo por nome ou por nome e id.

Observações Se você excluir um modelo enviado em uma mensagem que ainda não foi entregue (por exemplo, porque o telefone do cliente está desligado), o status do modelo será definido como PENDING_DELETION, e tentaremos entregar a mensagem por 30 dias. Depois disso, você verá um erro de "Estrutura indisponível", e o cliente não receberá a mensagem.

Exclusão por nome

Ao excluir um modelo por nome, você removerá todos os modelos com essa nomenclatura. Isso significa que modelos com o mesmo nome, mas idiomas diferentes, também serão excluídos.

URI

URI: https://gateway-d-whatsapp.estaleiro.serpro.gov.br/waba/{wabaId}/v2/templates/{name_template}
Método: DELETE

Exemplo de solicitação

curl -X DELETE 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates/{order_confirmation}' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "success": true
}

Exclusão por nome e id

A exclusão do template poderá ser por nome e id. Ao excluir um modelo com estes parâmetros, você removerá o modelo com essa nomenclatura e no idioma representado por este id.

URI

URI: https://gateway-d-whatsapp.estaleiro.serpro.gov.br/waba/{wabaId}/v2/templates/{name}/{id}
Método: DELETE

Exemplo de solicitação

curl -X DELETE 'https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/templates/{name_template}/{id_template}' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "success": true
}