📋 Antes de começar

Certifique-se de contar com os seguintes elementos para realizar suas integrações com sucesso:

Token UUID válido: É sua credencial principal. Identifica sua empresa automaticamente (por isso não requer enviar o companyId no JSON).
Número de canal: Você deve ter à mão o número de telefone operativo, incluindo sempre o código do país (ex. +5491112345678).
Cliente HTTP: Utilize ferramentas para testes de API como Postman, Insomnia ou diretamente o terminal com curl.

⚙️ Passos de Configuração

Passo 1: Cabeçalho de autorização

Cada solicitação que você fizer à API requer estritamente os seguintes cabeçalhos (headers). Sem eles, o servidor rejeitará a requisição com um erro 401 Unauthorized.

HTTP

Authorization: Bearer <seu-token-uuid>
Content-Type: application/json

💡 Dica: Como o token já identifica automaticamente sua empresa em nosso banco de dados, nunca inclua o campo companyId no corpo da solicitação; a API o resolve internamente de forma segura.

Passo 2: Criar um modelo (POST)

Utilize o método POST para registrar e enviar para revisão um novo modelo no Meta através do fluxo do Atom.

Campos obrigatórios:

Campo	Tipo	Descrição
`channelNumber`	string	Número de telefone do canal (ex. +5491112345678).
`platform`	string	Sempre deve ser o valor `"whatsapp"`.
`language`	string	Código oficial do idioma (ex. `"es"`, `"en_US"`, `"pt_BR"`).
`category`	string	Tipo de conteúdo: `"MARKETING"`, `"UTILITY"` ou `"AUTHENTICATION"`.
`components`	array	O array com os blocos que formam a mensagem (texto, botões, etc.).
`groupIds`	string[]	IDs dos grupos autorizados para usá-lo. (Use `["ALL"]` para todos).
`groupNames`	string[]	Nomes dos grupos que correspondem aos IDs (ex. `["ALL"]`).

Campos opcionais:

Campo	Tipo	Padrão	Descrição
`name`	string	—	Nome único do modelo. Utilize sempre o formato `snake_case`.
`makeUnique`	boolean	`false`	Se você enviar `true`, adiciona um sufixo aleatório para evitar colisões de nome.

Exemplo A — Modelo simples (Cabeçalho de texto + Corpo)

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <seu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "bienvenida_simple",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Bienvenido" },
        { "type": "BODY", "text": "Gracias por contactarnos. Pronto te atenderemos." }
      ]
    }'

Exemplo B — Modelo com variáveis e botões de resposta rápida (Observação: Use os marcadores {{1}}, {{2}} para valores dinâmicos. É obrigatório incluir o objeto example com valores de exemplo, pois o Meta o exige para a revisão).

BASH

curl -X POST https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api \
  -H "Authorization: Bearer <seu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "channelNumber": "+5491112345678",
      "platform": "whatsapp",
      "language": "es",
      "category": "UTILITY",
      "name": "pedido_con_params",
      "groupIds": ["ALL"],
      "groupNames": ["ALL"],
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Solicitud de pedido" },
        {
          "type": "BODY",
          "text": "Estimado/a {{1}}, gracias por su interés en el modelo {{2}}.",
          "example": { "body_text": [["Nombre_Cliente", "Modelo_Vehiculo"]] }
        },
        { "type": "FOOTER", "text": "Estamos aquí para servirle." },
        {
          "type": "BUTTONS",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Confirmar pedido" },
            { "type": "QUICK_REPLY", "text": "Modificar pedido" }
          ]
        }
      ]
    }'

Passo 3: Atualizar um modelo existente (PATCH)

Utilize este método para atualizar os metadados internos de um modelo no Atom.

⚠️ Importante: O conteúdo real do WhatsApp (componentes, texto, botões e idioma) NÃO pode ser modificado através da API uma vez que o modelo foi criado/aprovado.

Campos disponíveis (Pelo menos um é necessário no corpo):

Campo	Tipo	Descrição
`description`	string	Nome interno de exibição para o modelo dentro do Atom.
`groupIds`	string[]	IDs de grupos autorizados para usar este modelo.
`groupNames`	string	Nomes de grupos correspondentes aos `groupIds`.
`active`	boolean	`true` para habilitar seu uso, `false` para desabilitá-lo.

Exemplo de solicitação PATCH:

BASH

curl -X PATCH "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1" \
  -H "Authorization: Bearer <seu-token-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Promo verão 2025",
      "active": false
    }'

Passo 4: Listar modelos (GET)

Recupere todos os modelos associados ao seu canal. Este endpoint suporta paginação e ordenamento para facilitar o gerenciamento de grandes volumes de dados.

Parâmetros de consulta (Query Params):

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`channelNumber`	string	Sim	—	Número de telefone exato para filtrar.
`page`	número	Não	`1`	Número da página a consultar.
`size`	número	Não	`10`	Quantidade de resultados por página.
`sort`	string	Não	`"asc"`	Direção da ordenação: `"asc"` ou `"desc"`.

Exemplo de solicitação GET:

BASH

curl -X GET "https://us-central1-atomchat-io.cloudfunctions.net/api/webhook/whatsapp/templates/api?channelNumber=+5491112345678&page=1&size=20&sort=desc" \
  -H "Authorization: Bearer <seu-token-uuid>"

💡 Recomendações e Boas Práticas

Nomenclatura limpa: Utilize sempre o formato snake_case (ex. bienvenida_cliente_nuevo) no nome dos seus modelos para evitar erros de sintaxe na validação do Meta.
Uso de makeUnique: Se você experimentar erros de "nome duplicado" ao tentar substituir um modelo que acabou de excluir, envie "makeUnique": true. A API adicionará automaticamente um sufixo numérico para evitar colisões.
Formatos de Cabeçalho: Lembre-se de que além de "format": "TEXT", os cabeçalhos do WhatsApp suportam conteúdo multimídia utilizando "format": "IMAGE", "VIDEO" ou "DOCUMENT".

⚠️ Resolução de Problemas Comuns

Se suas chamadas à API falharem, revise estes pontos críticos:

Erro 401 (Unauthorized): O token UUID está incorreto, vencido ou o cabeçalho não tem exatamente o formato Bearer <seu-token>.
Erro 404 (Channel not found): O channelNumber enviado não está registrado ou não se encontra ativo dentro de sua conta do Atom. Certifique-se de incluir o código do país sem o símbolo + se a API lhe retornar erros de formato de URL, ou conforme está registrado na plataforma.
Modelo travado em estado PENDING: Lembre-se de que a revisão é um processo de auditoria externo realizado pelo Meta (WhatsApp). Pode levar desde alguns segundos até 24 horas para ser aprovado.

Automatize sua comunicação em larga escala! 🚀

Integrar o gerenciamento de modelos através de nossa API permite que você escale sua operação, sincronize seus sistemas internos com o Atom e mantenha suas campanhas do WhatsApp funcionando de forma ininterrupta e sem intervenção manual. ✅

Como criar e gerenciar modelos do WhatsApp através da API

📋 Antes de começar

⚙️ Passos de Configuração

Passo 1: Cabeçalho de autorização

Passo 2: Criar um modelo (POST)

Passo 3: Atualizar um modelo existente (PATCH)

Passo 4: Listar modelos (GET)

💡 Recomendações e Boas Práticas

⚠️ Resolução de Problemas Comuns