Sign inGet Started

Plantillas de autenticación de WhatsApp

Una plantilla de autenticación entrega un código de verificación de un solo uso. Meta proporciona su texto cuando creas la plantilla. Al enviarla, indica el código como parámetro del cuerpo.

Antes de enviar

Elige si usar una plantilla gestionada por Bird o crear una plantilla en tu propia cuenta de empresa.

Para enviar las plantillas del catálogo de Bird, bird_otp y bird_otp_authifly, no necesitas ninguna verificación propia. Esas plantillas están en las cuentas de WhatsApp Business de Bird, y la ruta de envío gestionada nunca comprueba el estado de verificación de tu empresa.

Cuando la cuenta de empresa conectada indica not_verified, Bird rechaza la creación o duplicación de plantillas de autenticación con 412 E15043 WhatsAppTemplateBusinessNotVerified. Revisa la cuenta conectada y su último estado sincronizado. Consulta Verificación de empresa de WhatsApp para conocer el proceso de verificación y cómo se gestiona cada estado.

Este requisito no afecta a la creación de plantillas de utilidad y de marketing: puedes seguir creándolas y editándolas sea cual sea tu estado de verificación.

Crea plantillas en el panel, con la bird CLI o mediante el servidor MCP. Consulta Crear plantillas de autenticación para ver el proceso completo.

Enviar un código de verificación

POST /v1/whatsapp/messages con un objeto template que indique el slug del catálogo:

const msg = await bird.whatsapp.send({
  to: "+14155550100",
  template: {
    slug: "bird_otp",
    language: "en",
    parameters: { code: "481920" },
  },
});
console.log(msg.id, msg.status);

Cuatro reglas son específicas de esta categoría:

  • Omite from. Una plantilla gestionada por Bird elige su propio remitente según la categoría y la región, así que si defines from se devuelve 422 E15018 WhatsAppSenderNotAllowed. Es lo contrario de un envío de formato libre, que requiere from, algo que conviene tener en cuenta si llegas desde las páginas de mensajes interactivos.
  • to debe ser un número de teléfono E.164. Una plantilla de autenticación no puede enviarse a un ID de usuario limitado a una empresa; eso devuelve 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
  • El código va en parameters.code. Rellena el marcador de posición del cuerpo y el botón de copiar código. En cambio, un envío components admite exactamente un parámetro posicional en el cuerpo: el código. Si no envías ningún parámetro o le das nombre al parámetro, se devuelve 422 E15003 WhatsAppTemplateParameterMismatch.
  • No necesitas una ventana de atención al cliente. Los envíos de plantillas no dependen de la ventana, y precisamente por eso existe una plantilla de código de verificación: tiene que llegar a alguien que nunca te ha escrito antes.

Consulta los idiomas disponibles para bird_otp o bird_otp_authifly en el catálogo de plantillas. Si el idioma que solicitas no está disponible, el envío falla en lugar de usar otro idioma.

El botón de copiar código

Meta redacta el cuerpo de una plantilla de autenticación como un texto predefinido con un único marcador de posición para el código, así que tú proporcionas indicadores en lugar de texto. Un envío parameters rellena el botón a partir de code. En un envío components, el componente de botón es opcional: si no lo incluyes, Bird lo añade por ti con el mismo código que el cuerpo. También puedes proporcionarlo tú:

Ejemplo de código
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }

En ambos casos, a WhatsApp llega exactamente un botón, y es el de copiar código: al tocarlo, el código se copia al portapapeles. Bird solo admite copy_code; los otros dos comportamientos de botón que Meta documenta para las plantillas de autenticación, el autocompletado con un toque y sin toque, no están disponibles en Bird.

Al crear el botón de una plantilla se sigue la misma estructura: un botón otp, y la plantilla no admite ningún otro tipo de botón. En lugar de redactar el texto, proporcionas add_security_recommendation (un booleano que se muestra en el cuerpo) y code_expiration_minutes (de 1 a 90, que se muestra en el pie).

Qué permite Meta en una plantilla de autenticación

Meta fija la estructura de una plantilla de autenticación y revisa su contenido: no se permiten URL, archivos multimedia ni emojis en ninguna parte de la plantilla, y el parámetro del código tiene un límite de 15 caracteres. La categoría también cambia la forma en que WhatsApp entrega el mensaje, ya que solo lo envía al dispositivo principal del destinatario. Consulta Directrices de plantillas para ver en detalle la estructura fija, los límites de caracteres y el proceso de revisión.

Coste

La categoría y el destino determinan el precio. Consulta Tarifas de autenticación internacional de WhatsApp para saber cómo puede cambiar el precio si envías a un país distinto de tu ubicación principal, y Coste y facturación para saber cuándo se cobra un envío. Las tarifas concretas están en Precios de WhatsApp.

Puntos a tener en cuenta

  • Las plantillas predefinidas de Bird no se entregan en nueve países. bird_otp y bird_otp_authifly se envían desde las propias WhatsApp Business Accounts de Bird, y esas cuentas no entregan mensajes de autenticación en Egipto, India, Indonesia, Malasia, Nigeria, Pakistán, Arabia Saudí, Sudáfrica ni los Emiratos Árabes Unidos. Un envío de este tipo se rechaza con 422 E15063 WhatsAppDestinationRestricted antes de que se cobre nada. Una plantilla que hayas creado en tu propia cuenta y envíes desde tu propio número llega a estos países con normalidad. Verify también llega a ellos, porque traslada por sí solo el código de verificación a otro canal.
  • Un envío de una plantilla propia requiere from, que debe estar en la misma WhatsApp Business Account que la plantilla. Un remitente de otra cuenta se rechaza con 422 E15023 WhatsAppSenderWABAMismatch antes de que se cobre nada.
  • Solo puedes enviar un idioma cuya versión esté aprobada y activa. Un idioma en borrador, pendiente, rechazado o pausado no se puede enviar.
  • Meta puede cambiar la categoría de una plantilla por iniciativa propia. No es posible excluirse, y el cambio modifica las reglas de precio y entrega asociadas a la categoría.
  • La categoría de la plantilla y la de su idioma pueden no coincidir. Consulta Plantillas de WhatsApp para saber cómo lo resuelve la ruta de envío.
  • No se puede duplicar una plantilla de autenticación importada. Bird no puede convertir el texto generado por WhatsApp en los ajustes a partir de los que se crea una plantilla nueva; eso es 422 E15024 WhatsAppTemplateContentNotDuplicable. En su lugar, crea una nueva con su propia recomendación de seguridad y caducidad del código.

Próximos pasos