Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Rastreie links de campanha

Dê a cada destinatário de campanha um link curto, conte as aberturas de cada link e receba a primeira abertura de cada link como um evento de webhook.

Ver em Markdown

O rastreamento de links substitui um link em uma mensagem de campanha por um link curto diferente para cada destinatário. Quando um destinatário o abre, a Polymorfa conta a abertura e o redireciona para o seu destino.

O que você pode rastrear#

  • Campanhas enviadas de números com dispositivos vinculados ou de números de teste. Uma campanha que enviaria de números da API oficial é recusada no lançamento, porque um modelo aprovado mantém os links aprovados.
  • Até cinco links por campanha. Cada link tem uma key e uma url de destino.
  • key tem de 1 a 32 letras minúsculas, dígitos ou sublinhados e é única na campanha.
  • url é uma URL https absoluta com um nome de domínio público, com no máximo 2.048 caracteres. Nomes de usuário, senhas, endereços IP e nomes de rede local, como localhost ou nomes terminados em .local ou .internal, são recusados.

Use o Console#

Na etapa de mensagem do builder de campanhas, abra Links rastreados, escolha Adicionar link e informe uma chave e uma URL de destino. O painel mostra o marcador para colar na mensagem, como {{link:offer}}.

Use a API#

Envie trackedLinks ao criar ou atualizar um rascunho e escreva {{link:<key>}} onde o link deve ficar na mensagem.

cURL
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackedLinks": [
      { "key": "offer", "url": "https://example.com/spring-sale" }
    ]
  }'
TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  trackedLinks: [{ key: "offer", url: "https://example.com/spring-sale" }],
});

TypeScript:

create e update aceitam trackedLinks.

Na Platform API, envie o mesmo campo para API Create campaign ou API Update campaign.

Uma mensagem como Hi {{first_name}}, see the sale: {{link:offer}} chega a cada destinatário com o próprio link curto no lugar de {{link:offer}}. O marcador funciona em qualquer lugar onde o texto da mensagem da campanha funciona, incluindo o corpo e os botões de URL de um modelo.

As leituras de campanha retornam trackedLinks, um array vazio quando a campanha não rastreia nenhum link. Envie null ou [] para remover os links; removê-los não exige o beta.

Os links rastreados só mudam enquanto a campanha é um rascunho, inclusive enquanto ela aguarda um início agendado. Depois que o envio começa, uma alteração responde 409. Uma campanha lançada que aguarda o início ainda precisa definir todo {{link:<key>}} que as mensagens dela usam.

Verificações no lançamento#

O lançamento responde 400 invalid_parameter, com param definido como trackedLinks, quando:

  • uma mensagem usa um {{link:<key>}} que a campanha não define, para que um marcador nunca seja enviado como texto simples; ou
  • a campanha tem links rastreados e enviaria de números da API oficial.

O que os destinatários recebem#

Cada destinatário recebe um link curto no host da API para cada link rastreado que a mensagem dele usa:

Text
https://api.polymorfa.com/l/<token>
  • Abrir o link retorna um redirecionamento temporário para o destino que o link tinha quando a mensagem foi enviada. Uma alteração posterior na campanha nunca muda um link já enviado.
  • O redirecionamento não define cookies e não envia referrer.
  • Um link para de funcionar 90 dias depois que a Polymorfa o cria, quando a mensagem é preparada para envio. Um link expirado ou desconhecido responde 404.
  • Quando um envio é tentado novamente, a nova tentativa leva um novo link curto. O link anterior continua funcionando até expirar.

Enquanto sua equipe tem o beta, requisições GET a um link curto contam como aberturas, exceto prévias de link conhecidas, crawlers, scanners de segurança e requisições marcadas como prefetch. Essas requisições ainda são redirecionadas, mas não contam nem encerram uma sequência de gotejamento. Requisições HEAD nunca contam. A detecção é de melhor esforço: buscas automatizadas desconhecidas ou disfarçadas ainda podem contar, então uma abertura não prova que uma pessoa clicou.

cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/links" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const links = await messaging.raw.request({
  method: "GET",
  path: `/messaging/projects/<project-slug>/campaigns/${campaignId}/links`,
});
console.log(links.data);

TypeScript:

O SDK ainda não tem um método para o relatório de aberturas de links. Chame a rota com raw.request.

JSON
{
  "success": true,
  "data": [
    { "key": "offer", "url": "https://example.com/spring-sale", "uniqueOpens": 412, "totalOpens": 655 }
  ]
}
CampoSignificado
uniqueOpensDestinatários que abriram o link pelo menos uma vez.
totalOpensTodas as aberturas registradas, incluindo as repetidas.

A Platform API retorna a mesma lista em API Get campaign links. A leitura exige campaigns:read. No Console, a página de análises da campanha mostra Aberturas de links.

Receba a primeira abertura como webhook#

Inscreva um webhook de projeto em campaign.recipient_link_opened. A Polymorfa o envia uma vez por destinatário e link rastreado, na primeira abertura.

JSON
{
  "id": "019b2345-5555-7555-8555-555555555555",
  "session": "sales-1",
  "timestamp": "2026-10-05T14:20:00.000Z",
  "event": "campaign.recipient_link_opened",
  "payload": {
    "campaignId": "019b2345-3333-7333-8333-333333333333",
    "recipientId": "019b2345-4444-7444-8444-444444444444",
    "linkKey": "offer",
    "openedAt": 1791190800
  }
}

session indica o número que enviou a mensagem do destinatário. openedAt usa segundos Unix. O evento não traz número de telefone, link, destino, endereço IP nem user agent. Use recipientId com a lista de destinatários da campanha para associá-lo aos seus próprios registros. Veja Eventos de campanha para as regras de entrega.

TypeScript:

O SDK TypeScript tipa a carga como CampaignRecipientLinkOpenedPayload.

Privacidade e retenção#

  • A Polymorfa não armazena o endereço IP nem o user agent de um destinatário com uma abertura.
  • As contagens de aberturas são mantidas por 400 dias após a primeira abertura de um link por um destinatário.
  • Excluir uma campanha ou um destinatário exclui os respectivos links curtos e aberturas.

Saída do beta#

Quando sua equipe sai do beta ou o beta deixa de estar disponível para ela:

  • Mensagens enviadas depois disso levam o destino original de cada link, sem rastreamento.
  • Links curtos já enviados continuam redirecionando até expirar, sem registrar aberturas nem enviar eventos.
  • Definir links rastreados, lançar uma campanha com links rastreados e ler aberturas de links respondem 403 feature_unavailable. Remover links rastreados continua funcionando.