Enviar plantillas de mensajes

/v1/messages

Usa el punto de conexión messages para enviar plantillas de mensaje a los clientes. Las plantillas de mensaje se pueden crear en el administrador de WhatsApp. Consulta Crear plantillas de mensajes.

Este documento abarca lo siguiente:

Requisitos previos

Asegúrate de haber completado las acciones que se describen en la sección de requisitos previos de la documentación sobre mensajes.

Solicitud

Recomendación: Usa el tipo de plantilla de mensaje template.

POST /v1/messages
{
  "to": "recipient_wa_id",
  "ttl": "P4D" | "3600" | 3600, # The "ttl" field will be deprecated in v2.35.
  "type": "template",
  "template": {
        "namespace": "your-namespace",
        "name": "your-template-name",
        "language": {
            "code": "your-language-and-locale-code",
            "policy": "deterministic"
        },
        "components": [{
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "your-text-string"
                },
                {
                    "type": "currency",
                    "currency": {
                        "fallback_value": "$100.99",
                        "code": "USD",
                        "amount_1000": 100990
                    }
                },
                {
                    "type": "date_time",
                    "date_time" : {
                        "fallback_value": "February 25, 1977",
                        "day_of_week": 5,
                        "day_of_month": 25,
                        "year": 1977,
                        "month": 2,
                        "hour": 15,
                        "minute": 33
                    }
                },
                {
                "type": "date_time",
                    "date_time" : {
                    "fallback_value": "February 25, 1977",
                    "timestamp": 1485470276
                    }
                }
            ]
        }]
    }
}

Usar el tipo de plantilla de mensaje hsm

El parámetro hsm contiene un par de elementos namespace y element_name que identifican una plantilla y los valores que se aplicarán a las variables de dicha plantilla. La retirada del tipo de plantilla de mensaje hsm está planeada para una versión futura.

El código siguiente proporciona un ejemplo de envío de una plantilla de mensaje. En este ejemplo, se muestra el uso del nombre del elemento purchase_with_credit_card con el espacio de nombres cdb2df51_9816_c754_c5a4_64cdabdcad3e: los parámetros namespace y element_name deben coincidir, o el mensaje no se enviará.

POST /v1/messages
  
{
    "to": "whatsapp_id",
    "ttl": "P1D" | "86400" | 86400,
    "type": "hsm",
  
    "hsm": { 
        "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
        "element_name": "purchase_with_credit_card", 
        "language": {
            "policy": "deterministic",
            "code": "en_US"
        },
        "localizable_params": [ 
            { "default": "$10" }, 
            { "default": "1234" } 
        ]
    }  
}

El mensaje resultante que recibirá el cliente tiene un aspecto similar al siguiente:

Realizaste una compra de $10 con una tarjeta de crédito que termina en 1234.

Como puedes ver al observar los parámetros localizables y el mensaje que recibió el cliente, la plantilla usa el valor predeterminado 10 como monto de la compra y el valor predeterminado 1234 como los últimos números de la cuenta.

Parámetros

Nombre Descripción

type

Obligatorio para las plantillas de mensaje.

El tipo de mensaje que se envía.
Opciones:

  • text: valor predeterminado
  • image
  • audio
  • document
  • template: se usa para enviar un mensaje de plantilla con contenido multimedia
  • hsm

to

Obligatorio.

El identificador de WhatsApp a quien se envía el mensaje.

ttl
Quedará obsoleto en la v2.35

Opcional.

A partir de la v2.21.3: Duración del tiempo de vida (TTL).
Valor predeterminado: 7 días
Otras opciones: Las duraciones mínima y máxima compatibles oscilan entre 1 y 30 días (ambos valores incluidos).


Acepta una cadena con el formato de duración ISO-8601 o simplemente en segundos. Las duraciones deben especificarse con un múltiplo exacto de días. Cualquier otro valor intermedio se redondeará automáticamente al día más próximo. Consulta la sesión del objeto ttl para obtener más información.

recipient_type

Opcional.

Valor:individual

template

Obligatorio para los mensajes template.

Contiene toda la información de la plantilla.

hsm

Obligatorio para las plantillas de mensaje.

El elemento de contención del contenido del mensaje. Indica que el mensaje está altamente estructurado. Los parámetros que contiene proporcionan la estructura.

Objeto ttl

Empezando con la v2.21.3, el objeto ttl permite establecer una duración de caducidad para los mensajes (es decir, el tiempo de vida). Las empresas pueden aprovechar esto para asegurarse de que los mensajes se entreguen en un plazo determinado. Actualmente, solo se admiten tiempos de vida para las plantillas de mensajes.

Si el mensaje no se entrega al cliente antes del período de expiración, caducará y no se entregará. Recibirás una notificación de devolución de llamada failed con un código de error 410 cuando caduque un mensaje enviado (como en el ejemplo siguiente), pero no hay ningún recibo de entrega porque los mensajes que caduquen no se entregan.

El parámetro ttl quedará obsoleto con la v2.35 en 2021. Debes estar preparado para dejar de usar este parámetro y así evitar cualquier error inesperado en su funcionamiento después del lanzamiento de la v2.35.

Ejemplo de una notificación de devolución de llamada failed

"statuses": [
    {
        "errors": [
            {
                "code": 410,
                "title": "Message expired"
            }
        ],
        "id": "gBGGFmkiWVVPAgmurVK0Oo_-o60",
        "recipient_id": "16695551234",
        "status": "failed",
        "timestamp": "1538520126"
    }
]

Objeto template

NombreDescripción

namespace

Obligatorio.

Espacio de nombres de la plantilla.


A partir de la versión v2.27.8, este debe ser el espacio de nombres asociado a la cuenta de WhatsApp Business que posee el número de teléfono correspondiente al cliente de la API de WhatsApp Business actual, o el mensaje no se enviará.

name

Obligatorio.

Nombre de la plantilla.

language

Obligatorio.

Especifica el lenguaje en que se puede representar la plantilla. Solo funciona la política de lenguaje deterministic con los mensajes de plantilla multimedia. Consulta la sección Idioma para obtener más información.

components

Opcional.

Matriz que incluye los parámetros del mensaje.

Objeto components

NombreDescripción

type

Obligatorio.

Describe el tipo component
Valores:header, body, footer

parameters

Opcional.

Matriz que incluye el contenido del mensaje.

Objeto parameters

NombreDescripción

type

Obligatorio.

Describe el tipo parameter.
Valores:text, currency, date_time, image, document, video


Los tipos de contenido multimedia (image, document y video) siguen el mismo formato que los que se usan en mensajes multimedia estándar; consulta la documentación sobre contenido multimedia para obtener más información. Actualmente, las plantillas de mensajes multimedia solo admiten documentos PDF.


Para obtener más información sobre currency y date_time, consulta la sección sobre parámetros localizables. Los parámetros currency y date_time para mensajes de template usan fallback_value en lugar de default. Consulta el ejemplo anterior de solicitud para ver un modelo.

Objeto hsm

La retirada del objeto hsm está planeada para una versión futura.

Nombre Descripción

namespace

Obligatorio.

Espacio de nombres que se utilizará. A partir de la v2.2.7, si el espacio de nombres no coincide con element_name, no se podrá enviar el mensaje.

element_name

Obligatorio.

Nombre del elemento que indica la plantilla que se utilizará en el espacio de nombres. A partir de la v2.2.7, si el espacio de nombres no coincide con element_name, no se podrá enviar el mensaje.

language

Obligatorio.

Permite la especificación de un lenguaje "deterministic" o "fallback". Consulta la sección Lenguaje para obtener más información.


Campo utilizado que ofrece una opción fallback, pero quedó obsoleto con v2.27.8.

localizable_params

Obligatorio.

Este campo es una matriz de valores que se aplicarán a las variables en la plantilla. Consulta la sección Parámetros localizables para obtener más información.

Lenguaje

El parámetro language define la política de lenguaje para una plantilla de mensaje.

Parámetros

Nombre Descripción

policy

Obligatorio.

Predeterminada:deterministic
política de lenguaje que debe seguir el mensaje. La opción fallback quedará obsoleta con la v2.27.8.

code

Obligatorio.

El código de idioma o configuración regional que se usará. Admite los formatos language y language_locale (por ejemplo, en y en_US).

Paquetes de idioma

Las plantillas de mensaje se almacenan en forma de paquetes de idioma. Un paquete de idioma es básicamente un conjunto de elementos de plantilla de mensajes para un idioma o una configuración regional en particular. Si una empresa contiene, como mínimo, una traducción de un idioma o configuración regional, se considerará que lo admite y se creará un paquete para el idioma o la configuración regional en cuestión.

Un espacio de nombres de plantilla de mensaje es un paquete de paquetes de idioma para una empresa en específico.

Paquetes de idioma

La opción de la política de idioma predeterminada es deterministic; antes ofrecíamos la opción fallback, pero quedó obsoleta.

Si una plantilla de mensaje se envía con el campo language: policy definido en deterministic, WhatsApp entrega la plantilla de mensaje en el idioma y la configuración regional que se solicitó. El dispositivo solicitará al servidor un paquete de ese idioma específico.

A continuación, figura una descripción del proceso:

Paso 1: Envías una plantilla de mensaje como la que se indica a continuación:

{ 
  "namespace": "business_a_namespace" 
  "element_name": "hello_world", 
  "language": {
      "policy": "deterministic",
      "code": "en"
  }
  "localizable_params": [ 
      { "default": "1234" }
  ], 
}

Paso 2: Cuando este mensaje se entregue al dispositivo, el dispositivo hará lo siguiente:

  • Verificación de política/código: Si "policy": "deterministic" y "code": "en": ¿existe un paquete en almacenado en caché en el dispositivo?
    • Si la respuesta es afirmativa, procede a Verificación del elemento.
    • De lo contrario, ¿se puede encontrar el paquete en en el servidor?
      • Si la respuesta es afirmativa, actualiza la caché local y procede a Verificación del elemento.
      • De lo contrario, registra el error. El servidor devolverá un error structure_unavailable mediante un webhook y no se representará ningún mensaje en el dispositivo.

  • Verificación del elemento: ¿existe el elemento "element": "hello_world"?
    • Si la respuesta es afirmativa, desempaqueta los parámetros y representa el mensaje en el dispositivo.
    • De lo contrario, haz lo siguiente:
      • Si el paquete de idioma procede de la caché local, descarga el paquete en más reciente del servidor y repite la Verificación del elemento.
      • Si el paquete de idioma se descargó recientemente del servidor, registra el error. El servidor devolverá un error structure_unavailable mediante un webhook y no se mostrará ningún mensaje en el dispositivo.

La configuración de idioma o configuración regional del dispositivo se ignoran completamente.

Un problema que puede ocurrir al usar la política deterministic es la inexistencia de lo que se está solicitando. Asegúrate de comprobar que:

  • El espacio de nombres es correcto,
  • El nombre del elemento es correcto,
  • La traducción del idioma o la configuración regional existen para el elemento, y
  • Que el número de parámetros que se enviaron coincide con lo que se especifica en la plantilla de mensajes.

Parámetros localizables

Cuando se envía una plantilla de mensaje, el objeto hsm es obligatorio. Para definir plantillas de mensaje, se debe especificar un namespace y un par de element_name que identifiquen la plantilla. Las plantillas tienen parámetros que se incorporarán de manera dinámica al mensaje. Para el ejemplo que se utiliza en este documento, la plantilla de mensaje tiene el aspecto siguiente:

"You made a purchase for {{1}} using a credit card ending in {{2}}."

Para "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e" con "element_name": "purchase_with_credit_card", el primer valor que enumeras reemplaza la variable {{1}} en el mensaje de plantilla, y el segundo reemplaza la variable {{2}}.

El número de parámetros que se pasan a la carga útil debe coincidir con el número de parámetros del objeto hsm. De lo contrario, se te devolverá la llamada y se te informará que hubo un problema con la plantilla del mensaje.

Algunos de estos parámetros (por ejemplo, date_time o currency) son localizables para que se muestren adecuadamente según el idioma y las preferencias de localización del cliente. Si el dispositivo no localiza correctamente un parámetro, recurrirá al valor proporcionado como "default".

Las opciones de localizable_params se muestran en la tabla siguiente. Para obtener más información sobre los parámetros localizables, lee la documentación de Localización.

Parámetros

NombreDescripción

default

Tipo: cadena

Obligatorio.

El texto predeterminado si no funciona la localización.

currency

Tipo: objeto currency

Opcional.

Si se utiliza el objeto currency, este contiene los parámetros obligatorios currency_code y amount_1000.

date_time

Tipo: objeto date_time

Opcional.

Si se utiliza el objeto date_time, la definición adicional de fecha y hora será obligatorio. Consulta el ejemplo siguiente de dos de las opciones.

Todos los parámetros de localización deben tener un valor predeterminado. El valor predeterminado es todo lo que se necesita para especificar texto.

No obstante, para especificar la moneda y la fecha, además del valor predeterminado, si corresponde, usa los objetos currency y date_time, como se muestra a continuación. Esto permite al cliente intentar localizar estos datos de la mejor manera posible y recurrir a la opción default solo si no los puede localizar.

Se recomienda utilizar los objetos currency y date_time para los parámetros adecuados a fin de proporcionar una experiencia óptima a tus clientes.

A continuación, se ofrece un ejemplo completo que demuestra el uso de todos los tipos localizados que actualmente se admiten:

{
  "to": "19195551112",
  "type": "hsm",
  "recipient_type": "individual",
  
  "hsm": {
    "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
    "element_name": "four_lparam_demo",
    "language": {
            "policy": "deterministic",
            "code": "en_US"
        }
  
    "localizable_params": [
      {
        "default": "just a string"
      },
      {
        "default": "$100.99",
        "currency": {
          "currency_code": "USD",
          "amount_1000": 100990
        }
      },
      {
        "default": "February 25, 1977",
        "date_time": {
          "component": {
            "day_of_week": 5,
            "day_of_month": 25,
            "year": 1977,
            "month": 2,
            "hour": 15,
            "minute": 33
          }
        }
      },
      {
        "default": "January 26, 2017",
        "date_time": {
          "unix_epoch": {
            "timestamp": 1485470276
          }
        }
      }
    ]
  
  }
}

Respuesta

Una respuesta correcta incluye un objeto messages con un valor de id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

Una respuesta errónea contiene un objeto incorrecto con una cadena incorrecta, un código de error e información adicional. Para obtener más información, consulta Códigos de error y de estado.

Preguntas frecuentes

¡Por supuesto! Comunícate con tu representante de WhatsApp y solicítala. Consulta la documentación sobre la creación de plantillas de mensaje para obtener la información que necesitaremos de tu parte para procesar la creación de tu plantilla de mensaje.