# Pulsanti link WhatsApp

Un pulsante link aggiunge un pulsante tappabile sotto un messaggio WhatsApp che apre un URL nel browser del destinatario. Usalo quando il passaggio successivo si trova sul web, ad esempio una pagina di checkout o un elenco di date per un workshop, anziché nella chat stessa. Per una scelta a cui il destinatario risponde direttamente in WhatsApp, usa i [pulsanti di risposta](/docs/guides/whatsapp/message-types/interactive/reply-buttons) o i [menu a lista](/docs/guides/whatsapp/message-types/interactive/list-menus).

## Inviare un pulsante link

Imposta `interactive.type` su `cta_url`, con un oggetto `body_text` e un oggetto `cta_url` che contengono `text` e `url` del pulsante:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "cta_url",
    body_text: "Tap the button below to see the available dates.",
    cta_url: { text: "See dates", url: "https://example.com/workshops?click_id=a1b2c3" },
  },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/interactive/cta-url-buttons.curl.md)

`from` è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. La struttura completa aggiunge un header opzionale, un footer e la citazione di un messaggio precedente:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Tap the button below to see the available dates.",
    "footer_text": "Dates are subject to change.",
    "cta_url": {
      "text": "See dates",
      "url": "https://example.com/workshops?click_id=a1b2c3"
    }
  },
  "tags": [{ "name": "campaign", "value": "autumn-workshops" }],
  "metadata": { "order_id": "A-4192" }
}
```

`in_reply_to_message_id` cita un messaggio precedente nella stessa conversazione. Consulta la sezione dell'hub [citare un messaggio per correlare una risposta](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) per come funziona la risoluzione e cosa può non intercettare.

Questo tipo invia esattamente un pulsante `cta_url` e non può includere `buttons`, `list` o `cards` insieme a esso. Consulta la sezione [buttons](/docs/guides/whatsapp/message-types/interactive#buttons) dell'hub per la struttura condivisa del pulsante, che anche il pulsante link di una card carosello riutilizza.

## Header e footer

Un header è opzionale e può avere una di quattro forme:

```text
"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }
```

Un header multimediale (`image`, `video` o `document`) trasporta il file come URL `https` pubblico che WhatsApp scarica al momento dell'invio, anziché come handle di un media caricato. `footer_text` è opzionale e aggiunge una riga sotto il pulsante.

## Limiti

| Campo                      | Vincolo                             |
| -------------------------- | ----------------------------------- |
| Pulsanti `cta_url`         | esattamente uno                     |
| `cta_url.text` (etichetta) | obbligatorio, da 1 a 20 caratteri   |
| `cta_url.url`              | obbligatorio, da 1 a 2000 caratteri |
| `body_text`                | obbligatorio, da 1 a 1024 caratteri |
| `footer_text`              | opzionale, da 1 a 60 caratteri      |
| `header.text`              | da 1 a 60 caratteri                 |

Il limite di 2000 caratteri su `url` è proprio di Bird: Meta non pubblica un limite di lunghezza per questo campo. `url` verifica anche `format: uri`, un indirizzo assoluto con schema, ma Bird non controlla quale schema: un indirizzo `http://` supera la validazione di Bird, e Meta è l'unico arbitro sulla consegna effettiva.

## Cosa segnala un clic

Un tap apre l'indirizzo nel browser del destinatario e nulla torna indietro attraverso API. Il tap di un pulsante link non è un `interactive_reply`: il mapper inbound che produce `interactive_reply` gestisce solo il tap di un pulsante di risposta e il tap di una riga lista, e un link `cta_url` non ha una struttura inbound equivalente. Quello che vedi è il normale ciclo di vita outbound: gli stati `sent`, `delivered` e `read` del messaggio, ma `read_at` indica che il messaggio è stato aperto, non che il pulsante è stato tappato. Non esiste un evento di clic, nessun timestamp e nessun segnale di tap per destinatario da WhatsApp né da Bird.

Due modi per ottenere l'attribuzione, dato che l'invio stesso non te la fornisce:

- **Strumenta la landing page.** L'unica evidenza di clic disponibile è sul tuo server di destinazione, dall'URL che hai fornito.
- **Varia l'URL tu stesso, per destinatario.** L'`url` che invii è una stringa letterale: Bird la memorizza e la passa a Meta senza modifiche, senza sostituzione e senza sintassi a variabili. È identica per ogni destinatario di un singolo invio, quindi l'attribuzione per destinatario significa generare un proprio parametro di query, come `?click_id=<value>`, ed effettuare una chiamata `POST /v1/whatsapp/messages` per destinatario. L'endpoint accetta già un singolo `to` per chiamata, quindi si tratta di gestione lato tuo, non di una funzionalità mancante di API.

Una terza opzione esiste al di fuori di questo tipo: un [template](/docs/guides/whatsapp/templates) con una variabile pulsante `url` viene personalizzato per destinatario da WhatsApp stesso, fornito attraverso il componente `button` dell'invio. La variabile deve trovarsi alla fine dell'indirizzo, scritta come `{{1}}`, quindi può variare un segmento finale del percorso o un valore di query, ma mai l'host o la parte centrale dell'URL. Il compromesso: un template offre URL per destinatario e consegna al di fuori della finestra di servizio clienti, al costo della revisione di Meta e di una struttura approvata fissa, mentre un invio `cta_url` offre invio libero, senza revisione, all'interno di una finestra aperta con un URL che vari tu stesso.

## Limiti e casi particolari

- **La finestra di servizio clienti deve essere aperta.** Un pulsante link è un messaggio di servizio, consegnabile solo all'interno di una finestra aperta; consulta la sezione dell'hub [finestra di servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window). Il controllo della finestra fallisce in modo permissivo, quindi un `202` non è prova che la finestra fosse effettivamente aperta al momento dell'invio.
- **`from` deve essere un numero di proprietà del tuo spazio di lavoro.** Ometterlo, o indicare un numero che non è un sender connesso, viene rifiutato prima che l'invio venga creato.
- **L'URL è statico per l'intero invio e identico per ogni destinatario.** Non esiste una variabile per destinatario su questo tipo. Consulta [Cosa segnala un clic](#cosa-segnala-un-clic) per sapere come attribuire i clic comunque.
- **Nessun segnale di tap, mai.** Il tap di un pulsante link non produce alcun messaggio inbound né alcun evento webhook. Non costruire una funzionalità che prometta metriche di clic basandosi solo su questo tipo.
- **Bird controlla la forma dell'URL, non lo schema.** `url` deve essere un indirizzo assoluto con schema, ma Bird non richiede `https`, e neppure Meta pubblica restrizioni sullo schema. Al contrario, l'`url` di un header multimediale è documentato come richiedente `https`.
- **Un URL di header multimediale che WhatsApp non riesce a scaricare fallisce dopo l'accettazione dell'invio.** WhatsApp scarica l'asset dell'header al momento dell'invio e lo memorizza in cache per 10 minuti; un URL firmato deve sopravvivere all'invio, e un URL irraggiungibile fallisce in modo asincrono, con `media_rejected` sullo stato `last_error` del messaggio.

Nessuno dei controlli di struttura elencati nella tabella [errori](/docs/guides/whatsapp/message-types/interactive#errors) dell'hub può attivarsi su questo tipo: ispezionano le righe di una lista, un array `buttons` o le card di un carosello, e un messaggio `cta_url` non ha nessuna delle tre strutture. Un errore di struttura, come un'etichetta `text` oltre i 20 caratteri, torna come errore generico di validazione della richiesta anziché come uno di quei codici. Una citazione che non si risolve fa fallire la richiesta prima che venga creato o addebitato qualcosa: `404` [`E15071`](/docs/api/errors/E15071) quando l'id indica un messaggio non presente in questo spazio di lavoro, `422` [`E15072`](/docs/api/errors/E15072) quando indica un messaggio che non può essere citato. Per gli errori che qualsiasi invio WhatsApp può incontrare, una finestra chiusa, un sender mancante o non valido o un destinatario non valido, consulta la sezione [errori](/docs/guides/whatsapp/message-types/interactive#errors) dell'hub e [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp).

## Passaggi successivi

- [Messaggi interattivi WhatsApp](/docs/guides/whatsapp/message-types/interactive): cosa condividono tutti e sei i tipi interattivi
- [Template WhatsApp](/docs/guides/whatsapp/templates): per una variabile pulsante `url` che WhatsApp personalizza per destinatario
- [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): l'envelope della richiesta, il modello `202` e i tentativi sicuri

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)