Templates Meta

Disponibilize no seu SaaS somente templates aprovados e enviáveis, sem consultar a Graph API em cada tela.

Modelo recomendado

WhatsApp ManagerManager ou backend cria o template

→

Metaanalisa e muda o status

→

HookCloudcache + webhook + rate limit

→

Seu SaaSseletor de templates

Referências: Templates oficiais · Fetch Message Templates

Listar templates enviáveis

curl --request GET \
  --url 'https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-meta-templates&instance_id=UUID&status=APPROVED&sendable_only=true&page=1&page_size=50' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE'

{
  "ok": true,
  "source": "hookcloud_cache",
  "meta_waba_id": "WABA_ID",
  "sync": {
    "status": "synced",
    "last_success_at": "2026-07-21T12:00:00Z",
    "next_allowed_at": "2026-07-21T12:05:00Z"
  },
  "items": [
    {
      "template_id": "123456789",
      "template_name": "confirmacao_agendamento",
      "template_language": "pt_BR",
      "template_status": "APPROVED",
      "quality_status": "GREEN",
      "category": "UTILITY",
      "sendable": true,
      "components": [],
      "parameter_schema": {
        "total_parameters": 2,
        "parameters": [
          { "component": "body", "index": 1, "placeholder": "{{1}}", "kind": "text" },
          { "component": "body", "index": 2, "placeholder": "{{2}}", "kind": "text" }
        ]
      }
    }
  ]
}

Como usar parameter_schema

Gere o formulário da campanha a partir dos parâmetros retornados. Valide quantidade, ordem, tipo e mídia antes de enviar.

Campo	Exemplo	Uso
component	body	Parte do template
index	1	Ordem posicional
placeholder	{{1}}	Texto exibido no template
kind	text / image / video / document / button_url	Tipo de input
required	true	Validação do formulário

Atualização sem excesso de GET

A listagem usa o cache HookCloud. A Graph API é chamada quando a Meta envia uma mudança ou quando uma credencial autorizada solicita refresh.

{
  "route": "refresh-partner-meta-templates",
  "instance_id": "UUID_DA_INSTANCIA"
}

Use o sync_job_id e consulte get-partner-meta-template-sync. Não faça polling agressivo.

Regra sendable

Condição	Resultado
APPROVED ou REINSTATED + qualidade saudável	`sendable=true`
PENDING	Apenas exibir “Em análise”
REJECTED	Bloquear seleção e mostrar motivo
PAUSED ou DISABLED	Remover de campanhas
Qualidade RED / FLAGGED	Bloquear ou exigir revisão
Partner suspenso ou instância inativa	Não enviar

Enviar template

Use recipient com o BSUID da Meta. Templates de autenticação que exigem telefone continuam usando to. Veja as diferenças entre BSUID, user_id e username.

curl --request POST 'https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient": "BR.BSUID_RECEBIDO_DA_META",
    "type": "template",
    "template": {
      "name": "confirmacao_agendamento",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Marcos" },
            { "type": "text", "text": "22/07 às 15h" }
          ]
        }
      ]
    }
  }'

Referências: Template de texto · Template com mídia

Webhook de mudança

Ao receber hookcloud.meta.template.updated:

Deduplicate pelo ID do evento.
Atualize status local imediatamente.
Se sendable=false, interrompa novas seleções.
Consulte o catálogo HookCloud para componentes completos.

Criar, consultar, editar e excluir na Graph

O catálogo HookCloud é uma consulta sincronizada. A criação, edição e exclusão são realizadas pelo backend do parceiro diretamente na Meta, com o token da instância e a permissão whatsapp_business_management. O envio de mensagens usa whatsapp_business_messaging.

Ação	Método Graph	Identificador
Criar	`POST /v26.0/WABA_ID/message_templates`	WABA
Listar	`GET /v26.0/WABA_ID/message_templates`	WABA + paginação
Consultar um	`GET /v26.0/TEMPLATE_ID`	ID retornado pela Meta
Editar	`POST /v26.0/TEMPLATE_ID`	ID do template
Excluir uma tradução	`DELETE /v26.0/WABA_ID/message_templates?name=NOME&hsm_id=TEMPLATE_ID`	Nome e ID exatos

Criar um template de utilidade

curl --request POST 'https://graph.facebook.com/v26.0/WABA_ID/message_templates' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "confirmacao_agendamento",
  "language": "pt_BR",
  "category": "utility",
  "parameter_format": "positional",
  "components": [
    {
      "type": "body",
      "text": "Olá, {{1}}! Seu agendamento está confirmado para {{2}}.",
      "example": {
        "body_text": [
          [
            "Ana",
            "15/09 às 15h"
          ]
        ]
      }
    }
  ]
}'

Guarde o id retornado e acompanhe a análise. Criação aceita não significa que já é possível enviar. Use categoria e exemplos que correspondam ao conteúdo real.

Consultar e paginar

curl --request GET 'https://graph.facebook.com/v26.0/WABA_ID/message_templates?fields=id,name,language,status,category,components,parameter_format&limit=50' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN'

Continue com o cursor paging.cursors.after se houver próxima página. Não limite o catálogo aos primeiros 50 itens.

Editar os componentes

curl --request POST 'https://graph.facebook.com/v26.0/TEMPLATE_ID' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}! Confirmamos seu atendimento em {{2}}.",
      "example": {
        "body_text": [
          [
            "Ana",
            "15/09 às 15h"
          ]
        ]
      }
    }
  ]
}'

A edição substitui o conjunto completo de componentes: inclua cabeçalho, corpo, rodapé e botões que deseja manter. Nome e idioma não são editáveis dessa forma. A Meta limita as edições por estado do template; não altere a categoria de um template aprovado.

Excluir somente o template identificado

curl --request DELETE 'https://graph.facebook.com/v26.0/WABA_ID/message_templates?name=confirmacao_agendamento&hsm_id=TEMPLATE_ID' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN'

Após uma mutação, peça refresh-partner-meta-templates, acompanhe get-partner-meta-template-sync e consulte novamente o catálogo. Respeite o cooldown informado. O resultado da Graph e o resultado da sincronização são etapas distintas.

Referência: Gerenciamento oficial de templates · Criação e parâmetros posicionais/nomeados.

Selecionar sem ambiguidade

Para consultar por nome, envie template_name e language. Informe também instance_id ou meta_waba_id quando o parceiro possui mais de uma WABA. A mesma combinação de nome e idioma pode existir em WABAs diferentes. Ao consultar por template_id, não envie template_name junto.

O GET de listagem exige página inteira positiva e page_size de 1 a 200. Um refresh aceito retorna uma sincronização agendada; consulte o status até concluir ou falhar, respeitando o intervalo indicado.

Esta página ajudou?Use o Partner Portal para suporte e compartilhe o link desta seção.