Sign inGet started

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 o i menu a lista.
Imposta interactive.type su cta_url, con un oggetto body_text e un oggetto cta_url che contengono text e url del pulsante:
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);
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:
Esempio di codice
{
  "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 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 dell'hub per la struttura condivisa del pulsante, che anche il pulsante link di una card carosello riutilizza.
Un header è opzionale e può avere una di quattro forme:
Esempio di codice
"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

CampoVincolo
Pulsanti cta_urlesattamente uno
cta_url.text (etichetta)obbligatorio, da 1 a 20 caratteri
cta_url.urlobbligatorio, da 1 a 2000 caratteri
body_textobbligatorio, da 1 a 1024 caratteri
footer_textopzionale, da 1 a 60 caratteri
header.textda 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 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. 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 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 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 quando l'id indica un messaggio non presente in questo spazio di lavoro, 422 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 dell'hub e Invio di messaggi WhatsApp.

Passaggi successivi