Sign inGet started

Reglas de palabras clave

Bird incluye el catálogo de palabras clave, así que un destinatario que responda STOP a uno de tus números con capacidad de recepción queda excluido sin que configures nada. START lo revierte. Una regla tuya reemplaza el valor predeterminado de Bird en el alcance que cubre.
Esta página cubre lo que Bird reconoce, cómo se compara un mensaje entrante y cómo cambiar el texto o añadir palabras clave. La página Keywords es el equivalente en el panel.
Una lista de reglas de palabras clave, con las reglas del espacio de trabajo sobre las reglas predeterminadas que sustituyen

Qué reconoce Bird de forma predeterminada

Nueve palabras registran una exclusión:
stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout
Dos la revierten: start y unstop.
La comparación se hace con el mensaje completo, no con una subcadena. Como cancel y end son palabras clave, esa distinción importa: "cancel my 3pm delivery" es un mensaje común, no una retirada de consentimiento. Se ignoran mayúsculas, acentos, espacios repetidos y puntuación al final, así que Stop! y STOP coinciden. La puntuación antes o dentro de la palabra no se ignora, así que #stop no coincide.

Dónde no se comparan las palabras clave

Una palabra clave dentro de un mensaje de grupo se omite, así que un participante no puede excluirse respondiendo ahí. Respeta la exclusión declarada de un miembro del grupo en tu propia lógica de envío.

Cuándo se registra la preferencia

La clasificación se ejecuta junto con el evento whatsapp.received, no antes. Una integración que observe ese evento puede ver llegar un STOP antes de que exista la preferencia que registra. Si tu handler reacciona al mensaje entrante enviando algo, vuelve a leer los registros del destinatario en lugar de asumir el orden de los eventos.

Ver qué se aplica

GET /v1/whatsapp/keyword-rules describe cómo se gestionan las respuestas a tus números. Sin filtrar, devuelve el catálogo de Bird junto con las reglas que hayas creado. Acótalo con country, waba, operation o scope:
  • scope=system devuelve el catálogo de Bird, incluido el valor predeterminado que una regla tuya reemplaza.
  • scope=workspace devuelve tus propias reglas.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}
Las reglas se devuelven de la más específica a la menos, que es el orden en que un mensaje entrante se compara con ellas. Cada una lleva effective_keywords: el conjunto de Bird para esa operación y país, más lo que hayas añadido.
Para una regla tuya sin country, effective_keywords muestra el conjunto mundial de Bird, porque la regla no tiene país y el del remitente es desconocido hasta que llega un mensaje. Esa regla se compara con el conjunto de Bird para el país del remitente, que puede ser mayor. Asigna un country a tu regla para ver exactamente con qué coinciden esos remitentes.
country es el país del remitente, deducido de su propio número de teléfono y no del número al que envió el mensaje. Es la señal de país que WhatsApp envía. Un remitente identificado por un ID de usuario con alcance de negocio no lleva país, así que un mensaje de este tipo omite las reglas por país y coincide con una regla mundial.

Cambiar la respuesta

Las respuestas predeterminadas de Bird son correctas pero genéricas. Para responder en tu propio nombre, crea una regla:
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);
Tu regla reemplaza la respuesta de Bird para ese alcance y conserva las palabras clave de Bird. Tus keywords son adiciones, no un reemplazo, así que una palabra clave que Bird incorpore después empieza a coincidir sin que cambies nada.
Para no enviar nada y aun así registrar la exclusión, omite reply al crear la regla. Para silenciar una regla existente, establece reply a null en un cuerpo JSON en la actualización de abajo; un flag CLI no puede llevar null.
Un cuadro de diálogo para añadir una regla de palabras clave, con campos para palabras clave adicionales y una respuesta

Añadir tus propias palabras clave

// 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);
Omitir keywords deja intactas tus adiciones. Enviar un array vacío las restablece al conjunto de Bird.

Alcance de la regla y duplicados

Una regla se limita a una cuenta Business Account de WhatsApp con waba, a un país del remitente con country, a ambos o a ninguno. Tienes una regla por combinación de operación, país y cuenta. Una segunda escritura para la misma combinación devuelve un error de duplicado.
Bird rechaza una regla que vincule stop a opt_in, tanto si la palabra proviene del catálogo de Bird como de otra de tus reglas, de modo que una palabra de exclusión no puede convertirse en concesión de consentimiento.

Eliminar una regla

Eliminar tu regla cede ese alcance a la siguiente regla en el orden de comparación, que no siempre es una tuya. El orden es:
  1. Tu regla para una cuenta y un país.
  2. Tu regla para la cuenta.
  3. Tu regla para el país.
  4. La regla de Bird para el país del remitente.
  5. Tu regla mundial.
  6. La regla mundial de Bird.
Eliminar tu regla para un país cede el alcance a la regla de Bird para ese país antes que a tu propia regla mundial:
// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one; STOP never stops working.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");
Eliminar una regla no detiene el funcionamiento de STOP. Devuelve el texto y el conjunto de palabras clave a la regla que siga en ese orden.

Próximos pasos