Preferencias
Una preferencia es una declaración sobre lo que una persona desea, registrada contra su identificador en un canal. En WhatsApp el identificador es un número de teléfono en formato E.164. Es un registro separado de una supresión, y ambos se comprueban antes de un envío.
Las preferencias llegan a tu espacio de trabajo de tres formas: WhatsApp reporta una, un destinatario escribe una palabra clave o tú registras una. Lo que puedes hacer con cada una depende de quién la declaró.
Qué contiene una preferencia
Una declaración es revoked, una exclusión, o granted, consentimiento.
También tiene una cobertura, que determina cuánto tráfico detiene. non_transactional cubre mensajes de marketing y otros no esenciales, mientras que los mensajes transaccionales como recibos y códigos de verificación siguen llegando. all cubre todos los mensajes. La pestaña Preferences los muestra en su columna Covers como Non-transactional y All messages.
Una declaración puede limitarse a un remitente con sender_scope, que en WhatsApp identifica la cuenta de negocio. Sin él, la declaración cubre el canal en todo tu espacio de trabajo, incluidas las cuentas que conectes después.
Una persona puede tener varias filas en un canal, como una exclusión de todo el canal junto a una limitada a un remitente. La declaración más restrictiva decide si un mensaje se envía.
Preferencias que Bird registra por ti
Cuando Bird recibe un evento de Meta indicando que un destinatario ha detenido los mensajes de marketing, registra una preferencia de origen del destinatario para esa cuenta de negocio de WhatsApp. La preferencia cubre mensajes no transaccionales. No crea una supresión de todos los mensajes ni excluye a la persona de todas las cuentas de tu espacio de trabajo.
Un destinatario puede declarar lo mismo respondiendo STOP. Esa preferencia se limita a la cuenta de negocio a la que escribió, igual que la anterior. Cubre todos los mensajes, porque un STOP escrito es más amplio que la exclusión de marketing de WhatsApp. Consulta las reglas de palabras clave para ver qué reconoce Bird y cómo cambiar la respuesta.
Un evento posterior de reanudación actualiza la preferencia de esa cuenta. Las supresiones y otras preferencias aplicables siguen vigentes, así que un evento de reanudación por sí solo no demuestra que un envío sea válido.
Preferencias que tú registras
Abre la página Suppressions y cambia a la pestaña Preferences. Registrar una allí con Every business account in the workspace impide que la dirección reciba mensajes de WhatsApp desde cualquier cuenta que tengas, incluidas las que conectes después.

El diálogo Record opt-out en esa pestaña registra cobertura de todos los mensajes.

Para registrar una que detenga solo el marketing, usa la página Contacts > Preferences de todo el espacio de trabajo, cuyo diálogo ofrece Marketing messages además de All messages.
Leer preferencias desde código
GET /v1/preferences devuelve las preferencias registradas del espacio de trabajo, empezando por la más reciente. Pasa channel=whatsapp para limitarlo a este canal, y handle junto con él para consultar todo lo registrado de un número antes de enviarle un mensaje:
for await (const preference of bird.preferences.list({
channel: "whatsapp",
handle: "+15550001234",
})) {
console.log(preference.status, preference.coverage, preference.sender_scope);
}for preference in client.preferences.list(channel="whatsapp", handle="+15550001234"):
print(preference.status, preference.coverage, preference.sender_scope)for pref, err := range client.Preferences.List(context.Background(), bird.PreferencesListParams{
Channel: bird.PreferenceChannelWhatsapp,
Handle: "+15550001234",
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(*pref.Status, *pref.Coverage)
}foreach ($bird->preferences->list(['channel' => 'whatsapp', 'handle' => '+15550001234']) as $preference) {
echo $preference->getStatus(), ' ', $preference->getCoverage(), PHP_EOL;
}bird preferences list --channel whatsapp --handle +15550001234curl "https://us1.platform.bird.com/v1/preferences?channel=whatsapp&handle=%2B15550001234" \
-H "Authorization: Bearer $BIRD_API_KEY"handle requiere channel, ya que el mismo identificador puede existir en más de un canal.
Registrar una preferencia desde código
POST /v1/preferences registra una declaración. La escritura es un upsert con clave en el canal, el identificador y el alcance del remitente, así que una nueva declaración reemplaza la actual de esa clave:
const result = await bird.preferences.create({
channel: "whatsapp",
handle: "+15550001234",
status: "revoked",
coverage: "non_transactional",
});
console.log(result.applied, result.preference?.id);result = client.preferences.create(
channel="whatsapp",
handle="+15550001234",
status="revoked",
coverage="non_transactional",
)
print(result.applied, result.preference.id)result, err := client.Preferences.Create(context.Background(), bird.PreferencesCreateParams{
Channel: bird.PreferenceChannelWhatsapp,
Handle: "+15550001234",
Status: bird.PreferenceStatusRevoked,
Coverage: bird.PreferenceCoverageNonTransactional,
})
if err != nil {
log.Fatal(err)
}
// A newer statement already on file answers Applied false instead of an
// error, with the surviving statement in Preference.
if result.Applied != nil && *result.Applied {
fmt.Println("opt-out recorded")
}$result = $bird->preferences->create(
channel: 'whatsapp',
handle: '+15550001234',
status: 'revoked',
coverage: 'non_transactional',
);
echo var_export($result->getApplied(), true);bird preferences create \
--channel whatsapp \
--handle +15550001234 \
--status revoked \
--coverage non_transactionalcurl -X POST https://us1.platform.bird.com/v1/preferences \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"channel":"whatsapp","handle":"+15550001234","status":"revoked","coverage":"non_transactional"}'Las declaraciones se ordenan por el momento en que se hicieron, no por el momento en que llegan. API rechaza una declaración con fecha anterior a la actual de la clave y devuelve applied: false con la declaración que sobrevivió. El rechazo queda en el historial de la clave.
Un 201 significa que la clave no tenía registro y esta declaración creó uno. Un 200 devuelve el registro vigente de la clave, ya sea que esta declaración lo reemplazó, lo repitió o fue rechazada.
Qué puedes revertir
Una que tú registraste puedes eliminarla desde la pestaña Preferences o con DELETE /v1/preferences/{preference_id} cuando el destinatario te pida reanudar el envío.
Una declaración que la persona hizo por sí misma le corresponde a ella revertirla. Una cancelación de suscripción o una palabra clave de detención termina cuando la persona vuelve a aceptar, y un delete devuelve 422. Para reanudar el envío con su consentimiento, registra una declaración granted con consented_at, el momento en que consintieron. La concesión aplica cuando ese momento es posterior a la exclusión que revierte, de modo que registra el cambio de opinión en lugar de borrar la declaración original.
Un delete se ordena como cualquier otra declaración, usando el momento en que se recibe. Si el registro contiene una declaración hecha después de ese momento, el delete se rechaza y se devuelve con applied: false junto al registro vigente.
Cuando un error de entrega llega primero
Un error de entrega del proveedor puede reportar una detención antes de que Bird haya registrado un evento correspondiente. Respeta la decisión del destinatario e investiga el historial de preferencias y eventos en lugar de tratar un registro local ausente como permiso para enviar.
Próximos pasos
- Supresiones: las direcciones que tu espacio de trabajo bloquea directamente.
- Reglas de palabras clave: las palabras que registran una preferencia en tus números.
- Eventos de WhatsApp: el payload de whatsapp.rejected que produce un envío bloqueado.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación