Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Sua credencial de API no cabeçalho Authorization: Bearer sk_live_.... Crie e revogue credenciais no painel, em Conta → API Keys. O segredo aparece uma única vez, na criação.

A credencial identifica a organização: organization_id não é aceito em nenhuma requisição.

Body

application/json
​
name
string
required

Nome do modelo, único na organização.

Minimum string length: 1
Example:

"cobranca_vencida"

​
body
string
required

O corpo da mensagem, com uma regra de conteúdo por canal.

Em whatsapp: texto puro, a Meta não aceita marcação, e o tamanho é validado na criação contando o exemplo de cada variável.

Em email: aceita HTML, e o tamanho não é limitado.

Nos dois canais, os marcadores são numerados e sequenciais: {{1}}, {{2}}, {{3}}. Um marcador com texto, como {{nome}}, é recusado com 400 Formato inválido (placeholder com texto).

Example:

"Prezado(a) {{1}}, consta débito de R$ {{2}} com vencimento em {{3}}."

​
template_type
enum<string>
required

O tipo de cabeçalho, e é ele que decide se a mensagem leva um arquivo.

  • TEXT: só texto. É o caso normal e o único aceito em envio em massa.
  • DOCUMENT: a mensagem leva um documento.
  • IMAGE: a mensagem leva uma imagem.

Obrigatório em whatsapp, que é o canal padrão. Em email o Pombo assume TEXT e só TEXT é aceito: outro valor é recusado com 400 Invalid request: template_type inválido para email. Valor aceito: TEXT.

No envio o par é obrigatório nos dois sentidos: um modelo DOCUMENT ou IMAGE enviado como application/json, sem arquivo, é recusado com 400, e um modelo TEXT enviado como multipart/form-data, com arquivo, também. A Meta aprova o tipo de cabeçalho junto com o modelo, então mudá-lo depois exige uma nova aprovação.

Available options:
TEXT,
DOCUMENT,
IMAGE
Example:

"TEXT"

​
variables
object
required

As variáveis do corpo, uma entrada por marcador. Exemplo:

A chave é o marcador literal, entre chaves duplas: "{{1}}". Não é o índice 1 nem o variable_name. Envie {} se o corpo não tiver marcadores.

As chaves precisam ser consecutivas a partir de {{1}}. Um vão, como {{1}} e {{3}} sem {{2}}, é recusado com 400.

​
channel
enum<string>

Em minúsculas aqui, diferente de channel no envio, que é em maiúsculas.

Opcional: omitido, vale whatsapp, e com ele vêm a exigência de template_type e a aprovação da Meta. Para e-mail, informe email explicitamente.

Available options:
whatsapp,
email
Example:

"whatsapp"

Response

Modelo criado.

​
template_id
string
​
organization_id
string | null
​
name
string
​
channel
enum<string>
Available options:
whatsapp,
email
​
body
string
​
body_example
string

O body com cada marcador substituído pelo variable_example da variável, entre colchetes. Montado pelo Pombo, serve para pré-visualizar o texto sem preencher nada.

​
template_type
enum<string>

O tipo de cabeçalho. DOCUMENT e IMAGE são os que levam arquivo; TEXT é só texto.

VIDEO e LOCATION podem aparecer em modelos antigos e não são aceitos ao criar um modelo novo. Um envio com eles não leva arquivo.

Available options:
DOCUMENT,
IMAGE,
LOCATION,
TEXT,
VIDEO
​
language_code
enum<string>
Available options:
pt_BR,
en_US,
es_ES
​
template_status
enum<string>

Só um modelo APPROVED pode ser usado em um envio de WhatsApp. A aprovação é da Meta, não do Pombo.

Um modelo de whatsapp nasce PENDING: consulte GET /templates/{id} até chegar a APPROVED, e crie os seus modelos com antecedência, porque um envio com modelo não aprovado é recusado com 422.

Um modelo de email nasce APPROVED e serve para enviar na mesma hora.

Available options:
PENDING,
APPROVED,
REJECTED,
PAUSED,
DISABLED,
DELETED,
IN_APPEAL,
FLAGGED,
FAILED
​
template_origin
enum<string>

SYSTEM são modelos do catálogo do Pombo; ORG, os da sua organização.

Available options:
SYSTEM,
ORG
​
requires_attachment
boolean | null

Anotação de quem criou o modelo, sem efeito nenhum: nada no envio a consulta, e enviar sem arquivo não é recusado por causa dela. Não a envie.

Um modelo de whatsapp devolve sempre null, tenha você enviado o campo ou não; só um modelo de email devolve o valor como chegou.

Para um modelo que leve arquivo, o campo que importa é template_type, com DOCUMENT ou IMAGE.

​
variables
object

As variáveis do modelo. Estas chaves são as de parameters no envio.

​
subject
string | null

Campo histórico, sem efeito: não é o assunto que o destinatário recebe. O assunto de um e-mail é montado no momento do envio a partir do nome da organização.

Sempre null em um modelo criado pela API, nos dois canais: o campo não é gravado na criação. Só traz conteúdo em modelos antigos.

​
declined_reason
enum<string> | null

Por que a Meta recusou o modelo, quando template_status é REJECTED ou FAILED. null enquanto não houve recusa.

ABUSIVE_CONTENT e SCAM exigem reescrever o texto. INVALID_FORMAT, TAG_CONTENT_MISMATCH e INCORRECT_CATEGORY são erros de forma. REVIEW_TIMEOUT é falha da própria revisão e um modelo novo com o mesmo texto pode passar.

Available options:
ABUSIVE_CONTENT,
SCAM,
INVALID_FORMAT,
TAG_CONTENT_MISMATCH,
INCORRECT_CATEGORY,
REVIEW_TIMEOUT,
UNKNOWN,
null
​
rejected_reason
string | null

O motivo em texto livre, como o provedor o enviou. Não é estável e não deve ser comparado em código: para ramificar, use declined_reason.

​
created_at
string<date-time>
​
updated_at
string<date-time>

A última alteração do registro. Muda sem você fazer nada: a Meta atualiza o status e a categoria por webhook, e cada atualização mexe neste campo.