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.
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
keye umaurlde destino. keytem de 1 a 32 letras minúsculas, dígitos ou sublinhados e é única na campanha.urlé uma URLhttpsabsoluta 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, comolocalhostou nomes terminados em.localou.internal, são recusados.
Adicione links rastreados a uma campanha#
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 -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" }
]
}'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:
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.
Leia as aberturas de links#
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 "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/links" \
-H "Authorization: Bearer $POLYMORFA_KEY"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.
{
"success": true,
"data": [
{ "key": "offer", "url": "https://example.com/spring-sale", "uniqueOpens": 412, "totalOpens": 655 }
]
}| Campo | Significado |
|---|---|
uniqueOpens | Destinatários que abriram o link pelo menos uma vez. |
totalOpens | Todas 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.
{
"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.