Link com preview personalizado no WhatsApp pela API: título, descrição e imagem

Pela API não oficial do WhatsApp você envia um link com preview totalmente personalizado — título, descrição e miniatura escolhidos por você — com POST /message/link; e, se só quer que a URL apareça com o preview da própria página, basta mandá-la no texto com POST /message/text, que monta o cartão automaticamente. A diferença é quem decide o que o cliente vê: a página de destino ou a sua mensagem.

O cartão de preview é o que faz alguém tocar no link. Uma URL crua, sem imagem, parece suspeita; um cartão com título claro e uma miniatura reconhecível parece o que é — um link legítimo da sua empresa. Este guia mostra os dois caminhos, quando usar cada um e como medir os cliques.

A camada não oficial não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Caminho 1: preview automático no texto

Na maioria dos casos, o mais simples resolve. Mande a URL dentro do texto:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Seu pedido saiu para entrega! Acompanhe aqui: https://loja-exemplo.com.br/pedido/48213"
  }'

Quando a mensagem tem uma URL, a API busca a página e monta o preview com o título, a descrição e a imagem que a própria página declara nas tags Open Graph (og:title, og:description, og:image). Se o seu site tem essas tags bem feitas, pronto: todo link sai com um cartão bonito, sem esforço.

O preview automático depende da página. Ele falha ou sai pobre quando:

• a página não tem tags Open Graph (muito comum em sistemas internos e links de pagamento);
• a página exige login ou está atrás de proteção contra robôs;
• a página é lenta para responder;
• a imagem declarada é pesada demais ou não está acessível.

Caminho 2: preview personalizado

Quando você quer controlar exatamente o que aparece — ou a página não ajuda —, use o endpoint de link:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/link" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Oi, Ana! O boleto da sua matrícula já está disponível:",
    "title": "Matrícula 2027 — Colégio Exemplo",
    "description": "Vencimento em 10/01. Pague pelo app do banco ou Pix.",
    "thumbnailUrl": "https://colegio-exemplo.com.br/img/cartao-matricula.jpg",
    "sourceUrl": "https://colegio-exemplo.com.br/financeiro/boleto/9921"
  }'

Os campos:

A vantagem é a independência: o cartão sai igual mesmo se a página de destino não tiver tag nenhuma, estiver atrás de login ou mudar amanhã.

Quando usar cada um

Preview automático (texto com URL):

• links para o seu site, blog ou produto, que já têm boas tags;
• respostas de atendimento com links variados;
• quando o destino é público e bem construído.

Preview personalizado (/message/link):

• links de pagamento e de boleto, que costumam não ter imagem nenhuma — combina com cobrança por Pix no WhatsApp;
• páginas com login (área do cliente, rastreio, segunda via);
• cartão específico por contexto: a mesma página de produto com título "Seu carrinho está te esperando" para um cliente e "Voltou ao estoque" para outro;
• conteúdo que você quer destacar com uma imagem feita para o WhatsApp.

Miniatura que funciona

A imagem é metade do cartão. Algumas regras práticas:

• HTTPS e acesso público direto. A URL precisa entregar a imagem, não uma página.
• Leve. Miniatura não precisa de alta resolução; imagem pesada atrasa o envio ou nem aparece. Algumas dezenas de KB bastam.
• Formato simples, como JPG ou PNG.
• Legível em tamanho pequeno. O cartão é pequeno no celular: logo grande, pouco texto, contraste alto.
• Sirva de um lugar rápido, como o seu CDN.

Medindo cliques com UTM

Link no WhatsApp sem rastreio vira "tráfego direto" no analytics, e você nunca sabe o que funcionou. Adicione parâmetros UTM ao sourceUrl (ou à URL no texto):

function comUtm(url, campanha, conteudo) {
  const u = new URL(url);
  u.searchParams.set('utm_source', 'whatsapp');
  u.searchParams.set('utm_medium', 'mensagem');
  u.searchParams.set('utm_campaign', campanha);
  if (conteudo) u.searchParams.set('utm_content', conteudo);
  return u.toString();
}

const BASE = 'https://us.api-wa.me/SUA_KEY';

async function enviarLinkRastreado(to, dados) {
  const res = await fetch(`${BASE}/message/link`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      to,
      text: dados.texto,
      title: dados.titulo,
      description: dados.descricao,
      thumbnailUrl: dados.miniatura,
      sourceUrl: comUtm(dados.url, dados.campanha, dados.variacao),
    }),
  });
  if (!res.ok) throw new Error(`falha no envio: ${res.status}`);
  return res.json();
}

Com utm_content, você compara variações de título e miniatura e descobre qual cartão gera mais cliques. As outras métricas — entregue, lido, respondido — estão em métricas de campanha no WhatsApp.

Encurtadores: melhor evitar os genéricos

Encurtador genérico esconde o destino do link. Para o cliente, isso é um sinal de alerta: golpes no WhatsApp usam muito esse recurso justamente para esconder para onde levam. Resultado prático: menos cliques e mais desconfiança — e mensagens que parecem golpe são as que mais recebem denúncia.

O preview personalizado resolve o motivo pelo qual muita gente usa encurtador ("a URL é feia e comprida"): o cliente vê o cartão, não a URL. Use o seu domínio, com UTM, e deixe o cartão fazer o trabalho visual. Se precisar de URL curta, crie no seu próprio domínio (sualoja.com.br/p/48213).

Links e o risco de bloqueio

Link, sozinho, não derruba número — as pessoas trocam links o tempo todo. O que pesa é o padrão: o mesmo link para muita gente que não pediu é o retrato do disparo em massa, e a WAME não apoia spam. A própria API recusa o envio (com 429) quando o mesmo texto sai para números demais em poucos minutos ou quando a instância começa a falar com gente nova demais de uma vez.

Links dentro de conversas, em notificações para quem pediu (pedido, boleto, agendamento) e em respostas de atendimento são uso normal, e a taxa de bloqueio nesse cenário é muito baixa quando o uso é o certo. Dois cuidados extras:

• Personalize o texto que acompanha o link — nome do cliente, número do pedido. Mensagem idêntica para todo mundo é o que o anti-spam procura.
• Para contato que nunca conversou com você, abra com um texto simples antes de mandar formatos mais ricos.

As regras completas estão em uso responsável da API não oficial.

Conclusão

No WhatsApp, o link é julgado pelo cartão. Com a API não oficial da WAME você tem os dois caminhos: mandar a URL no /message/text e deixar o preview sair das tags da página, ou usar o /message/link para definir título, descrição e miniatura você mesmo — ideal para boleto, link de pagamento, área logada e cartões por contexto. Some UTM para saber o que funciona, fuja de encurtadores genéricos e mantenha os links dentro de conversas com quem pediu. Os campos completos estão na documentação, e o panorama da camada não oficial está em vantagens da API não oficial.