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
• Solicitud
• Respuesta

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

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

Objeto components

Objeto parameters

Objeto hsm

Lenguaje

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

Parámetros

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}}.

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

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

Más información

• Enviar mensajes multimedia
• Enviar mensajes multimedia
• Otros tipos de mensaje
• Mensajes