API de administración de WhatsApp Business

Plantillas de autenticación

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

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

Las plantillas de autenticación constan de lo siguiente:

Texto predefinido fijo: <VERIFICATION_CODE> es tu código de verificación.
Un descargo de responsabilidad de seguridad opcional: Por tu propia seguridad, no compartas este código.
Una advertencia de caducidad opcional: Este código caduca en <NUM_MINUTES> minutos.
Un botón de autocompletar con un solo toque, un botón para copiar código o ningún botón si se usa la opción sin toque.

Los botones de autocompletar con un solo toque son la solución recomendada, ya que ofrecen la mejor experiencia de usuario. Sin embargo, por el momento, Android no admite estos botones. Por este motivo, es necesario hacer más cambios en el código de tu app.

Consulta Normas adicionales para obtener información sobre cuándo se debe utilizar una plantilla de autenticación.

Plantillas de autenticación con función de autocompletar con un solo toque

Las plantillas de autenticación incluyen un botón de autocompletar con un solo toque.

Cuando un usuario de WhatsApp toca este botón, el cliente de WhatsApp habilita una actividad que abre tu app y le entrega la contraseña o el código.

Consulta Plantillas de autenticación con función de autocompletar con un solo toque para aprender a usarlas.

Plantillas de autenticación con función de copiar código

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

Cuando un usuario toca el botón para copiar código, el cliente de WhatsApp copia la contraseña o el código en el portapapeles del dispositivo. Luego, el usuario puede cambiar manualmente a tu app y pegar la contraseña o el código.

Consulta Plantillas de autenticación con función de copiar código para aprender a usarlas.

Plantillas de autenticación con función sin toque

Las plantillas de autenticación con función sin toque permiten a los usuarios recibir códigos o contraseñas de un solo uso a través de WhatsApp, sin tener que abandonar tu app.

Cuando un usuario de tu app solicita un código o una contraseña y la entregas usando una plantilla de autenticación con función sin toque, el cliente de WhatsApp transmite la contraseña o el código incluidos y, luego, tu app puede capturarlos con un receptor de transmisión.

Consulta Plantillas de autenticación con función sin toque para aprender a usarlas.

Prácticas recomendadas

Confirma el número de teléfono de WhatsApp del usuario antes de enviar el código o la contraseña de un solo uso a ese número.
Deja claro al usuario que el código o la contraseña se enviarán a su número de teléfono de WhatsApp, sobre todo, si ofreces varias maneras para que el usuario reciba el código o la contraseña. Consulta Conseguir que el usuario acepte recibir mensajes para obtener más consejos.
Cuando el usuario pegue el código o la contraseña en tu app o tu app los reciba como parte del proceso de botón de autocompletar con un solo toque, deja claro al usuario que tu app los recibió.

Consulta también Mejores prácticas recomendadas para autenticar usuarios mediante WhatsApp.

Tiempo de duración

Si no podemos entregar un mensaje a un usuario de WhatsApp, seguiremos tratando de entregarlo durante un período de tiempo conocido como "tiempo de duración".

De manera predeterminada, los mensajes tienen un tiempo de duración de 30 días, pero las plantillas de autenticación recién creadas tienen un tiempo de duración predeterminado de 10 minutos.

Si no podemos entregar una plantilla de autenticación en un plazo determinado y se supera el tiempo de duración, dejaremos de intentarlo y omitiremos el mensaje. Si el tiempo transcurrido tras la solicitud de envío de mensaje de plantilla de autenticación supera el tiempo de duración y no recibes ningún webhook, asumiremos que se omitió.

Para anular el tiempo de duración predeterminado 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 preexistentes creadas antes de que esta funcionalidad estuviera disponible tienen un tiempo de duración de 30 días. Si lo deseas, puedes configurar la propiedad message_send_ttl_seconds para editar una plantilla preexistente y anular su tiempo de duración.

También puedes configurar la propiedad message_send_ttl_seconds de una plantilla de autenticación en -1, lo cual establecerá su tiempo de duración en 30 días.

Te invitamos a fijar un tiempo de duración (de preferencia, igual o inferior a tu tiempo de vencimiento de código) para todas tus plantillas de autenticación a fin de asegurarte de que los clientes solo reciban un mensaje cuando un código aún pueda utilizarse.

Ten en cuenta que podría existir una pequeña demora en la entrega del webhook del mensaje fallido, por lo que tal vez te convenga crear un pequeño búfer si se prevé una caída.

Enviar mensajes de la plantilla de autenticación

Usa la API de la nube o de instalaciones locales para enviar plantillas de autenticación aprobadas en un mensaje de plantilla.

Vista previa de plantillas

Puedes generar vistas previas del texto de la plantilla de autenticación en diferentes idiomas, que incluyen o excluyen la cadena de recomendación de seguridad y la cadena de vencimiento del código con el punto de conexión 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 Valor de ejemplo

Marcador de posición	Descripción	Valor de ejemplo
`<LANGUAGE>` Lista separada por comas	Opcional. Lista separada por comas de códigos de idioma y configuración regional de las versiones de idioma que quieres que se devuelvan. Si se omite, se devolverán todas las versiones de idiomas compatibles.	`en_US,es_ES`
`<ADD_SECURITY_RECOMMENDATION>` Booleano	Opcional. Configúralo en `true` si quieres que la cadena del texto de recomendación de seguridad se incluya en la respuesta. Si se omite, la cadena de recomendación de seguridad no se incluirá.	`true`
`<CODE_EXPIRATION_MINUTES>` Int64	Opcional. Configúralo como entero si quieres que la cadena del pie de página del código de vencimiento se incluya en la respuesta. Si se omite, la cadena del pie de página del código de vencimiento no se incluirá. El valor indica la cantidad de minutos que faltan para que venza el código. Mínimo `1`, máximo `90`.	`10`
`<BUTTON_TYPES>` Lista de cadenas separada por comas	Obligatorio. Lista de cadenas separada por comas que indica el tipo de botón. Si se incluye, la respuesta contendrá el texto de cada botón de 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 códigos de idioma y configuración regional de las versiones de idioma que quieres que se devuelvan.

Si se omite, se devolverán todas las versiones de idiomas compatibles.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Booleano

Opcional.

Configúralo en true si quieres que la cadena del texto de recomendación de seguridad se incluya en la respuesta.

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

true

<CODE_EXPIRATION_MINUTES>

Int64

Opcional.

Configúralo como entero si quieres que la cadena del pie de página del código de vencimiento se incluya en la respuesta.

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

El valor indica la cantidad de minutos que faltan para que venza el código.

Mínimo 1, máximo 90.

10

<BUTTON_TYPES>

Lista de cadenas separada por comas

Obligatorio.

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

Si se incluye, la respuesta contendrá el texto de cada botón de 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 punto de conexión Cuenta de WhatsApp Business > Actualizar e insertar plantillas de mensajes para actualizar o crear en forma masiva plantillas de autenticación en varios idiomas que incluyen o excluyen advertencias de seguridad y vencimiento opcionales.

Si ya existe una plantilla con el mismo idioma y nombre, la plantilla 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 publicación

{
  "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

Todas las propiedades de creación de plantillas son compatibles, con estas excepciones:

La propiedad language no es compatible. En su lugar, usa languages y configura su valor en una matriz de cadenas de códigos de idioma y configuraciones regionales. Por ejemplo: ["en_US","es_ES","fr"]
La propiedad text no es compatible.
La propiedad autofill_text no es compatible.

Ejemplo de solicitud para copiar código

En este ejemplo, se crean tres plantillas de autenticación en inglés, español y francés con botones de código de copia. Cada plantilla recibe el nombre "authentication_code_copy_code_button" e incluye la recomendación de seguridad y la hora de vencimiento.

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 de autocompletar con un solo toque

En este ejemplo, (1) se actualiza una plantilla existente con el nombre "authentication_code_autofill_button" y el idioma "en_US" y (2) se crean dos plantillas de autenticación nuevas en español y francés con botones de autocompletar con un solo toque. Las dos plantillas recién creadas reciben el nombre de "authentication_code_autofill_button" e incluyen la recomendación de seguridad y la hora de vencimiento.

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"
    }
  ]
}

App de ejemplo

Consulta nuestra app de ejemplo de contraseña de un solo uso (OTP) de WhatsApp para Android en Github. La app de ejemplo muestra cómo enviar y recibir códigos y contraseñas de un solo uso mediante la API, cómo integrar los botones de autocompletar con un solo toque y de copia de código, y cómo crear una plantilla y un servidor de muestra.

Más información

Cuenta de empresa oficial: es conveniente solicitar el estado de cuenta de empresa oficial para generar confianza entre tus usuarios, lo que reducirá las probabilidades de que descarten o ignoren tus mensajes.
Webhooks para confirmaciones de lectura: te recomendamos suscribirte al campo de webhooks de mensajes para poder recibir una notificación cuando un usuario reciba y lea tu plantilla de autenticación con un botón de OTP. Consulta Webhooks de la API de la nube o Webhooks de la API de instalaciones locales.