# 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.

> **Note**
>
> O rastreamento de links é um beta. Em [Recursos opcionais](https://docs.polymorfa.com/teams/opt-in-features), um
> proprietário ou administrador da equipe seleciona o rastreamento de links,
> depois **Participar**, revisa os termos e seleciona **Aceitar e participar**. A
> etapa de mensagem do builder de campanhas leva até lá pelo selo **Prévia**. Até que sua equipe participe e o beta esteja
> disponível para ela, requisições que definem links rastreados, lançam uma
> campanha com links rastreados ou leem aberturas de links respondem
> `403 feature_unavailable`.

## 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.

## 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.

```bash 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 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 `POST /platform/campaigns` ou
`PATCH /platform/campaigns/{campaignId}`.

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.

## 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.

```bash cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/links" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript 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 }
  ]
}
```

| 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
`GET /platform/campaigns/{campaignId}/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](https://docs.polymorfa.com/api/events#campaigns-events) 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.
