Crear y administrar plantillas

Las plantillas se usan cuando se envían mensajes de plantilla con la API de la nube, alojada por Meta, o la API de instalaciones locales. La API de la nube revisa las plantillas y los parámetros variables mediante aprendizaje automático a fin de conservar la seguridad e integridad de sus servicios. Cuando la API de la nube revisa las plantillas y el texto variable, no se comparte ninguna información con WhatsApp.

Las plantillas se pueden crear usando la API de administración comercial o el administrador de WhatsApp Business. El negocio principal determina la cantidad de plantillas que puede tener una cuenta de WhatsApp Business. Si un negocio principal no está verificado, cada una de sus cuentas de WhatsApp Business tendrá un límite de 250 plantillas. Sin embargo, si el negocio principal se verificó y al menos una de sus cuentas de WhatsApp Business tiene un número de teléfono con un nombre para mostrar aprobado, cada una de las cuentas de WhatsApp Business podrá tener hasta 6.000 plantillas.

Antes de empezar

Necesitarás lo siguiente:

• Un token de acceso de usuario del sistema que esté vinculado al negocio.
• El permiso whatsapp_business_management
• El identificador de la cuenta de WhatsApp Business del negocio.
• El identificador del archivo multimedia del documento, imagen o archivo de video que se usará en una plantilla multimedia. Para obtener un identificador de archivo multimedia, debes cargar el archivo usando la API de subida reanudable.

Limitaciones

• El campo del nombre de la plantilla de mensaje se limita a 512 caracteres.
• El campo del contenido de la plantilla de mensaje se limita a 1024 caracteres.
• Solo se puede editar una plantilla cuando se encuentra en el estado Aprobada, Rechazada o Pausada. Se puede editar una plantilla una vez al día y hasta 10 veces al mes.
• Una cuenta de WhatsApp Business solo puede crear 100 plantillas de mensajes por hora.
• Las plantillas compuestas por 4 o más botones, o un botón de respuesta rápida y uno o más botones de otro tipo, no se pueden ver en los clientes de WhatsApp para computadoras. Por lo tanto, se les 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 agregar una plantilla de mensaje en un idioma específico cuando se crea una plantilla. Estas plantillas se descontarán del límite. Sé coherente al proporcionar traducciones. Para obtener más información, consulta el artículo ¿Por qué aparecen errores con el mensaje "structure unavailable" en la devolución de llamada? del servicio de ayuda.

Crear plantillas

Para crear una plantilla, usa una solicitud POST al punto de conexión Cuenta de WhatsApp Business > Plantillas de mensajes.

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 alguna de las siguientes categorías. Las categorías inciden en los precios, y la categoría que designes se validará cuando se cree la plantilla.

• AUTHENTICATION
• MARKETING
• UTILITY

Consulta nuestro documento Categorización de plantillas para determinar qué categoría debes usar al crear plantillas.

Componentes de plantillas

Las plantillas se componen de diferentes tipos de texto, contenido multimedia y componentes interactivos según las necesidades de la empresa. Consulta el documento Componentes de plantillas para ver una lista de todos los posibles componentes y sus requisitos. También se incluyen muestras y ejemplos de consultas.

Al crear una plantilla, define sus componentes asignando una matriz de objetos de componentes a la propiedad "components" del cuerpo de la solicitud.

Por ejemplo, aquí hay una matriz que contiene un componente de cuerpo de texto con dos variables y valores de muestra, un componente 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 plantillas para hallar una lista de todos los posibles componentes y sus requisitos, así como muestras y ejemplos de consultas.

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

Validación de categorías

Cuando envías una solicitud de creación de plantilla, validamos de inmediato su categoría según nuestras normas de categorización de plantillas.

• Si estamos de acuerdo con la categoría que designaste, creamos la plantilla y configuramos el status como PENDING. Luego, la plantilla pasa a revisión.
• Si no estamos de acuerdo con la categoría que designaste, creamos la plantilla, pero configuramos el status como REJECTED y activamos un webhook de actualización de estado de plantilla de mensaje con el reason configurado como INCORRECT_CATEGORY. Te recomendamos capturar este webhook para identificar las plantillas rechazadas o solicitar el campo rejected_reason en las nuevas plantillas creadas, que contendrán el valor TAG_CONTENT_MISMATCH.

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

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

• Edita los componentes de la plantilla de modo tal que cumplan con nuestras normas.
• Edita la categoría de la plantilla de modo tal que cumpla con nuestras normas.
• Crea una plantilla nueva.

Categorización automática

Puedes incluir la propiedad allow_category_change en tu solicitud para que asignemos automáticamente una categoría en función del contenido de tu plantilla y de nuestras normas de categorización de plantillas. De esta manera, podrás evitar que el estado se configure inmediatamente en REJECTED debido a una categorización incorrecta.

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

Revisión de plantillas

Las plantillas con estado PENDING deben pasar por un proceso de revisión. Revisamos el contenido de todas las plantillas nuevas o recientemente editadas para asegurarnos de que cumplan con nuestras normas y políticas de contenido. En función del 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 la 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 status de esta o lo cambiamos por uno de los siguientes valores:

• APPROVED: la plantilla pasó la revisión y se aprobó, y ahora se puede enviar en mensajes de plantilla.
• PENDING: la plantilla pasó la validación de categoría y está en revisión.
• REJECTED: la plantilla no pasó la validación de categoría o la revisión. Puedes solicitar el campo rejected_reason de la plantilla para conocer el motivo del rechazo.

Consulta la referencia del punto de conexión Plantilla de mensaje de WhatsApp para conocer todos los campos y estados posibles.

Respuesta

Si la operación se realiza correctamente, la API responde con el identificador, el estado y la categoría de la plantilla creada recientemente. Estos son los tres resultados posibles:

• Estamos de acuerdo con la categoría que designaste y la plantilla ahora está en revisión (el status es PENDING).
• No estamos de acuerdo con la categoría que designaste (el status es REJECTED).
• Aprobamos automáticamente la plantilla (el status es APPROVED). Esto solo se aplica a 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, se muestra un ejemplo de solicitud para crear una plantilla de promoción de temporada que consta de los siguientes componentes:

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

Para ver 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 la nube o la API de instalaciones locales para enviar una plantilla en un mensaje de plantilla.

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

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

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

Te invitamos a definir un TTL (de preferencia, igual o inferior al tiempo de vencimiento del 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.

Valores predeterminados, valores mínimos o máximos y tabla de compatibilidad

Cómo personalizar el TTL de tu plantilla

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

El TTL se puede personalizar en incrementos de 1 segundo.

Valores de propiedades message_send_ttl_seconds válidos

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

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

Cuando se supera el TTL: Mensajes omitidos

Se omiten los mensajes que no se pueden entregar dentro del TTL predeterminado o personalizado.

Si no recibes un webhook de mensaje entregado antes de que se supere el TTL, se asume que el mensaje se omitió.

Si envías un mensaje que no se puede entregar, podría producirse un leve retraso antes de recibir el webhook, por lo que te recomendamos incorporar un tiempo de espera breve antes de asumir que el mensaje se omitió.

Prácticas recomendadas referidas a las plantillas de marketing

Botón "Desactivar marketing"

Te recomendamos agregar un botón de respuesta rápida a las plantillas con la categoría MARKETING, lo que permite a los clientes desactivar sus mensajes de marketing de forma más sencilla. Con esto, los usuarios tendrán la opción de desactivar los mensajes de marketing sin tener que bloquear tu negocio. En consecuencia, podrás aumentar más rápidamente el volumen de los mensajes. Consulta este artículo para hallar más información sobre las ventajas de agregar un botón de desactivación a tus plantillas de marketing.

Obtener plantillas

Envía una solicitud GET al punto de conexión Cuenta de Whatsapp Business > Plantillas de mensajes para obtener una lista de 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 cadena de la 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 específicos si incluyes el campo y el valor deseado en tu solicitud. Por ejemplo, incluye status=REJECTED para obtener únicamente 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 la plantilla de mensajes

El espacio de nombres es obligatorio para enviar mensajes mediante plantillas de mensajes.

Para obtener el espacio de nombres de una plantilla, envía una solicitud GET al punto de conexión /{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 el proceso es correcto, se devolverá un objeto JSON con el identificador de la cuenta de WhatsApp Business y el espacio de nombres:

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

Editar plantillas

Para editar una plantilla, envía una solicitud POST al punto de conexión Plantillas de mensajes de WhatsApp. También puedes editar plantillas manualmente usando el panel Administrador de WhatsApp > Herramientas de cuenta > Plantillas de mensajes.

Limitaciones

• Solo se pueden editar las plantillas con el estado APPROVED, REJECTED o PAUSED.
• Solo se puede editar el elemento category o components de una plantilla.
• No se puede editar el elemento category de una plantilla aprobada.
• Se puede editar una plantilla aprobada hasta 10 veces en un plazo de 30 días o una vez en 24 horas. Las plantillas rechazadas o pausadas se pueden editar un número ilimitado de veces.
• Una vez que se edite una plantilla aprobada o en pausa, esta 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

Ejemplo de solicitud (edición de componentes)

Ejemplo de solicitud al cuerpo de una plantilla de texto que incluía contenido tanto de marketing como de utilidades, 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"
        }
      ]
    }
  ]
}'

Ejemplo de solicitud (solo edición de categoría)

Ejemplo de solicitud para cambiar la categoría de la 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 después de una operación exitosa.

{
  "success": true
}

Eliminar plantillas

Utiliza el punto de conexión Cuenta de WhatsApp Business > Plantillas de mensajes para eliminar una plantilla según su nombre o identificador.

Notas

• Si eliminas una plantilla que se envió en un mensaje de plantilla, pero que aún no se entregó (por ejemplo, porque el teléfono del cliente está apagado), el estado de la plantilla se configurará en PENDING_DELETION y trataremos de entregar el mensaje durante 30 días. Pasado ese tiempo, recibirás un error "Structure Unavailable", y el cliente no recibirá el mensaje.
• Los nombres de las plantillas aprobadas que se eliminaron no se pueden volver a usar por 30 días.

Eliminar por nombre

Al eliminar una plantilla por nombre, se eliminan todas las plantillas que coinciden con ese nombre (es decir, también se eliminan las plantillas con el mismo nombre, pero en diferentes idiomas).

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 identificador, incluye en la solicitud el identificador de la plantilla con su nombre. Solo se borrará la plantilla cuyo identificador coincida.

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

Próximos pasos

• Empieza a usar la API de la nube para enviar mensajes