# Opt-out e keyword

Quando qualcuno invia un messaggio a uno dei tuoi numeri, Bird confronta il testo con un catalogo di keyword prima che tu lo riceva. Una keyword **stop** riconosciuta sopprime i messaggi futuri da quel mittente verso il destinatario, una keyword **start** termina la soppressione e **help** risponde con informazioni di supporto. I paesi supportati non richiedono configurazione per questo comportamento.

Questa guida spiega cosa fa Bird di default, come visualizzarlo e come modificarlo.

## Cosa succede di default

Un destinatario invia `STOP` a uno dei tuoi numeri. Bird:

1. **La riconosce** confrontandola con il catalogo di keyword per il paese di quel numero.
2. **Registra una soppressione** su quella esatta coppia mittente-destinatario.
3. **La conferma** rispondendo con il messaggio di opt-out per quel paese.

Da quel momento, un invio da quel mittente a quel destinatario viene rifiutato con [`E12077 SMSRecipientSuppressed`](/docs/api/errors/E12077) invece di essere spedito. Un `START` termina la soppressione e conferma la riattivazione, mentre `HELP` risponde senza modificare nulla.

Una soppressione copre **un mittente e un destinatario**. Non copre l'intero spazio di lavoro. L'ambito tecnico di quel blocco non stabilisce il permesso di usare un altro mittente. Applica la preferenza espressa dal cliente ai messaggi e al programma di cui ha chiesto l'interruzione. Per bloccare tutti i mittenti nello spazio di lavoro in una volta, vedi [Opt-out da tutti i mittenti](#opt-out-da-tutti-i-mittenti) più avanti.

La conferma è esente dalla soppressione che registra. Bird può rispondere al messaggio in entrata anche se la nuova soppressione blocca gli invii successivi in uscita.

## La copertura è per paese

Il catalogo di Bird copre un **sottoinsieme di paesi**. Dove un paese è coperto, Bird gestisce di default le keyword di opt-out, opt-in e help. Dove non lo è, Bird non riconosce alcuna keyword, non invia risposte e non registra opt-out. Se invii a un paese non coperto, devi gestire gli opt-out autonomamente.

Verifica cosa offre un paese prima di fare affidamento su di esso:

```bash
bird sms keyword-rules list --country NL
```

Un risultato vuoto indica che il paese non ha copertura. Puoi aggiungere le tue keyword `custom` lì, ma ogni altra operazione sostituisce qualcosa fornito da Bird, quindi puoi crearne una solo per un paese presente nel catalogo di Bird.

## Visualizzare cosa si applica

`GET /v1/sms/keyword-rules` descrive come vengono gestite le risposte ai tuoi numeri. Senza filtri, restituisce l'intero catalogo di Bird insieme a eventuali regole che hai creato; restringi con `country`, `number`, `operation` o `scope`:

- `scope=system` restituisce solo il catalogo di Bird, incluso il default sostituito da una regola dello spazio di lavoro.
- `scope=workspace` restituisce solo le tue regole.
- `number=+18005551234` restituisce le regole che si applicano a uno dei tuoi numeri, nell'ordine in cui vengono applicate a un messaggio in entrata; aggiungi `from_country` per vedere cosa riceve un mittente che scrive da altrove, che può differire.

Le regole sono restituite dalla più specifica, e ciascuna include `effective_keywords`: l'insieme di Bird per quell'operazione e paese più qualsiasi aggiunta tua.

L'elenco restituisce due operazioni oltre a `stop`, `start` e `help`:

- `info` risponde con le informazioni del tuo programma e si comporta esattamente come `help`. È separata perché un paese la cui risposta INFO deve differire dalla risposta HELP possa gestire entrambe; dove Bird non fornisce una regola `info` per un paese, INFO è una delle keyword `help` di quel paese e risponde con la risposta `help`.
- `confirm` contrassegna una risposta di doppio opt-in, come `JOIN` o `YES`. Non invia nulla al momento, quindi gestiscila dal tuo handler. Bird riserva quelle keyword in modo che una regola `custom` non possa reclamarle.

## Modificare la risposta

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

```bash
bird sms keyword-rules create \
  --operation stop \
  --country NL \
  --reply "You are unsubscribed from MyBrand. Reply START to resume."
```

La tua regola sostituisce la risposta predefinita di Bird per quel paese e **mantiene le keyword di Bird** salvo che tu ne aggiunga altre. Eredita anche le keyword che Bird aggiunge in seguito. Non puoi cambiare l'operazione assegnata a una keyword di opt-out o opt-in; Bird rifiuta una regola che tenta di associare `STOP` a un'altra operazione.

Dove Bird fornisce le keyword di un paese in più lingue, ogni lingua ha la propria regola, quindi una creazione deve specificare la lingua che sostituisce. Il Canada è quel paese: le sue regole `stop`, `start` e `help` sono disponibili in `en` e `fr`. `language` è obbligatorio lì e rifiutato per un paese che Bird fornisce in una sola lingua.

```bash
bird sms keyword-rules create \
  --operation stop \
  --country CA \
  --language fr \
  --reply "Vous etes desabonne de MyBrand. Repondez DEBUT pour reprendre."
```

Elencare le regole di un paese mostra se la suddivisione si applica e quali lingue sono disponibili.

Per limitare una regola a un solo numero anziché a tutti i numeri che possiedi nel paese, imposta `number` invece di affidarti solo al paese.

Se rispondi a questi messaggi dal tuo sistema anziché tramite Bird, imposta `reply` a null insieme a `confirmed_self_managed`. Questo disattiva la risposta automatica di Bird per la regola, mentre la soppressione stessa continua a funzionare.

## Keyword di campagna

Le regole `custom` non hanno comportamento integrato. Corrispondono alle keyword che scegli e inviano la risposta che scrivi, il che supporta keyword di campagna come `PIZZA`. Una regola `custom` non eredita keyword, quindi ne richiede almeno una propria, e può omettere `country` per applicarsi ovunque invii.

Una keyword che Bird ha associato a un'operazione di compliance non può essere riutilizzata come keyword personalizzata.

## Leggere e gestire le soppressioni

`GET /v1/sms/suppressions` elenca le coppie per cui i tuoi messaggi sono attualmente bloccati, dalla più recente. Filtra per `destination` per verificare un destinatario prima di inviargli un messaggio, per `originator` per uno dei tuoi mittenti, o per `reason`:

- `keyword_stop`: il destinatario ha inviato una keyword stop.
- `carrier_opted_out`: il suo operatore ha segnalato l'opt-out.
- `manual`: aggiunta tramite API o la dashboard.

Le soppressioni terminate non sono elencate, quindi la risposta identifica i destinatari a cui non puoi inviare messaggi in questo momento.

Puoi aggiungerne una manualmente per onorare un opt-out che un cliente ti ha comunicato per telefono:

```bash
bird sms suppressions add --destination +15550001234 --originator +15557654321
```

Una soppressione manuale blocca **ogni categoria, inclusa quella transazionale**, e l'aggiunta è idempotente. La rimozione è volutamente restrittiva: solo una soppressione `manual` può essere terminata in questo modo. La keyword stop del destinatario e l'opt-out dell'operatore vengono rifiutati, perché non spetta a te annullarli.

## Opt-out da tutti i mittenti

Una keyword stop e le soppressioni manuali sopra bloccano un solo mittente. Alcuni destinatari vogliono uscire da tutti i mittenti nello spazio di lavoro in una volta, ad esempio qualcuno che chiede al tuo team di supporto di interrompere tutti i messaggi anziché rispondere a ciascun numero singolarmente.

È una preferenza espressa, non una soppressione, quindi si trova nella scheda **Preferences** di **SMS** > **Suppressions**, non nell'elenco sopra. Apri la scheda e registra un opt-out con **Every sender in the workspace**: il numero smette di ricevere SMS da ogni mittente nello spazio di lavoro, inclusi mittenti che aggiungi in seguito. Un opt-out registrato in questa scheda copre tutti i messaggi, inclusi quelli di autenticazione; per registrarne uno che blocchi solo il marketing, usa la pagina **Contacts** > **Preferences** a livello di spazio di lavoro, il cui dialogo offre la scelta di copertura.

Bird verifica prima le soppressioni descritte in questa guida, quindi uno stop tramite keyword semplice viene comunque rifiutato con `E12077` come prima. Un invio a un numero con un opt-out a livello di spazio di lavoro registrato viene rifiutato con [`E25000 PreferenceRevoked`](/docs/api/errors/E25000). Per riprendere a inviare quando il destinatario te lo chiede, rimuovi la voce dalla scheda Preferences (l'hai registrata tu, quindi puoi rimuoverla), oppure registra un opt-in nella pagina **Contacts** > **Preferences** a livello di spazio di lavoro.

## Passaggi successivi

Consulta [consenso di campagna e controlli di invio](/products/sms/marketing/compliance) prima di un invio a un pubblico, oppure esplora [gestione opt-out SMS](/products/sms/compliance/opt-out) per la tua integrazione.

- [Invio SMS](/docs/guides/sms/sending-sms): consulta categorie, mittenti e condizioni di rifiuto.
- [Eventi](/docs/guides/sms/events): gestisci gli eventi `sms.*` per invii e risposte.
- [Log SMS](/docs/guides/sms/sms-log): ispeziona un messaggio, incluso un invio rifiutato.

## Related resources

- [How do I collect SMS opt-ins?](/explained/sms/how-do-i-collect-sms-opt-ins) (answer)
- [Preview message segments](/tools/sms-segment-calculator) (tool)
- [SMS compliance](/sms-api/features/compliance) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

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