Sign inGet Started

Reglas de palabras clave de WhatsApp

Bird incluye el catálogo de palabras clave, así que un destinatario que responde STOP a uno de tus números que admiten mensajes entrantes queda dado de baja sin que tengas que configurar nada. START revierte la baja. Una regla propia sustituye la predeterminada de Bird en el ámbito que cubre.

Esta página explica qué reconoce Bird, 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 encima de las reglas predeterminadas que sustituyen

Qué reconoce Bird de forma predeterminada

Nueve palabras registran una baja:

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 parte de él. Como cancel y end son palabras clave, esa diferencia importa: "cancel my 3pm delivery" es un mensaje normal, no una retirada del consentimiento. Se ignoran las mayúsculas y minúsculas, los acentos, los espacios repetidos y la puntuación final, así que Stop! y STOP coinciden. La puntuación antes de la palabra o dentro de ella no se ignora, así que #stop no coincide.

Dónde no se comparan las palabras clave

Las palabras clave dentro de un mensaje de grupo se omiten, así que un participante no puede darse de baja respondiendo allí. Respeta en tu propia lógica de envío la baja que exprese un miembro del grupo.

Cuándo se registra la preferencia

La clasificación se ejecuta en paralelo con el evento whatsapp.received, no antes. Por eso, una integración que escuche ese evento puede ver llegar un STOP antes de que exista la preferencia que registra. Si tu controlador responde al mensaje entrante enviando algo, vuelve a leer los registros del destinatario en lugar de dar por hecho el orden de los eventos.

Ver qué reglas se aplican

GET /v1/whatsapp/keyword-rules describe cómo se gestionan las respuestas a tus números. Sin filtros, devuelve una fila por ámbito: tu regla donde tengas una y la de Bird donde no. Una regla tuya sin waba sustituye la regla de Bird para la misma operación y el mismo país. Acota los resultados con country, waba, operation o scope:

  • scope=system devuelve el catálogo de Bird, incluida la regla predeterminada que sustituye una regla tuya.
  • 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 específica, que es el orden en que se compara con ellas un mensaje entrante. Cada una incluye effective_keywords: el conjunto de Bird para esa operación y ese país, sin lo que hayas quitado y con lo que hayas añadido.

En una regla tuya sin country, effective_keywords muestra el conjunto mundial de Bird, porque la regla no tiene país y el del remitente no se conoce hasta que llega un mensaje. Esa regla se compara con el conjunto de Bird para el país del remitente, que puede ser más amplio. Define un country en tu regla para ver exactamente qué palabras coinciden para esos remitentes.

country es el país del remitente, determinado a partir de su propio número de teléfono y no del número al que escribió. Es la señal de país que envía WhatsApp. Un remitente identificado con un ID de usuario vinculado a una empresa no tiene país, así que su mensaje 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 nombre de tu empresa, 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 sustituye la respuesta de Bird para ese ámbito y conserva las palabras clave de Bird. Tus keywords se suman a ellas en lugar de sustituirlas, así que una palabra clave que Bird incorpore más adelante empieza a coincidir sin que tengas que cambiar nada.

Para no enviar nada y seguir registrando la baja, omite reply al crear la regla. Para silenciar una regla existente, establece reply en null en un cuerpo JSON en la actualización que se muestra a continuación; un indicador CLI no puede contener null.

Un cuadro de diálogo de regla de palabras clave que muestra las palabras clave de Bird, una palabra clave añadida, una palabra clave quitada 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);

Si omites keywords, tus palabras añadidas no cambian. Si envías un array vacío, se eliminan y vuelve a aplicarse el conjunto de Bird.

Quitar palabras clave de Bird

Algunas conversaciones necesitan cancel o stop como palabras corrientes, por ejemplo, un flujo de bot en el que cancel significa cancelar este paso. Indícalas en excluded_keywords en tu regla:

Ejemplo de código
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 partir de ese momento, un mensaje que sea exactamente una de ellas no da de baja a nadie ni recibe respuesta para las personas que cubre la regla. El mensaje te sigue llegando como siempre, y la regla propia de Bird no actúa sobre él en su lugar. Para desactivar todas las palabras clave de Bird, exclúyelas una por una. Una palabra clave que Bird añada más adelante sí coincide, salvo que tu regla ya la excluya. Si quitas palabras clave, te corresponde a ti respetar las bajas que expresan. El botón de baja propio de Meta en las plantillas de marketing sigue funcionando.

En una actualización, excluded_keywords sustituye el conjunto de palabras quitadas, un array vacío no quita ninguna y, si lo omites, el conjunto no cambia. Una palabra clave no puede estar añadida y excluida a la vez. Cada palabra clave excluida debe ser una de las palabras clave de Bird para la operación de la regla. En una regla con country, debe ser una de las palabras clave de Bird para ese país, o de las palabras clave mundiales de Bird si Bird no tiene ninguna para él. Bird rechaza cualquier otra palabra con un 422, porque de lo contrario quitaría esa palabra si Bird la incorporara más adelante.

Ámbito de las reglas y duplicados

Una regla se limita a una cuenta de empresa de WhatsApp con waba, a un país del remitente con country, a ambos o a ninguno. Puedes tener una regla por cada 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 asocie stop a opt_in, tanto si la palabra procede del catálogo de Bird como de otra de tus reglas, para que una palabra de baja no pueda usarse para otorgar consentimiento.

Eliminar una regla

Al eliminar tu regla, ese ámbito pasa a la siguiente regla en el orden de coincidencia, que no siempre es una de las tuyas. El orden es el siguiente:

  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 global.
  6. La regla global de Bird.

Por tanto, si eliminas tu regla para un país, el ámbito pasa a la regla de Bird para ese país antes que a tu propia regla global:

// 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");

Al eliminar una regla, el texto y el conjunto de palabras clave vuelven a los de la regla que siga en ese orden. Si esa regla es una de las tuyas que excluye stop, STOP tampoco hace nada allí.

Próximos pasos

  • Preferencias: los registros que crea una palabra clave y cuáles de ellos puedes revertir.
  • Supresiones: las direcciones que tu espacio de trabajo bloquea directamente.