WhatsApp Business Platform

Mensagens de modelo

As mensagens de modelo do WhatsApp são formatos de mensagem específicos que as empresas usam para enviar notificações ou mensagens de atendimento ao cliente às pessoas que optaram por receber notificações. As mensagens podem incluir lembretes de horas marcadas, informações de envio, resolução de problemas e atualizações de pagamento.

Antes de enviar um modelo de mensagem, é preciso criar um. Para ver mais informações, consulte Criar modelos de mensagem para a conta do WhatsApp Business. Se a sua conta ainda não foi verificada, use um modelo pré-aprovado.

Atualmente, é possível enviar os seguintes tipos de modelo:

• Modelos de mensagem de texto
• Modelos de mensagem de mídia
• Modelos de mensagem interativa
• Modelos de mensagem com localização
• Modelos de autenticação com botões de senha descartável
• Modelos de mensagem multiproduto

Todas as chamadas de API mencionadas neste guia precisam ser autenticadas com um token de acesso. Os desenvolvedores podem autenticar as chamadas de API com o token de acesso gerado em Painel de Apps > WhatsApp > Configuração da API. Os parceiros de soluções devem fazer a autenticação usando um token de acesso com a permissão whatsapp_business_messaging.

Regularidade

Os modelos de marketing recém-criados ou retomados estão sujeitos ao mecanismo de regularidade. Consulte Modelos: Regularidade do modelo.

Modelos de mensagem de texto

Para enviar um modelo de mensagem de texto, faça uma chamada POST a /PHONE_NUMBER_ID/messages e anexe um objeto message com type=template. Depois, adicione um objeto template.

Substitua as propriedades do espaço reservado abaixo usando a tabela indicada.

Exemplo de solicitação

curl -X  POST \
 'https://graph.facebook.com/v23.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "text-string"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

Propriedades

    "type": "body",
    "parameters": [
      {
        "type": "text",
        "parameter_name": "customer_name",
        "text": "John"
      },
      {
        "type": "text",
        "parameter_name": "order_id",
        "text": "9128312831"
      }        
    ]
          

    "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "9128312831"
        }        
      ]
    ]
          

Exemplo de resposta

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Modelos de mensagem de mídia

Para enviar um modelo de mensagem de mídia, faça uma chamada POST a /PHONE_NUMBER_ID/messages e anexe um objeto message com type=template. Depois, adicione um objeto template. É compatível com cache HTTP de mídia.

Use o ponto de extremidade POST em Número de telefone do WhatsApp Business > Mensagens para enviar um modelo de mensagem de mídia. Defina a propriedade type como template e use a propriedade template para configurar os objetos de modelo e mídia.

Ao definir o objeto de mídia, é possível carregar o ativo de mídia nos nossos servidores e usar a propriedade id ou hospedar o ativo no seu servidor e usar a propriedade link. Para usar link, o ativo precisa estar em um servidor público acessível. Caso contrário, a mensagem não será enviada.

Para reduzir a probabilidade de erros e evitar solicitações desnecessárias para seu servidor público, recomendamos que você carregue os ativos de mídia e use as identificações deles ao enviar mensagens.

Os ativos de mídia também podem ser armazenados em cache. Consulte Cache HTTP de mídia.

Exemplo de solicitação:

curl -X  POST \
 'https://graph.facebook.com/v23.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT-STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Modelos de mensagem interativa

Os modelos de mensagem interativa expandem o conteúdo que pode ser enviado ao irem além dos tipos de modelo-padrão de mensagem e de modelo de mensagem de mídia para incluir botões interativos com o objeto components. Estes são os dois tipos de botões predefinidos:

• Chamada para ação: permite que o cliente ligue para um telefone e visite um site.
• Resposta rápida: permite que o cliente responda com um SMS simples.

Esses botões podem ser anexados a mensagens de texto ou de mídia. Depois de criados e aprovados, os modelos de mensagem interativa podem ser usados em mensagens de notificação e de atendimento ao cliente.

Para enviar um modelo de mensagem interativa, faça uma chamada POST a /PHONE_NUMBER_ID/messages e anexe um objeto message com type=template. Depois, adicione um objeto template com o button escolhido.

Exemplo de solicitação:

curl -X  POST \
 'https://graph.facebook.com/v23.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Modelos de mensagem com localização

Sua solicitação precisa incluir um objeto de cabeçalho com localização para enviar modelos desse tipo.

Sintaxe

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

Propriedades

Exemplo de solicitação

Veja este exemplo de solicitação para enviar um modelo existente com os seguintes componentes:

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

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

Modelos de autenticação

A tentativa de enviar modelos de autenticação antigos (modelos sem botões de senha descartável) retornará um código de erro 100 se os valores das variáveis excederem 15 caracteres ou tiverem links/emojis, ou se o componente do corpo do modelo incluir um link. Em vez disso, crie e use um modelo de autenticação que tenha um botão de senha descartável.

Consulte Modelos de autenticação e Sending Authentication Templates.

Sequência de entrega de mensagens

Se você enviar várias mensagens, talvez elas não sejam entregues na mesma ordem das solicitações da API. Caso haja uma ordem a ser seguida, verifique se cada mensagem foi entregue no status delivered do webhook de mensagens antes de enviar a próxima.

Preferências do usuário para mensagens de marketing

O WhatsApp oferece a configuração Ofertas e anúncios, que permite aos usuários indicar o nível de interesse em mensagens de marketing enviadas pela sua empresa, além de interromper ou retomar o recebimento dessas mensagens.

Feedback de interesse

Os usuários do WhatsApp podem usar a configuração Ofertas e anúncios para indicar o nível de interesse em receber mensagens de marketing da sua empresa.

A escolha da opção Não tenho interesse poderá afetar os limites de mensagens de modelo de marketing entre você e o usuário. Também será exibido um segundo modal para que o usuário possa optar por interromper o recebimento de mensagens de marketing da sua empresa.

Controles de interrupção e retomada

Os usuários do WhatsApp podem usar a configuração Ofertas e anúncios para interromper ou retomar a entrega de mensagens de modelo de marketing da sua empresa.

Se você tentar enviar um modelo de marketing para um usuário do WhatsApp que interrompeu o recebimento de mensagens de modelo de marketing da sua empresa, a API processará a solicitação, mas não enviará a mensagem. Em vez disso, a API disparará um webhook de mensagens com:

• status definido como failed
• code definido como 131050
• title definido como Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business

Para receber uma notificação sempre que um usuário do WhatsApp interromper ou retomar o recebimento de mensagens de modelo de marketing da sua empresa, assine o webhook user_preferences.

Limites de mensagens de modelo de marketing por usuário

O que é isso?

O WhatsApp poderá limitar o número de mensagens de modelo de marketing que uma pessoa recebe de uma empresa em períodos com menos probabilidade de engajamento. Isso será determinado com base em vários fatores, incluindo uma visão dinâmica da taxa de leitura de mensagens de marketing recentes de uma pessoa e quantas mensagens de amigos, familiares e empresas existem na caixa de entrada.

A partir de 1º de abril de 2025, para focar a criação da experiência do consumidor, o WhatsApp não entregará nenhuma mensagem de modelo de marketing para pessoas com números de telefone dos Estados Unidos (código de discagem +1 e código de área dos EUA).

Por que isso é importante

O WhatsApp descobriu que limitar o envio de modelos de marketing maximiza o engajamento dessas mensagens e melhora a experiência do usuário, o que foi comprovado por meio de melhorias nas taxas de leitura e no sentimento do usuário. Essa limitação ajuda os usuários do WhatsApp a considerarem as mensagens comerciais mais valiosas e a não terem a sensação de que estão recebendo notificações demais.

Como isso afeta sua empresa

Nosso limite de marketing por usuário é adaptado ao longo do tempo com base nos níveis de engajamento recentes de uma pessoa. Talvez você entregue menos mensagens a alguns usuários durante períodos de baixas nas taxas de leitura de marketing ou na atividade geral na caixa de entrada, mas sua capacidade de alcançar as pessoas quando elas estiverem mais engajadas não vai mudar.

Alinhamento dos limites de marketing por usuário com as alterações futuras nos preços por mensagem

Com implementação gradual no segundo trimestre de 2025, as atualizações de preços por mensagem influenciarão o limite de marketing por usuário. Antes, o limite se aplicava apenas a mensagens de modelo de marketing que normalmente abririam uma nova conversa de marketing, e as empresas podiam enviar uma mensagem de modelo de marketing adicional se uma conversa já estivesse aberta entre você e um usuário do WhatsApp.

Agora, as empresas poderão enviar um número ilimitado de mensagens de marketing, porém, cada mensagem entregue contará para o limite de marketing por usuário. Uma exceção é que se uma pessoa responder a uma mensagem de marketing, ela iniciará uma janela de atendimento ao cliente 24 horas. As mensagens de marketing enviadas nessa janela não contarão para o limite de uma pessoa.

Como enviamos notificações via código de erro

Caso uma mensagem não seja enviada devido à aplicação do limite de modelo de marketing por usuário, um webhook de mensagens será disparado com o status definido como "falha" e o código (de erro) definido como 131049 (na API de Nuvem) ou 1026 (na API Local).

Se você receber esse código de erro e suspeitar que seja devido ao limite, evite reenviar imediatamente a mensagem de modelo. Fazer isso só resultará em outra resposta de erro, já que o limite pode estar em vigor em diferentes períodos. Em vez disso, tente enviar a mensagem novamente em intervalos de tempo cada vez maiores até que ela seja entregue.

Continuaremos aperfeiçoando nossa abordagem e agradecemos sua parceria à medida que investimos para tornar o WhatsApp a melhor experiência possível para sua empresa e seus clientes.

Solução de problemas

Se você está tendo problemas com a entrega de mensagens, consulte Mensagem não entregue.