--- title: "Link com preview personalizado no WhatsApp pela API: título, descrição e imagem" description: "Como enviar link com preview personalizado (título, descrição e miniatura) pela API não oficial do WhatsApp, e quando usar o preview automático." url: "https://wame.api.br/blog/link-preview-personalizado-whatsapp-api" language: "pt-BR" og:type: "article" published_time: "2026-09-28" modified_time: "2026-09-28" author: "Raphael Serafim" keywords: "api whatsapp não oficial, api não oficial whatsapp, link preview whatsapp api, enviar link whatsapp api, miniatura link whatsapp, preview personalizado whatsapp, utm link whatsapp" reading_time: "8 min de leitura" --- # Link com preview personalizado no WhatsApp pela API: título, descrição e imagem > Como enviar link com preview personalizado (título, descrição e miniatura) pela API não oficial do WhatsApp, e quando usar o preview automático. **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: ```bash curl -X POST "https://server.wame.api.br/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: ```bash curl -X POST "https://server.wame.api.br/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: | Campo | Obrigatório | O que é | | --- | --- | --- | | `to` | Sim | Destinatário (número ou grupo) | | `text` | Sim | Texto da mensagem | | `title` | Sim | Título do cartão | | `description` | Não | Linha de apoio abaixo do título | | `thumbnailUrl` | Sim | Imagem da miniatura | | `sourceUrl` | Sim | Para onde o toque leva | 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](/blog/cobrar-pix-whatsapp-api); - **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): ```js 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://server.wame.api.br/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](/blog/metricas-campanha-whatsapp-api). ## 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](/blog/uso-responsavel-api-whatsapp-nao-oficial-spam). ## 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](/docs), e o panorama da camada não oficial está em [vantagens da API não oficial](/blog/api-whatsapp-nao-oficial-vantagens). ## Perguntas frequentes ### Como enviar um link com preview personalizado pela API do WhatsApp? Faça um POST em /{key}/message/link com 'to', 'title', 'text', 'thumbnailUrl' e 'sourceUrl' (obrigatórios) e 'description' (opcional). O cliente vê o cartão de preview com o título, a descrição e a miniatura que você escolheu, sem depender das tags da página. ### Qual a diferença entre /message/link e mandar a URL no texto? No /message/text, se a mensagem tem uma URL, o preview é montado automaticamente a partir das tags da página (título, descrição, imagem). No /message/link você define o preview: útil quando a página não tem boas tags, é um link de pagamento sem imagem, ou você quer um cartão específico para aquela mensagem. ### Por que o preview do meu link não aparece? No preview automático, os motivos comuns são página sem tags Open Graph, página lenta ou protegida por login, e imagem pesada demais. No preview personalizado, confira se thumbnailUrl é uma imagem acessível por HTTPS e se sourceUrl é a URL completa, com https://. ### Posso usar encurtador de link nas mensagens? Pode, mas encurtador genérico esconde o destino e é muito usado em golpes, o que deixa o cliente desconfiado e pode pesar na percepção de spam. Prefira o seu próprio domínio, com parâmetros UTM para medir cliques. ### Enviar links pela API aumenta o risco de bloqueio? Link por si só não bloqueia número. O risco vem de mandar o mesmo link para muita gente que não pediu, que é disparo em massa. Links dentro de conversas e notificações para quem pediu têm risco muito baixo quando o uso é o certo.