Templates

Um template é uma mensagem pré-aprovada pela Meta. É o único tipo de mensagem que você pode enviar quando a janela de 24 horas está fechada — ou seja, quando o contato não escreveu para você nas últimas 24 horas. Enquanto a janela está aberta você pode enviar texto livre; uma vez fechada, apenas um template chega ao cliente.

Os templates são criados e aprovados no dashboard. A API pública apenas os consome para enviar — não os cria nem os edita.

Como um template é resolvido

Identifique o template pelo nome

Um template é identificado pelo seu template_name — o mesmo nome que você vê no dashboard e que reporta à Meta.

Indique o idioma

O idioma é obrigatório em todo envio: adicione language no formato Meta lower_UPPER (ex. pt_BR) para escolher qual template enviar.

Verifique que esteja aprovado

Só é possível enviar templates com status APPROVED. Um em PENDING ou REJECTED não é enviável.

Componentes de um template

Um template é desenhado e aprovado no dashboard com partes fixas e slots dinâmicos. Ao enviá-lo pela API você apenas preenche esses slots: não é possível adicionar um header nem botões que o template não tenha.

body_variables

Os placeholders do corpo ({{1}}, {{2}}, …). Array de { index, value }, index a partir de 1, até 30 variáveis.

header

O cabeçalho: texto, ou mídia (imagem, vídeo ou documento) via file_uuid.

button_parameters

O parâmetro de um botão dinâmico (ex. o sufixo de um botão URL). Até 3.

É uma união por type — o tipo deve coincidir com como o template foi desenhado:

`type`	Campos	Notas
`text`	`text`	Texto do cabeçalho (até 1024 caracteres).
`image`	`file_uuid` (+ `transcription` opcional)	Imagem do header.
`video`	`file_uuid` (+ `transcription` opcional)	Vídeo do header.
`document`	`file_uuid`, `filename` opcional (+ `transcription` opcional)	Documento (PDF, etc.).

O file_uuid vem do fluxo de Enviar mídia. A transcription (até 4000 caracteres) é obrigatória quando a visão não pode transcrever o arquivo (MIME não suportado ou maior que 20 MB); se faltar nesse caso, a ação falha com TEMPLATE_HEADER_TRANSCRIPTION_MISSING.

button_parameters

Array de { subType, index, text }, até 3 botões:

subType — hoje apenas "url" (botão de URL dinâmica).
index — a posição do botão dinâmico dentro do template, a partir de 0.
text — o valor concatenado à URL base do botão (ex. o identificador de um recurso), até 1024 caracteres.

Ao escrever, a chave é subType (camelCase). O endpoint de leitura Detalhe do template devolve o mesmo campo como sub_type (snake_case): não copie a chave literal da resposta de leitura — ao enviar, sub_type é descartado em silêncio e a ação falha com INVALID_REQUEST.

Enviar um template

Você preenche o objeto template conforme os slots que ele tem. Estes são os casos mais comuns:

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "confirmacao_consulta",
          "language": "pt_BR",
          "body_variables": [
            { "index": 1, "value": "Ana" },
            { "index": 2, "value": "10:00 AM" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "promocao_visual",
          "language": "pt_BR",
          "header": {
            "type": "image",
            "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
            "transcription": "Banner: 20% de desconto em toda a loja até domingo."
          },
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "envio_fatura",
          "language": "pt_BR",
          "header": {
            "type": "document",
            "file_uuid": "9c1b2a3d-4e5f-6789-01ab-cdef23456789",
            "filename": "fatura-agosto.pdf",
            "transcription": "Fatura de agosto: total $1,250, vence em 15 de agosto."
          },
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "rastreamento_pedido",
          "language": "pt_BR",
          "body_variables": [
            { "index": 1, "value": "Ana" }
          ],
          "button_parameters": [
            { "subType": "url", "index": 0, "text": "pedido/8f21" }
          ]
        }
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "template": {
          "name": "confirmacao_consulta",
          "language": "pt_BR",
          "header": {
            "type": "image",
            "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
            "transcription": "Flyer da consulta: consultório 3, térreo."
          },
          "body_variables": [
            { "index": 1, "value": "María" },
            { "index": 2, "value": "3 de agosto, 10:00" }
          ],
          "button_parameters": [
            { "subType": "url", "index": 0, "text": "consulta/8f21" }
          ]
        }
      }
    ]
  }'

Os nomes dos templates você vê no dashboard, que é onde eles são aprovados. Para saber quais variáveis, header e botões um específico espera, consulte Detalhe do template.

Para enviar um texto ou mídia enquanto a janela está aberta e fazer o template chegar se estiver fechada, inclua o template junto ao conteúdo principal no mesmo send_message.

Dados de pagamento nas variáveis (marcadores)

Um marcador de pagamento é um token com a forma ==nome== que é substituído pelo dado de cobrança real daquela conversa no momento do envio. Em um template ele vai no valor de uma variável do corpo, nunca no texto do template. A Meta aprova o corpo com os placeholders (Olá {{1}}, sua CLABE é {{2}} ({{3}})), não os valores: esses viajam a cada envio. Por isso o marcador pode ser resolvido ali, e a Meta nunca vê o token.

{
  "conversation": {
    "phone": "+525512345678",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [
    {
      "type": "send_message",
      "template": {
        "name": "dados_de_pagamento",
        "language": "pt_BR",
        "body_variables": [
          { "index": 1, "value": "Manuel" },
          { "index": 2, "value": "==clabe_spei==" },
          { "index": 3, "value": "==clabe_bank==" }
        ]
      }
    }
  ]
}

Olá Manuel, sua CLABE é 646180110412345678 (STP)

Marcadores disponíveis: clabe_spei, clabe_bank e account_national_link.

Só funcionam em body_variables. No cabeçalho de texto e nos parâmetros de botão são rejeitados com PAYMENT_MARKER_UNSUPPORTED_FIELD (422).O motivo é que o tamanho desses campos é validado sobre o texto que você envia — medindo o marcador, não o dado que o substitui —, então uma substituição poderia transformar um valor válido ao salvar em uma rejeição da Meta na entrega. E o parâmetro de um botão é o sufixo de uma URL já aprovada, então um link de pagamento ali produziria uma URL aninhada. Mova o marcador para uma variável do corpo.O rodapé de um template não admite variáveis; isso é regra da Meta.

Se a conversa ainda não tiver conta de cobrança, uma é gerada nesse momento — o marcador é o gatilho. Por isso uma campanha cujos templates tragam marcadores cria uma conta por destinatário: é o que permite atribuir quem pagou.

O envio é bloqueado por inteiro, sem entregar nada, se o marcador não puder ser resolvido ou seu resultado não couber: nome mal escrito (PAYMENT_MARKER_UNKNOWN, 422), a conversa não tem esse dado (PAYMENT_MARKER_DATA_UNAVAILABLE, 422), o corpo interpolado passa dos 1024 caracteres da Meta (TEMPLATE_BODY_TOO_LONG, 422) ou não foi possível gerar a conta de cobrança (PAYMENT_PROFILE_GENERATION_FAILED, 500). Nunca se entrega uma mensagem pela metade num fluxo de dinheiro.

Templates de teste para conversas tester

O dashboard permite criar templates de teste (status: FAKE) a partir do módulo Tester sem passar pela aprovação da Meta. Existem para que o operador e os integradores testem fluxos contra conversas tester sem esperar a revisão da Meta. Regras de envio via API pública:

Conversa tester (is_tester: true em GET /conversation) — você pode enviar tanto templates APPROVED quanto templates FAKE. O envio replica o fluxo real mas não toca a Meta (wamid retorna "").
Conversa real (is_tester: false) — somente templates APPROVED. Se você tentar enviar um template FAKE ou um template com is_tester: true para uma conversa real, a API responde com TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION (422).

O catálogo público de templates não inclui templates FAKE — apenas os APPROVED reais. Se você precisa do nome de um template FAKE para enviá-lo, pergunte ao operador.

Introdução

Conceitos

Guias

Ações

Como um template é resolvido

Componentes de um template

body_variables

header

button_parameters

header

button_parameters

Enviar um template

Dados de pagamento nas variáveis (marcadores)

Templates de teste para conversas tester

Próximos passos

Enviar mensagens

Conversas

​Como um template é resolvido

​Componentes de um template

body_variables

header

button_parameters

​header

​button_parameters

​Enviar um template

​Dados de pagamento nas variáveis (marcadores)

​Templates de teste para conversas tester

​Próximos passos

Enviar mensagens

Conversas

Como um template é resolvido

Componentes de um template

header

button_parameters

Enviar um template

Dados de pagamento nas variáveis (marcadores)

Templates de teste para conversas tester

Próximos passos