Sign inGet Started

Regole delle parole chiave di WhatsApp

Bird fornisce il catalogo delle parole chiave, quindi un destinatario che risponde STOP a uno dei tuoi numeri abilitati alla ricezione viene disiscritto senza alcuna configurazione da parte tua. START annulla la disiscrizione. Una tua regola sostituisce l'impostazione predefinita di Bird per l'ambito che copre.

Questa pagina descrive cosa riconosce Bird, come viene confrontato un messaggio in arrivo e come modificare il testo o aggiungere parole chiave. La pagina Keywords è l'equivalente nella dashboard.

Un elenco di regole delle parole chiave, con le regole dello spazio di lavoro sopra le regole predefinite che sostituiscono

Cosa riconosce Bird per impostazione predefinita

Nove parole registrano una disiscrizione:

stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout

Due la annullano: start e unstop.

Il confronto avviene sull'intero messaggio e non su una sua parte. Poiché cancel e end sono parole chiave, questa distinzione è importante: "cancel my 3pm delivery" è un messaggio normale e non una revoca del consenso. Maiuscole e minuscole, accenti, spazi ripetuti e punteggiatura finale vengono ignorati, quindi sia Stop! sia STOP corrispondono. La punteggiatura prima o all'interno della parola non viene ignorata, quindi #stop non corrisponde.

Dove le parole chiave non vengono riconosciute

Una parola chiave all'interno di un messaggio di gruppo viene ignorata, quindi un partecipante non può revocare il consenso rispondendo lì. Rispetta la revoca dichiarata da un membro del gruppo nella tua logica di invio.

Quando viene registrata la preferenza

La classificazione avviene in parallelo all'evento whatsapp.received, non prima. Un'integrazione che osserva quell'evento può quindi vedere arrivare un STOP prima che esista la preferenza che registra. Se il tuo handler reagisce al messaggio in entrata inviando qualcosa, rileggi i record del destinatario invece di basarti sull'ordine degli eventi.

Vedere cosa si applica

GET /v1/whatsapp/keyword-rules descrive come vengono gestite le risposte ai tuoi numeri. Senza filtri, restituisce una riga per ambito: la tua regola dove ne hai una, e quella di Bird dove non ce l'hai. Una tua regola senza waba sostituisce la regola di Bird per la stessa operazione e lo stesso paese. Restringi i risultati con country, waba, operation o scope:

  • scope=system restituisce il catalogo di Bird, incluso il valore predefinito che una tua regola sostituisce.
  • scope=workspace restituisce le tue regole.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}

Le regole vengono restituite dalla più specifica, che è l'ordine in cui un messaggio in entrata viene confrontato con esse. Ognuna include effective_keywords: l'insieme di Bird per quell'operazione e quel paese, meno ciò che hai rimosso, più ciò che hai aggiunto.

Per una tua regola senza country, effective_keywords mostra l'insieme globale di Bird, perché la regola non ha un paese e quello del mittente è sconosciuto finché non arriva un messaggio. Quella regola confronta il messaggio con l'insieme di Bird per il paese del mittente, che può essere più ampio. Imposta un country sulla tua regola per vedere esattamente cosa riconoscono i messaggi di quei mittenti.

country è il paese del mittente, ricavato dal suo numero di telefono e non dal numero a cui ha scritto. È l'indicazione del paese che invia WhatsApp. Un mittente identificato da un ID utente legato all'azienda non ha un paese, quindi un suo messaggio salta le regole per paese e viene confrontato invece con una regola globale.

Modificare la risposta

Le risposte predefinite di Bird sono corrette ma generiche. Per rispondere a nome tuo, crea una regola:

const rule = await bird.whatsapp.keywordRules.create({
  operation: "opt_out",
  country: "US", // the SENDER's country, from their own number
  reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);

La tua regola sostituisce la risposta di Bird per quell'ambito e mantiene le parole chiave di Bird. I tuoi keywords si aggiungono a quelle esistenti invece di sostituirle, quindi una parola chiave che Bird introduce in seguito inizia a funzionare senza alcuna modifica da parte tua.

Per non inviare nulla continuando a registrare l'opt-out, ometti reply quando crei la regola. Per disattivare la risposta di una regola esistente, imposta reply su null in un corpo JSON nell'aggiornamento qui sotto; un flag CLI non può contenere null.

Una finestra di dialogo di una regola delle parole chiave che elenca le parole chiave di Bird, una parola chiave aggiunta, una parola chiave rimossa e una risposta

Aggiungere parole chiave personalizzate

// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's. reply: null switches the auto-reply off and still records
// the opt-out.
const rule = await bird.whatsapp.keywordRules.update("wkr_01m2kj8x4te9p0rr7e5w2n1abc", {
  keywords: ["no more texts", "remove me"],
});
console.log(rule.effective_keywords);

Se ometti keywords, le tue aggiunte restano invariate. Se invii un array vuoto, le aggiunte vengono eliminate e resta solo l'insieme di Bird.

Rimuovere le parole chiave di Bird

In alcune conversazioni cancel o stop servono come parole normali, ad esempio in un flusso di bot in cui cancel significa annullare questo passaggio. Elencale in excluded_keywords nella tua regola:

Esempio di codice
curl -X POST https://us1.platform.bird.com/v1/whatsapp/keyword-rules \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"opt_out","waba":"102290129340398","excluded_keywords":["cancel","end"]}'

A quel punto, un messaggio composto esattamente da una di queste parole non registra alcun opt-out e non riceve risposta per le persone coperte dalla regola. Il messaggio ti arriva comunque come di consueto, e la regola di Bird non interviene al suo posto. Per disattivare tutte le parole chiave di Bird, escludile una per una. Una parola chiave che Bird aggiunge in seguito viene comunque riconosciuta, a meno che la tua regola non la escluda già. Dopo aver rimosso delle parole chiave, spetta a te rispettare gli opt-out che esprimono. Il pulsante di opt-out di Meta nei modelli di marketing continua a funzionare.

In un aggiornamento, excluded_keywords sostituisce l'insieme delle parole rimosse, un array vuoto non ne rimuove nessuna e, se lo ometti, l'insieme resta invariato. Una parola chiave non può essere contemporaneamente aggiunta ed esclusa. Ogni parola chiave esclusa deve essere una delle parole chiave di Bird per l'operazione della regola. Per una regola con un country, deve essere una delle parole chiave di Bird per quel paese, oppure una delle parole chiave globali di Bird se Bird non ne ha per quel paese. Bird rifiuta qualsiasi altra parola con un 422, perché altrimenti rimuoverebbe quella parola se Bird la introducesse in seguito.

Ambito delle regole e duplicati

Una regola si può limitare a un solo account WhatsApp Business con waba, a un solo paese del mittente con country, a entrambi o a nessuno dei due. Puoi avere una sola regola per ogni combinazione di operazione, paese e account. Una seconda scrittura per la stessa combinazione restituisce un errore di duplicato.

Bird rifiuta una regola che associa stop a opt_in, sia che la parola provenga dal catalogo di Bird sia da un'altra delle tue regole, in modo che una parola di opt-out non possa mai concedere il consenso.

Eliminare una regola

Quando elimini la tua regola, quell'ambito passa alla regola successiva nell'ordine di corrispondenza, che non è sempre una delle tue. L'ordine è il seguente:

  1. La tua regola per un account e un paese.
  2. La tua regola per l'account.
  3. La tua regola per il paese.
  4. La regola di Bird per il paese del mittente.
  5. La tua regola globale.
  6. La regola globale di Bird.

Se elimini la tua regola per un paese, quindi, l'ambito passa alla regola di Bird per quel paese prima che alla tua regola globale:

// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");

Quando elimini una regola, il testo della risposta e l'insieme di parole chiave tornano a quelli della regola che segue in quell'ordine. Se quella regola è una delle tue ed esclude stop, anche lì STOP non ha alcun effetto.

Passaggi successivi

  • Preferenze: i record creati da una parola chiave e quali di essi puoi annullare.
  • Soppressioni: gli indirizzi che il tuo spazio di lavoro blocca direttamente.