Sign inGet started

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.
Una lista de suscriptores que aceptaron o rechazaron mensajes, con la cobertura de cada declaración
El diálogo Record opt-out en esa pestaña registra cobertura de todos los mensajes.
Un diálogo para registrar una exclusión, con el alcance de todo el espacio de trabajo seleccionado
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);
}
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);
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