Criar template

curl --request POST \
  --url https://cloud.datafyapi.com.br/v1/{waba_id}/message_templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "pedido_pronto",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}. O equipamento da ordem de serviço {{2}} está pronto para retirada.",
      "example": {
        "body_text": [
          [
            "Rafael",
            "7539"
          ]
        ]
      }
    }
  ]
}
'

{
  "id": "5400801403478858",
  "status": "PENDING",
  "category": "UTILITY"
}

{
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

{
  "statusCode": 401,
  "message": "Token inválido ou não encontrado."
}

{
  "statusCode": 402,
  "message": "Assinatura inativa. Ative sua assinatura no painel para voltar a usar a API."
}

{
  "statusCode": 429,
  "message": "Rate limit excedido (60 req/min). Tente novamente em 12s."
}

POST

{waba_id}

message_templates

curl --request POST \
  --url https://cloud.datafyapi.com.br/v1/{waba_id}/message_templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "pedido_pronto",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}. O equipamento da ordem de serviço {{2}} está pronto para retirada.",
      "example": {
        "body_text": [
          [
            "Rafael",
            "7539"
          ]
        ]
      }
    }
  ]
}
'

{
  "id": "5400801403478858",
  "status": "PENDING",
  "category": "UTILITY"
}

{
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

{
  "statusCode": 401,
  "message": "Token inválido ou não encontrado."
}

{
  "statusCode": 402,
  "message": "Assinatura inativa. Ative sua assinatura no painel para voltar a usar a API."
}

{
  "statusCode": 429,
  "message": "Rate limit excedido (60 req/min). Tente novamente em 12s."
}

Cria um template e o envia para análise da Meta. O template é criado com status PENDING e só pode ser utilizado em envios após ser aprovado. A resposta retorna o id do template:

{ "id": "5400801403478858", "status": "PENDING", "category": "UTILITY" }

A alteração de status é informada pelo webhook message_template_status_update, o que dispensa a consulta periódica à listagem.

Nome

O nome identifica o template no envio e aceita apenas letras minúsculas, números e sublinhado, sem espaços e sem acentos:

pedido_pronto
retirada_equipamento_2

Pedido Pronto
retirada-equipamento

O mesmo nome pode existir em vários idiomas, e cada idioma é analisado separadamente. A combinação de nome e idioma não pode ser repetida.

Categoria

Categoria	Finalidade
`UTILITY`	Mensagens referentes a uma transação existente: confirmação de pedido, aviso de entrega, cobrança
`MARKETING`	Ofertas, novidades, convites e demais conteúdos promocionais
`AUTHENTICATION`	Códigos de verificação

A categoria determina o preço e as regras de envio. As definições estão na visão geral de templates da Meta, e as regras específicas de marketing em templates de marketing personalizados.

A Meta reclassifica o template quando o conteúdo não corresponde à categoria informada. Um conteúdo promocional enviado como UTILITY é convertido para MARKETING. Se já existir uma versão daquele template em outra categoria, a criação falha com “A categoria MARKETING não corresponde à categoria já associada a este modelo, UTILITY”.

Componentes

O corpo (BODY) é obrigatório. Cabeçalho (HEADER), rodapé (FOOTER) e botões (BUTTONS) são opcionais.

{
  "name": "retirada_equipamento",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}. O equipamento da ordem de serviço {{2}} está pronto para retirada.",
      "example": { "body_text": [["Rafael", "7539"]] }
    },
    { "type": "FOOTER", "text": "Assistência Técnica Datafy" }
  ]
}

Para cabeçalho com imagem, vídeo ou documento, a Meta exige um header_handle no lugar da URL. Gere esse valor com Gerar handle de arquivo.

Variáveis posicionais ou nomeadas

As variáveis do template podem ser numeradas ou identificadas por nome. O formato é definido pelo campo parameter_format, que assume POSITIONAL quando não é informado.

{
  "parameter_format": "POSITIONAL",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}. O equipamento da ordem de serviço {{2}} está pronto para retirada.",
      "example": { "body_text": [["Rafael", "7539"]] }
    }
  ]
}

{
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{nome}}. O equipamento da ordem de serviço {{numero_os}} está pronto para retirada.",
      "example": {
        "body_text_named_params": [
          { "param_name": "nome", "example": "Rafael" },
          { "param_name": "numero_os", "example": "7539" }
        ]
      }
    }
  ]
}

As diferenças entre os dois formatos:

	Posicional	Nomeado
`parameter_format`	`POSITIONAL` (padrão)	`NAMED`
Marcação no texto	`{{1}}`, `{{2}}`	`{{nome}}`, `{{numero_os}}`
Campo do exemplo	`body_text`	`body_text_named_params`
Ordem no envio	Os valores seguem a numeração	Cada valor indica o `parameter_name` correspondente

Os nomes de parâmetro aceitam apenas letras minúsculas, números e sublinhado. Os dois formatos não podem ser combinados no mesmo template: um texto com {{nome}} e {{1}} é aceito na criação e reprovado na análise.

O formato escolhido na criação determina como as variáveis são preenchidas no envio, descrito em Enviar template.

Exemplo das variáveis

Toda variável precisa de um valor de exemplo, utilizado na análise do template. O comportamento difere conforme o formato:

No formato nomeado, a ausência de body_text_named_params retorna HTTP 400 com a mensagem “o componente do tipo BODY não contém o(s) campo(s) esperado(s) (example)”.
No formato posicional, a ausência de body_text não gera erro na requisição: a resposta é HTTP 200, o template é criado e passa para REJECTED, com rejected_reason igual a INVALID_FORMAT.

{
  "type": "BODY",
  "text": "Olá, {{1}}. Seu pedido {{2}} foi enviado.",
  "example": { "body_text": [["Rafael", "7539"]] }
}

{
  "type": "BODY",
  "text": "Olá, {{1}}. Seu pedido {{2}} foi enviado."
}

Um template reprovado pode ser corrigido em Editar template, sem necessidade de outro nome.

Erros comuns

A Meta retorna a descrição em error_user_msg, em português:

Situação	Mensagem da Meta
Nome com maiúscula, espaço ou hífen	”O nome do modelo de mensagem só pode ter letras minúsculas e sublinhados.”
Nome e idioma já utilizados	”Já existe conteúdo em Portuguese (BR) para esse modelo. Você pode criar um novo modelo e tentar novamente.”
Categoria diferente da já registrada	”A categoria MARKETING não corresponde à categoria já associada a este modelo, UTILITY.”
Exemplo ausente ou incompatível com o formato das variáveis	”o componente do tipo BODY não contém o(s) campo(s) esperado(s) (example)”

As regras de formato e os limites de cada componente estão em gerenciamento de templates da Meta.

Autorizações

Authorization

string

header

obrigatório

Token gerado no painel da Datafy ao criar o canal. Formato: sk_live_xxx.

Parâmetros de caminho

waba_id

string

obrigatório

ID da conta do WhatsApp Business. Descubra com GET /me.

Corpo

application/json

name

string

obrigatório

Nome do template, em letras minúsculas e com _ no lugar de espaços.

language

string

obrigatório

Código do idioma, como pt_BR.

Resposta

Template criado e enviado para análise.

Começar

Administração

Mensagens

Recursos de mensagens

Mídias

Templates

Conta e número

Endpoints Datafy

Webhooks

Nome

Categoria

Componentes

Variáveis posicionais ou nomeadas

Exemplo das variáveis

Erros comuns

Autorizações

Parâmetros de caminho

Corpo

Resposta

​Nome

​Categoria

​Componentes

​Variáveis posicionais ou nomeadas

​Exemplo das variáveis

​Erros comuns

Autorizações

Parâmetros de caminho

Corpo

Resposta

Nome

Categoria

Componentes

Variáveis posicionais ou nomeadas

Exemplo das variáveis

Erros comuns