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.

Exemplo de solicitação:

curl -X  POST \
 'https://graph.facebook.com/v19.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"
            }
          }
        ]
      }
    ]
  }
}'

{
  "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 WhatsApp Business Phone Number > Messages 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 carregue seus ativos de mídia e use os IDs 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/v19.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/v19.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.

Limites de mensagem de modelo de marketing por usuário

Estamos lançando novas abordagens com consumidores na Índia primeiro para criar experiências do usuário de alta qualidade e aumentar o engajamento com mensagens de modelo de marketing. Isso pode incluir a limitação do número de mensagens de modelo de marketing que uma pessoa recebe de uma empresa em um determinado período, começando com um pequeno número de conversas que têm menor probabilidade de serem lidas. Observe que o limite é determinado com base no número de mensagens de modelo de marketing que a pessoa já recebeu de uma empresa e não está relacionado especificamente ao seu negócio.

O limite será aplicado apenas a mensagens de modelo de marketing que normalmente iniciariam uma nova conversa de marketing. Se você já tiver iniciado uma conversa de marketing com um usuário do WhatsApp, as mensagens de modelo de marketing enviadas a ele não serão afetadas.

Caso uma mensagem de modelo de marketing não seja entregue a um determinado usuário devido ao limite descrito, a API de Nuvem e a API Local retornarão os códigos de erro 131026 e 1026, respectivamente. Importante: esses códigos de erro abrangem uma ampla gama de problemas que podem resultar na não entrega de uma mensagem e, por questões de privacidade, não divulgaremos se de fato a mensagem não foi entregue devido ao limite. Consulte o documento Solução de problemas da API de Nuvem e as Perguntas frequentes "Por que minha taxa de entrega não é de 100%?" da API Local para ver descrições de motivos de não entrega e o que é possível fazer para determinar a causa subjacente.

Se você receber um desses códigos de erro e suspeitar que seja devido ao limite descrito, evite reenviar imediatamente a mensagem de modelo, já que isso gerará outra resposta de erro. Em vez disso, tente novamente aplicando incrementos de tempo maiores até que a mensagem seja entregue, já que o limite talvez esteja em vigor por diferentes períodos.

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.