API de administración de WhatsApp Business

Plantillas de autenticación

Las plantillas de autenticación estarán disponibles en la India el 1 de julio de 2024.

Si tu aplicación para móviles ofrece a los usuarios la opción de recibir contraseñas de un solo uso o códigos de verificación mediante WhatsApp, debes usar una plantilla de autenticación.

Las plantillas de autenticación constan de lo siguiente:

Un texto predefinido fijo: Tu código de verificación es <VERIFICATION_CODE>.
Un descargo de responsabilidad de seguridad opcional: Por tu seguridad, no compartas este código.
Una advertencia de caducidad opcional: El código caduca en <NUM_MINUTES> minutos.
Un botón de relleno automático con un toque, un botón para copiar el código o ningún botón si se usa la pulsación cero.

Los botones de relleno automático con un toque son la solución preferida, ya que ofrecen la mejor experiencia de usuario. Sin embargo, actualmente, los botones de relleno automático con un toque solo se admiten en Android y requieren cambios adicionales en el código de la aplicación.

Consulta las normas adicionales para saber cuándo procede usar las plantillas de autenticación.

Plantillas de autenticación de relleno automático con un toque

Las plantillas de autenticación incluyen un botón que permite el relleno automático con un toque.

Cuando un usuario de WhatsApp toca el botón de relleno automático, el cliente de WhatsApp activa una actividad que abre tu aplicación y entrega la contraseña o el código.

Consulta Plantillas de autenticación de relleno automático con un toque para aprender a usarlas.

Plantillas de autenticación de copia de código

Las plantillas de autenticación de copia de código permiten enviar a los usuarios una contraseña o un código de un solo uso junto con un botón para copiar el código.

Cuando un usuario de WhatsApp toca el botón para copiar el código, el cliente de WhatsApp copia la contraseña o el código al portapapeles del dispositivo. Después, el usuario puede cambiar a tu aplicación y pegar la contraseña o el código en ella.

Consulta Plantillas de autenticación de copia de código para aprender a usarlas.

Plantillas de autenticación por pulsación cero

Las plantillas de autenticación por pulsación cero permiten a los usuarios recibir contraseñas o códigos de un solo uso mediante WhatsApp sin tener que salir de tu aplicación.

Cuando un usuario de la aplicación solicita una contraseña o un código y tú lo entregas mediante una plantilla de autenticación por pulsación cero, el cliente de WhatsApp transmite la contraseña o el código incluidos. Después, tu aplicación puede capturarlos con un receptor de transmisiones.

Consulta Plantillas de autenticación por pulsación cero para aprender a usarlas.

Prácticas recomendadas

Confirma el número de teléfono de WhatsApp del usuario antes de enviarle la contraseña de un solo uso o el código.
Deja claro al usuario que la contraseña o el código se enviará a su número de teléfono de WhatsApp, sobre todo si le ofreces varias formas de recibir la contraseña o el código. Consulta Obtener el consentimiento para obtener más información.
Cuando el usuario pega la contraseña o el código en la aplicación, o la aplicación recibe esta información como parte del proceso del botón de relleno automático con un toque, déjale claro que la aplicación lo ha registrado.

Consulta, asimismo, Prácticas recomendadas para autenticar a los usuarios a través de WhatsApp.

Duración

Si no podemos entregar un mensaje a un usuario de WhatsApp, seguiremos intentando entregar el mensaje durante un periodo de tiempo que se conoce como duración.

Los mensajes tienen una duración predeterminada de 30 días, pero las plantillas de autenticación recién creadas tienen una duración predeterminada de 10 minutos.

Si no podemos entregar una plantilla de autenticación durante un periodo de tiempo que supere su duración, dejaremos de intentarlo y eliminaremos el mensaje. Si el tiempo que transcurre desde que realizas la solicitud de envío del mensaje de la plantilla de autenticación supera la duración y no recibes ningún webhook, debes suponer que se ha eliminado.

Para invalidar la duración predeterminada al crear una plantilla de autenticación, incluye la propiedad message_send_ttl_seconds con un valor establecido entre 60 y 600 segundos.

Las plantillas existentes creadas antes de que esta funcionalidad estuviera disponible tienen una duración de 30 días. Si quieres, puedes editar una plantilla existente e invalidar su duración estableciendo su propiedad message_send_ttl_seconds.

También puedes establecer la propiedad message_send_ttl_seconds de una plantilla de autenticación en -1. Esta acción establecerá su duración en 30 días.

Te recomendamos que establezcas una duración para todas las plantillas de autenticación, preferiblemente igual o inferior al tiempo de caducidad de tu código, para asegurarte de que los clientes solo reciban un mensaje cuando el código todavía se pueda utilizar.

Ten en cuenta que podría producirse un ligero retraso en la entrega del webhook de mensaje con error, así que tal vez te interese añadir un pequeño búfer al inferir una eliminación.

Envío de mensajes de plantillas de autenticación

Usa la API de nube o la API local para enviar plantillas de autenticación aprobadas en mensajes de plantilla.

Vistas previas de las plantillas

Puedes generar vistas previas del texto de las plantillas de autenticación en varios idiomas que incluyan o excluyan la cadena de la recomendación de seguridad y la cadena de la caducidad del código con el extremo Cuenta de WhatsApp Business > Vistas previas de plantillas de mensajes.

Sintaxis de la solicitud

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

Parámetros de la cadena de consulta

Marcador de posición Descripción Ejemplo de valor

Marcador de posición	Descripción	Ejemplo de valor
`<LANGUAGE>` Lista separada por comas	Opcional. Lista separada por comas de los códigos de idioma y configuración regional de las versiones de idioma que quieres que se devuelvan. Si se omite, se devolverán las versiones de todos los idiomas admitidos.	`en_US,es_ES`
`<ADD_SECURITY_RECOMMENDATION>` Booleano	Opcional. Se establece en `true` si quieres que se incluya la cadena del cuerpo de la recomendación de seguridad en la respuesta. Si se omite, la cadena de la recomendación de seguridad no se incluirá.	`true`
`<CODE_EXPIRATION_MINUTES>` Entero de 64 bits	Opcional. Se establece en un entero si quieres que se incluya la cadena del pie de página de la caducidad del código en la respuesta. Si se omite, la cadena del pie de página de la caducidad del código no se incluirá. El valor indica el número de minutos que faltan hasta que el código caduque. Mínimo `1`, máximo `90`.	`10`
`<BUTTON_TYPES>` Lista de cadenas separadas por comas	Obligatorio. Lista de cadenas separadas por comas que indica el tipo de botón. Si se incluye, la respuesta incluirá el texto de cada botón en la respuesta. En el caso de las plantillas de autenticación, este valor debe ser `OTP`.	`OTP`

<LANGUAGE>

Lista separada por comas

Opcional.

Lista separada por comas de los códigos de idioma y configuración regional de las versiones de idioma que quieres que se devuelvan.

Si se omite, se devolverán las versiones de todos los idiomas admitidos.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Booleano

Opcional.

Se establece en true si quieres que se incluya la cadena del cuerpo de la recomendación de seguridad en la respuesta.

Si se omite, la cadena de la recomendación de seguridad no se incluirá.

true

<CODE_EXPIRATION_MINUTES>

Entero de 64 bits

Opcional.

Se establece en un entero si quieres que se incluya la cadena del pie de página de la caducidad del código en la respuesta.

Si se omite, la cadena del pie de página de la caducidad del código no se incluirá.

El valor indica el número de minutos que faltan hasta que el código caduque.

Mínimo 1, máximo 90.

10

<BUTTON_TYPES>

Lista de cadenas separadas por comas

Obligatorio.

Lista de cadenas separadas por comas que indica el tipo de botón.

Si se incluye, la respuesta incluirá el texto de cada botón en la respuesta.

En el caso de las plantillas de autenticación, este valor debe ser OTP.

OTP

Ejemplo de solicitud

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Administración masiva

Usa el extremo Cuenta de WhatsApp Business > Insertar plantillas de mensajes para actualizar o crear plantillas de autenticación de forma masiva en varios idiomas que incluyan o excluyan las advertencias opcionales de seguridad y caducidad.

Si una plantilla ya existe con un nombre y un idioma coincidentes, se actualizará con el contenido de la solicitud; de lo contrario, se creará una nueva plantilla.

Sintaxis de la solicitud

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Cuerpo de la solicitud POST

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

Propiedades

Se admiten todas las propiedades de creación de plantillas excepto las siguientes:

La propiedad language no se admite. En su lugar, usa languages y establece el valor en una matriz de cadenas de códigos de idioma y configuración regional. Por ejemplo: ["en_US","es_ES","fr"].
La propiedad text no se admite.
La propiedad autofill_text no se admite.

Ejemplo de solicitud para copiar código

Este ejemplo crea tres plantillas de autenticación en inglés, español y francés con botones para copiar el código. Cada plantilla se denomina “authentication_code_copy_code_button” e incluye la recomendación de seguridad y la hora de caducidad.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Ejemplo de solicitud para rellenar automáticamente con un toque

Este ejemplo (1) actualiza una plantilla existente con el nombre “authentication_code_autofill_button” y el idioma “en_US” y (2) crea dos nuevas plantillas de autenticación en español y francés con botones para rellenar automáticamente con un toque. Las dos plantillas recién creadas se denominan “authentication_code_autofill_button” e incluyen la recomendación de seguridad y la hora de caducidad.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

Ejemplo de respuesta

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

Aplicación de ejemplo

Consulta nuestra aplicación de ejemplo de contraseña de un solo uso (OTP) de WhatsApp para Android en GitHub. La aplicación de ejemplo ofrece una demostración de cómo enviar y recibir contraseñas y códigos de un solo uso mediante la API, cómo integrar los botones de relleno automático con un toque y de copia de código, cómo crear plantillas y cómo poner en marcha un servidor de ejemplo.

Más información

Cuenta empresarial oficial: es posible que quieras solicitar el estado de la cuenta empresarial oficial para generar confianza a los usuarios, lo que reduce la probabilidad de que ignoren tus mensajes.
Webhooks para confirmaciones de lectura: te recomendamos que te suscribas al campo de webhooks de mensajes para que recibas notificaciones cuando un usuario reciba y lea la plantilla de autenticación con un botón de contraseña de un solo uso. Consulta Webhooks para la API de nube o Webhooks para la API local.