Enviar mensagens de modelo com variáveis personalizadas através da API WhatChimp

Envie mensagens de modelo com dados dinâmicos de assinantes através da API

Updated 10 February 2026

Quando você envia mensagens de modelo do WhatsApp através do WhatChimp, frequentemente você quer personalizá-las com informações específicas do assinante como nomes de empresa, localizações, detalhes de conta ou preferências. Campos personalizados (também chamados de variáveis personalizadas) permitem que você armazene esses dados diretamente no perfil de cada assinante. Quando seu modelo faz referência a esses campos, a API automaticamente puxa os valores dos dados armazenados do assinante.

A diferença chave das variáveis de modelo: você não passa os valores em cada solicitação de envio. Em vez disso, você define os dados no assinante uma vez, e o sistema os usa toda vez que você envia um modelo que precisa desses campos.

Precisa enviar valores diferentes com cada mensagem? Se você está enviando dados dinâmicos que mudam por mensagem (como códigos OTP, números de pedido ou IDs de rastreamento), use variáveis de modelo em vez disso. Campos personalizados são para dados que permanecem com o perfil do assinante.

Video: https://www.youtube.com/watch?v=yd1O0Sd_zDQ

Como funcionam as variáveis personalizadas com modelos

Campos personalizados são armazenados no perfil do assinante no WhatChimp. Quando você envia um modelo que inclui marcadores de posição de campos personalizados, o sistema automaticamente recupera os valores dos dados desse assinante e os insere na mensagem.

Aqui está o fluxo típico:

Passo A. Você define company="Acme Corp" e country="United States" em um assinante usando a API ou interface.

Passo B. Sua mensagem de modelo aprovada diz: "Oi {{first_name}}, oferta especial para clientes da {{company}} em {{country}}!"

Passo C. Você chama a API de envio com apenas o nome do modelo e número de telefone do assinante — sem parâmetros de variáveis necessários.

Passo D. O destinatário recebe: "Oi John, oferta especial para clientes da Acme Corp em United States!"

O sistema puxa "Acme Corp" e "United States" dos campos personalizados armazenados do assinante automaticamente. Você nunca passa esses valores na solicitação de envio.

Passo 1: Criar campos personalizados

Antes de poder usar campos personalizados em modelos ou armazená-los em assinantes, você precisa criá-los no WhatChimp.

Passo A. Faça login na sua conta WhatChimp e navegue até Subscriber Manager > Manage Custom Fields, ou vá diretamente para /whatsapp/subscriber/manager/custom-field/list.

Passo B. Clique no botão Create para adicionar um novo campo personalizado.

Passo C. Digite um nome de campo (ex., company, country, customer_email, membership_level). Use minúsculas com sublinhados para consistência.

Passo D. Selecione o tipo de resposta (texto, email, telefone, número, etc.) com base no tipo de dados que o campo armazenará.

Passo E. Clique em Save para criar o campo.

Página de Custom Fields

Repita este processo para todos os campos personalizados que você precisa. Campos comuns incluem nome da empresa, localização, tipo de conta, indústria ou qualquer informação específica do assinante que seu negócio usa.

Passo 2: Configurar assinante e valores de campos personalizados através da API

Antes de enviar um modelo que usa campos personalizados, o assinante deve existir na sua conta WhatChimp E ter valores de campos personalizados atribuídos ao seu perfil.

Criar o assinante (se ele ainda não existir)

Se o assinante ainda não está na sua conta WhatChimp, você precisa criá-lo primeiro usando a API de criar assinante.

Endpoint: POST /api/v1/whatsapp/subscriber/create

Parâmetros:

ParâmetroTipoObrigatórioDescrição
apiTokenStringSimSeu token de API WhatChimp
phoneNumberIDStringSimSeu ID de número de telefone WhatsApp
nameStringSimNome do assinante
phoneNumberStringSimNúmero de telefone do assinante com código do país (sem sinal +)

Exemplo de solicitação:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"

Resposta de sucesso:

{"status":"1","mesasge":"WhatsApp subscriber has been created."}
Se o assinante já existe, a API retorna "Something went wrong or subscriber already exist." — isso é esperado, e você pode pular este passo e ir direto para atribuir campos personalizados abaixo.

Verificar campos personalizados disponíveis

Recupere a lista de campos personalizados que você criou para verificar os nomes exatos dos campos.

Endpoint: POST /api/v1/whatsapp/subscriber/custom-fields/list

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/custom-fields/list \
  -d "apiToken=YOUR_API_TOKEN"

Resposta:

{
  "status": "1",
  "message": "Custom fields retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "company",
      "reply_type": "text"
    },
    {
      "id": 2,
      "name": "country",
      "reply_type": "text"
    },
    {
      "id": 3,
      "name": "customer_email",
      "reply_type": "email"
    }
  ]
}

Anote os nomes de campos que você usará no próximo passo.

Atribuir campos personalizados ao assinante

Agora defina os valores de campos personalizados no perfil do assinante. Isso funciona se você acabou de criar o assinante ou se ele já existia.

Endpoint: POST /api/v1/whatsapp/subscriber/chat/assign-custom-fields

Parâmetros:

ParâmetroTipoObrigatórioDescrição
apiTokenStringSimSeu token de API WhatChimp
phone_number_idStringSimSeu ID de número de telefone WhatsApp
phone_numberStringSimNúmero de telefone do assinante (com código do país, sem sinal +)
custom_fieldsJSONSimObjeto JSON com nomes e valores de campos

Exemplo de solicitação:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","customer_email":"john@acme.com"}'

Resposta de sucesso:

{
  "status": "1",
  "message": "Subscriber changes have been saved successfully."
}

Os valores de campos personalizados agora estão armazenados no perfil deste assinante. Você pode atualizá-los a qualquer momento chamando este endpoint novamente com novos valores.

Você também pode definir campos personalizados:

  • Editando manualmente assinantes na interface do Subscriber Manager
  • Importando contatos via CSV com colunas de campos personalizados
  • Usando fluxos de chatbot que capturam entrada do usuário e salvam em campos personalizados
  • Operações em massa através da API de assinantes

Passo 3: Criar um modelo com campos personalizados

Agora crie um modelo de mensagem WhatsApp que usa seus campos personalizados.

Passo A. Navegue até Bot Manager > Message Template no seu painel WhatChimp.

Passo B. Clique em Create para começar um novo modelo.

Passo C. Escreva o corpo da sua mensagem. Quando você quiser inserir um campo personalizado, clique no botão dropdown Custom Fields (com o ícone de engrenagem) acima da área de texto do corpo da mensagem. NÃO clique em "Variables" — isso insere variáveis de modelo, que funcionam de forma diferente.

Clique no dropdown Custom Fields para inserir dados de assinante no seu modelo

O dropdown Custom Fields mostra todos os campos personalizados que você criou no Passo 1 (como Country, Email, FullName, etc.). Clique em qualquer nome de campo para inseri-lo no corpo da sua mensagem de modelo.

Dropdown Custom Fields mostrando seus campos de assinante

Exemplo de corpo de modelo:

Oi {{first_name}}, temos uma oferta especial para {{company}}!

Como um cliente valioso em {{country}}, você é elegível para benefícios exclusivos. Clique abaixo para saber mais.

Passo D. Adicione quaisquer botões, cabeçalhos ou rodapés que seu modelo precisa.

Passo E. Clique em Save e envie para aprovação da Meta.

Aguarde a Meta aprovar seu modelo. Isso normalmente leva algumas horas a um dia. Uma vez aprovado, você pode enviá-lo via API.

Passo 4: Enviar o modelo através da API

Agora você está pronto para enviar o modelo. Note que a solicitação de envio NÃO inclui parâmetros de variáveis. Os valores de campos personalizados são automaticamente puxados dos dados armazenados do assinante.

Endpoint: GET/POST /api/v1/whatsapp/send

Parâmetros:

ParâmetroTipoObrigatórioDescrição
apiTokenStringSimSeu token de API WhatChimp
phone_number_idStringSimSeu ID de número de telefone WhatsApp
phone_numberStringSimNúmero de telefone do destinatário
template_nameStringSimNome do seu modelo aprovado
language_codeStringSimIdioma do modelo (ex., en, en_US)

Exemplo de solicitação (GET):

https://app.whatchimp.com/api/v1/whatsapp/send?apiToken=YOUR_API_TOKEN&phone_number_id=1234567890&phone_number=15551234567&template_name=special_offer&language_code=en_US

Exemplo de solicitação (POST):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=special_offer" \
  -d "language_code=en_US"

Resposta de sucesso:

{
  "status": "1",
  "message": "Message sent successfully",
  "data": {
    "message_id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgARGBI5QTNDQTA3RjU4Q0M1MTBGMkEA"
  }
}

O sistema automaticamente puxa os valores de campos personalizados (company, country, customer_email) do perfil do assinante e os insere no modelo. O destinatário vê uma mensagem totalmente personalizada sem você ter que passar esses valores em cada solicitação de envio.

Exemplo de fluxo de trabalho completo

Aqui está o processo completo de ponta a ponta para enviar mensagens de modelo com variáveis personalizadas:

Configuração única:

Passo A. Crie campos personalizados na interface WhatChimp (ex., company, country, membership_level).

Passo B. Crie e obtenha aprovação para um modelo que usa esses campos personalizados.

Para cada assinante:

Passo C. Crie o assinante se ele ainda não existe no WhatChimp:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"
Pule este passo se o assinante já existe na sua conta.

Passo D. Defina valores de campos personalizados no assinante:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","membership_level":"Gold"}'

Passo E. Envie o modelo (sem parâmetros de variáveis necessários):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=membership_update" \
  -d "language_code=en_US"

O assinante recebe uma mensagem personalizada como: "Oi John, sua assinatura Gold na Acme Corp está ativa. Como cliente em United States, você tem acesso a benefícios exclusivos."

Solução de problemas

ProblemaSolução
Campo personalizado aparece em branco ou ausente na mensagemO valor do campo não está definido no assinante. Use a API assign-custom-fields para defini-lo primeiro, ou edite o assinante manualmente na interface.
Tentando passar variable1=VALUE na solicitação de envioCampos personalizados não usam parâmetros de variáveis. Eles são puxados automaticamente dos dados do assinante. Se você precisa passar valores diferentes com cada mensagem, use variáveis de modelo em vez disso.
Erro "Custom field not found"O nome do campo no seu modelo não corresponde a um campo personalizado existente. Verifique o nome exato usando a API custom-fields/list.
Modelo rejeitado pela MetaA Meta pode rejeitar modelos com muitas variáveis ou mensagens pouco claras. Revise as diretrizes de modelo da Meta e simplifique se necessário.
Assinante não encontradoCertifique-se de que o número de telefone está no formato correto (código do país, sem sinal +) e que o assinante existe na sua conta WhatChimp.

Artigos relacionados

More in WhatChimp APIs