--- title: "Link com preview personalizado no WhatsApp pela API" 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://api-wa.me/blog/link-preview-personalizado-whatsapp-api" language: "pt-BR" og:type: "article" og:site_name: "WAME API" --- [Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Link com preview personalizado no WhatsApp pela API: título, descrição e imagem Raphael Serafim· Publicado em 28 de setembro de 2026· 8 min de leitura Compartilhar # 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. Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/link-preview-personalizado-whatsapp-api.md) **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 Copiar ``` 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: bash Copiar ``` 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: | 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](https://api-wa.me/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): javascript Copiar ``` 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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/docs), e o panorama da camada não oficial está em [vantagens da API não oficial](https://api-wa.me/blog/api-whatsapp-nao-oficial-vantagens). ### Pronto para automatizar seu WhatsApp? Crie sua conta gratuita e comece a enviar mensagens pela API em minutos. [Começar grátis](https://portal.api-wa.me/sign-up) ## 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. ## Continue lendo [### Agente de voz no WhatsApp: latência, interrupção (barge-in) e silêncio Como deixar um agente de voz no WhatsApp natural: latência, streaming, detecção de fala, interrupção (barge-in), silêncio e eco, com exemplos em Node.js.](https://api-wa.me/blog/agente-voz-whatsapp-latencia-interrupcao)[### Anti-detecção na API não oficial do WhatsApp: como a WAME protege seu número Como funciona a camada de anti-detecção da API não oficial da WAME: identidade de dispositivo, tempo humano, ritmo de envio, reconexão e monitor de saúde.](https://api-wa.me/blog/anti-deteccao-api-whatsapp-nao-oficial)[### API do WhatsApp em C# (.NET): enviar mensagens e receber webhook Tutorial de API do WhatsApp em C# e .NET: HttpClient tipado, envio de texto, imagem e lista, webhook em ASP.NET Core com fila em background e tratamento de 429.](https://api-wa.me/blog/api-whatsapp-csharp-dotnet) [Voltar ao blog](https://api-wa.me/blog) ## Structured data ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "WAME API", "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram, Messenger e Telegram", "url": "https://api-wa.me", "inLanguage": "pt-BR", "publisher": { "@id": "https://api-wa.me/#organization", "@type": "Organization", "name": "WAME API", "url": "https://api-wa.me" } } { "@context": "https://schema.org", "@type": "Organization", "@id": "https://api-wa.me/#organization", "name": "WAME API", "alternateName": [ "WAME", "Wame API", "wame.api.br", "api-wa.me" ], "url": "https://api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/web-app-manifest-512x512.png", "width": 512, "height": 512 }, "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.", "identifier": { "@type": "PropertyValue", "propertyID": "INPI-BR", "name": "Pedido de registro de marca (INPI, classe NCL 42)", "value": "944724159" }, "foundingDate": "2017", "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram, Messenger e Telegram numa instância só. Desde 2017.", "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code e o Telegram, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.", "knowsAbout": [ "WhatsApp Cloud API oficial (Meta)", "API oficial de Instagram (Direct)", "API oficial de Messenger", "API multicanal Meta", "Meta Business Partner", "WhatsApp API", "API não oficial de WhatsApp", "automação de WhatsApp", "números virtuais", "webhooks" ], "sameAs": [ "https://github.com/wame-api", "https://www.linkedin.com/company/wameapi", "https://www.instagram.com/wame.api/", "https://www.youtube.com/@wameapi" ], "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://api-wa.me/contact", "availableLanguage": [ "Portuguese" ] } } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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.", "image": "https://api-wa.me/blog/link-preview-personalizado-whatsapp-api/opengraph-image", "datePublished": "2026-09-28", "dateModified": "2026-09-28", "author": { "@type": "Person", "name": "Raphael Serafim", "url": "https://github.com/raphaelvserafim", "sameAs": [ "https://github.com/raphaelvserafim" ] }, "publisher": { "@type": "Organization", "name": "api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/screenshot.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://api-wa.me/blog/link-preview-personalizado-whatsapp-api" }, "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", "inLanguage": "pt-BR" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://api-wa.me" }, { "@type": "ListItem", "position": 2, "name": "Blog da API do WhatsApp", "item": "https://api-wa.me/blog" }, { "@type": "ListItem", "position": 3, "name": "Link com preview personalizado no WhatsApp pela API: título, descrição e imagem", "item": "https://api-wa.me/blog/link-preview-personalizado-whatsapp-api" } ] } { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Como enviar um link com preview personalizado pela API do WhatsApp?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Qual a diferença entre /message/link e mandar a URL no texto?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Por que o preview do meu link não aparece?", "acceptedAnswer": { "@type": "Answer", "text": "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://." } }, { "@type": "Question", "name": "Posso usar encurtador de link nas mensagens?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Enviar links pela API aumenta o risco de bloqueio?", "acceptedAnswer": { "@type": "Answer", "text": "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." } } ] } ```