Crear y administrar plantillas

Las plantillas se usan al enviar mensajes de plantilla mediante la API de nube, alojada en Meta, o la API local. La API de nube revisa las plantillas y los parámetros de las variables mediante aprendizaje automático para proteger la seguridad y la integridad de los servicios de la API de nube. Cuando la API de nube revisa las plantillas y el texto de las variables, no se comparte información con WhatsApp.

Las plantillas se pueden crear con la API de administración de WhatsApp Business o el Administrador de WhatsApp Business. El número de plantillas que puede tener una cuenta de WhatsApp Business lo determina su empresa principal. Si una empresa principal no está verificada, cada una de sus cuentas de WhatsApp Business se limita a 250 plantillas. Sin embargo, si la empresa principal está verificada y al menos una de sus cuentas de WhatsApp Business tiene un número de teléfono de empresa con un nombre para mostrar aprobado, cada una de sus cuentas de WhatsApp Business puede tener hasta 6000 plantillas.

Antes de empezar

Necesitarás lo siguiente:

• Un identificador de acceso de usuario del sistema vinculado a la empresa.
• El permiso whatsapp_business_management.
• El identificador de la cuenta de WhatsApp Business de la empresa.
• El identificador de activos multimedia de cualquier documento, imagen o archivo de vídeo que se utilice en una plantilla de contenido multimedia. Para obtener el identificador de activos multimedia, debes subirlos mediante la API de subida reanudable.

Limitaciones

• El campo del nombre de la plantilla de mensaje está limitado a 512 caracteres.
• El campo del contenido de la plantilla de mensaje está limitado a 1024 caracteres.
• Las plantillas solo se pueden editar cuando su estado es Aprobada, Rechazada o En pausa. Las plantillas se pueden editar una vez al día, hasta un máximo de diez veces al mes.
• Las cuentas de WhatsApp Business solo pueden crear 100 plantillas de mensajes por hora.
• Las plantillas compuestas por cuatro o más botones, o un botón de respuesta rápida y uno o varios botones de otro tipo, no se pueden ver en los clientes de ordenador de WhatsApp. Se pedirá a los usuarios de WhatsApp que reciban uno de estos mensajes de plantilla que vean el mensaje en un teléfono.

Localización

Puedes añadir una plantilla de mensaje en un idioma específico al crear una plantilla. Estas plantillas se tienen en cuenta para el límite. Asegúrate de mantener la coherencia al proporcionar traducciones. Para obtener más información, consulta el artículo del Servicio de ayuda ¿Por qué veo errores de “estructura no disponible” en mi devolución de llamada?.

Crear plantillas

Envía una solicitud POST al extremo Cuenta de WhatsApp Business > Plantillas de mensajes para crear una plantilla.

Sintaxis de la solicitud

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Cuerpo de la solicitud POST

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Propiedades del cuerpo

Categorías de plantillas

Las plantillas se deben clasificar en una de las siguientes categorías. Las categorías tienen en cuenta los precios y la categoría que designes se validará al crear la plantilla.

• AUTHENTICATION
• MARKETING
• UTILITY

Consulta nuestro documento Categorización de plantillas para determinar la categoría que usar al crear plantillas.

Componentes de la plantilla

Las plantillas están formadas por varios componentes de texto, de contenido multimedia e interactivos en función de las necesidades de la empresa. Consulta el documento Componentes de las plantillas para obtener una lista de todos los componentes posibles y sus requisitos, así como muestras y consultas de ejemplo.

Al crear una plantilla, debes definir sus componentes; para ello, asigna una matriz de objetos de componentes a la propiedad “components” en el cuerpo de la solicitud.

Por ejemplo, a continuación se muestra una matriz que contiene un componente de cuerpo de texto con dos variables y valores de ejemplo, un componente de botón de número de teléfono y un componente de botón de URL:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Consulta el documento Componentes de las plantillas para obtener una lista de todos los componentes posibles y sus requisitos, así como muestras y consultas de ejemplo.

Ten en cuenta que las plantillas categorizadas como AUTHENTICATION tienen requisitos únicos de componentes. Consulta Plantillas de autenticación.

Validación de la categoría

Al enviar una solicitud de creación de plantillas, validamos inmediatamente su categoría según nuestras normas para la categorización de plantillas.

• Si estamos de acuerdo con la categoría que has designado, creamos la plantilla y establecemos el valor de status en PENDING. A continuación, la plantilla se somete a una revisión.
• Si no estamos de acuerdo con tu designación, creamos la plantilla, pero establecemos el valor de status en REJECTED y activamos un webhook de actualización de estado de plantilla de mensaje con el valor de reason establecido en INCORRECT_CATEGORY. Te recomendamos que escuches este webhook para identificar plantillas rechazadas o solicitar el campo rejected_reason en las plantillas recién creadas, que tendrán el valor TAG_CONTENT_MISMATCH.

En ambos casos, el estado inicial de la plantilla se devuelve como parte de la respuesta de la API.

Si el estado de la plantilla se ha establecido en REJECTED como parte de la validación de la categoría, tienes varias opciones:

• Edita los componentes de la plantilla para que se ajusten a nuestras normas.
• Edita la categoría de la plantilla para que se ajuste a nuestras normas.
• Crea una nueva plantilla.

Categorización automática

Puedes incluir la propiedad allow_category_change en la solicitud para que asignemos automáticamente una categoría en función del contenido de la plantilla y nuestras normas para la categorización de plantillas. Esto puede impedir que el estado de la plantilla se establezca en REJECTED inmediatamente a causa de una categorización incorrecta.

Ten en cuenta que la categorización automática solo se puede usar al crear una plantilla.

Revisión de la plantilla

Las plantillas con el estado PENDING se someterán a una revisión. Revisamos el contenido de cada plantilla recién creada o editada para asegurarnos de que se ajusta a nuestras normas y políticas de contenido. Según el resultado de esta revisión, cambiamos automáticamente el estado a APPROVED o REJECTED, lo que activa un webhook de actualización de estado de plantilla de mensaje.

Estado de la plantilla

En función del resultado de la validación de la categoría y la revisión de la plantilla, establecemos el valor de status de la plantilla en uno de los siguientes valores o lo cambiamos:

• APPROVED: la plantilla ha superado la revisión y se ha aprobado, de modo que ahora se puede enviar en mensajes de plantilla.
• PENDING: la plantilla ha superado la validación de la categoría y se está sometiendo a una revisión.
• REJECTED: la plantilla no ha superado la validación de la categoría o la revisión. Puedes solicitar el campo rejected_reason en la plantilla para obtener el motivo.

Consulta todos los campos y estados posibles en la referencia del extremo Plantilla de mensaje de WhatsApp.

Respuesta

Si la operación se realiza correctamente, la API responde con el identificador, el estado y la categoría de la plantilla recién creada. Hay tres resultados posibles:

• Estamos de acuerdo con la categoría que has designado y ahora la plantilla se está sometiendo a una revisión (status es PENDING).
• No estamos de acuerdo con la categoría que has designado (status es REJECTED).
• Hemos aprobado automáticamente la plantilla (status es APPROVED). Esto solo es posible en el caso de las plantillas de autenticación con botones de contraseña de un solo uso.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Propiedades de la respuesta

Ejemplo de solicitud

A continuación, te mostramos un ejemplo de solicitud para crear una plantilla de promoción estacional compuesta por los siguientes componentes:

• un encabezado de texto
• un cuerpo de texto
• un pie de página
• dos botones de respuesta rápida

Para obtener ejemplos adicionales, consulta Ejemplos de solicitudes.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Ejemplo de respuesta

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Enviar plantillas

Usa la API de nube o la API local para enviar una plantilla en un mensaje de plantilla.

Duración (TTL): personalización, valores predeterminados, valores mínimos y máximos y compatibilidad

Si no podemos entregar un mensaje a un usuario de WhatsApp, volveremos a intentar la entrega durante un periodo de tiempo que se conoce como duración (TTL) o periodo de validez del mensaje.

Puedes personalizar el valor de TTL predeterminado de las plantillas de autenticación, utilidad y marketing.

Te recomendamos que establezcas un valor de TTL 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.

Tabla de valores predeterminados, mínimos y máximos y compatibilidad

Cómo personalizar el valor de TTL de una plantilla

Para establecer un valor de TTL personalizado en una plantilla de autenticación, utilidad o marketing, incluye y establece el valor de la propiedad message_send_ttl_seconds en la llamada POST /<PHONE_NUMBER_ID>/messages.

El valor de TTL se puede personalizar en incrementos de un segundo.

Valores de la propiedad message_send_ttl_seconds válidos

• Plantillas de autenticación: de 30 a 900 segundos (de 30 segundos a 15 minutos).
• Plantillas de utilidad: de 30 a 43200 segundos (de 30 segundos a 12 horas).
• Plantillas de marketing: de 43200 a 2592000 segundos (de 12 horas a 30 días).

Para las plantillas de autenticación y utilidad, puedes establecer el valor de la propiedad message_send_ttl_seconds en -1, que establecerá un valor de TTL personalizado de 30 días.

Cuando se supera el valor de TTL: mensajes eliminados

Los mensajes que no se han podido entregar durante el periodo de TTL predeterminado o personalizado se eliminan.

Si no recibes un webhook de mensaje entregado antes de que se supere el valor de TTL, debes asumir que el mensaje se ha eliminado.

Si envías un mensaje y se produce un error en la entrega, podría producirse un breve retraso antes de recibir el webhook, por lo que es posible que quieras crear en un pequeño búfer antes de asumir que el mensaje se ha eliminado.

Prácticas recomendadas para plantillas de marketing

Botón de desactivación de marketing

Te recomendamos añadir un botón de respuesta rápida a las plantillas categorizadas como MARKETING que permita a los clientes desactivar los mensajes de marketing con facilidad. Así, los clientes podrán desactivar los mensajes de marketing que envíes sin tener que bloquear a la empresa. De esta forma, es posible que puedas escalar el volumen de mensajes más rápidamente. Consulta este artículo para obtener más detalles sobre las ventajas de añadir un botón de desactivación en las plantillas de marketing.

Obtener plantillas

Envía una solicitud GET al extremo Cuenta de WhatsApp Business > Plantillas de mensajes para obtener una lista de las plantillas que pertenecen a una cuenta de WhatsApp Business.

Sintaxis de la solicitud

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Parámetros de la cadena de consulta

Ejemplo de solicitud

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Ejemplo de solicitud (plantillas rechazadas)

Solo puedes devolver plantillas con valores de campo concretos si incluyes el campo y el valor deseado en la solicitud. Por ejemplo, puedes incluir status=REJECTED para obtener solo las plantillas rechazadas.

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Recuperar el espacio de nombres de una plantilla

El espacio de nombres de la plantilla de mensaje se necesita para enviar mensajes con las plantillas de mensajes.

Para obtener el espacio de nombres de una plantilla, envía una solicitud GET al extremo /{whatsapp-business-account-ID} e incluye el campo message_template_namespace.

Ejemplo de solicitud

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

Si la solicitud se realiza correctamente, se devuelve un objeto JSON con el espacio de nombres y el identificador de la cuenta de WhatsApp Business:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Editar plantillas

Envía una solicitud POST al extremo Plantilla de mensaje de WhatsApp para editar una plantilla. También puedes editar una plantilla manualmente mediante la ventana disponible en Administrador de WhatsApp > Herramientas de la cuenta > Plantillas de mensajes.

Limitaciones

• Solo se pueden editar las plantillas con uno de los siguientes estados: APPROVED, REJECTED o PAUSED.
• Solo puedes editar las propiedades category o components de una plantilla.
• No puedes editar la propiedad category de una plantilla aprobada.
• Las plantillas aprobadas se pueden editar un máximo de diez veces en un periodo de 30 días o una vez cada 24 horas. Las plantillas rechazadas o en pausa se pueden editar un número ilimitado de veces.
• Después de editar una plantilla aprobada o en pausa, se aprobará automáticamente a menos que no supere la revisión.

Sintaxis de la solicitud

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Cuerpo de la solicitud POST

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Propiedades

Solicitud de ejemplo (editar los componentes)

Solicitud de ejemplo del texto del cuerpo de una plantilla con contenido de marketing y utilidad para que solo incluya contenido de marketing.

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Solicitud de ejemplo (editar solo la categoría)

Solicitud de ejemplo para cambiar la categoría de una plantilla de UTILITY a MARKETING.

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Ejemplo de respuesta

Ejemplo de respuesta una vez realizada correctamente la solicitud.

{
  "success": true
}

Eliminar plantillas

Usa el extremo Cuenta de WhatsApp Business > Plantillas de mensajes para eliminar una plantilla por su nombre o identificador.

Notas

• Si eliminas una plantilla que se ha enviado en un mensaje de plantilla pero que todavía no se ha entregado (por ejemplo, en caso de que el teléfono del cliente esté apagado), el estado de la plantilla se establecerá en PENDING_DELETION e intentaremos entregar el mensaje durante 30 días. En cuanto pase ese periodo de tiempo, recibirás el error “Estructura no disponible” y el cliente no recibirá el mensaje.
• Los nombres de una plantilla aprobada que se ha eliminado no se pueden volver a usar hasta pasados 30 días.

Eliminar por nombre

Eliminar una plantilla por su nombre elimina todas las plantillas que coincidan con ese nombre (esto quiere decir que las plantillas con un mismo nombre pero en idiomas distintos también se eliminarán).

Sintaxis de la solicitud

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Ejemplo de solicitud

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "success": true
}

Eliminar por identificador

Para eliminar una plantilla por su identificador, incluye el identificador de la plantilla junto con su nombre en la solicitud. Solo se eliminarán las plantillas cuyos identificadores de plantilla coincidan.

Sintaxis de la solicitud

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Ejemplo de solicitud

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "success": true
}

Más información

Siguientes pasos

• Introducción a la API de nube para empezar a enviar mensajes