Saltar al contenido principal

1. Información general

Para ayudar a las empresas a tener un mayor control y optimizar su gasto en mensajes de marketing de WhatsApp, YCloud admite las nuevas capacidades de precios introducidas por Meta para la API de Marketing Messages en 2026, incluidas Max Price y la Reach Estimation Tool. Con la API de YCloud, las empresas pueden establecer el precio máximo que están dispuestas a pagar por cada mensaje de marketing de WhatsApp entregado y ajustar su estrategia de precios según el coste de la campaña y los objetivos de entrega. Cuando se establece un Max Price, Meta cobra ese precio o uno inferior por cada mensaje entregado. Antes de enviar, las empresas también pueden usar la Reach Estimation Tool para conocer el volumen de entrega y el coste estimados con diferentes niveles de Max Price. Esta guía explica cómo utilizar la API de YCloud para:
  1. Establecer un Max Price y un Country multiplier en una plantilla de mensaje de marketing
  2. Aplicar opcionalmente un multiplicador por mensaje al enviar un mensaje
  3. Obtener el cobro final a través de los webhooks de estado del mensaje
  4. Estimar el volumen de entrega y el coste a diferentes niveles de Max Price antes de enviar

2. Conceptos clave

2.1 ¿Qué es un Max Price?

Un Max Price es el importe máximo que una empresa está dispuesta a pagar por cada mensaje de marketing de WhatsApp entregado correctamente. Cuando se establece un Max Price, Meta cobra ese precio o uno menor por la entrega. El cobro real no superará el límite de precio configurado. Según el objetivo de una campaña de marketing, una empresa puede establecer su Max Price al mismo nivel, por debajo o por encima de la tarifa publicada de Meta: Un Max Price es un límite de precio, no un cobro fijo. Establecer un Max Price no significa que cada mensaje entregado se cobrará a ese precio. El precio de cada mensaje se calcula dinámicamente y puede ser igual o inferior al Max Price configurado.

2.2 Cómo establecer el Max Price

2.2.1 Establecer el precio máximo en una plantilla Puedes establecer un Max price fijo (maxBid) para una plantilla y configurar diferentes multiplicadores (countryPriceAdjustments.multiplier) para distintos países o regiones. Por ejemplo, supongamos que el maxBid se establece en 0,10 USD, con un multiplicador de 0,8× para la India y un multiplicador de 1,3× para Malasia:
  • Cuando la plantilla se utiliza para enviar un mensaje a la India, el Max price a nivel de plantilla es 0,10 USD × 0,8 = 0,08 USD.
  • Cuando la plantilla se utiliza para enviar un mensaje a Malasia, el Max price a nivel de plantilla es 0,10 USD × 1,3 = 0,13 USD.
  • Cuando la plantilla se envía a cualquier otro país, el Max price a nivel de plantilla es 0,10 USD.
2.2.2 Ajustar el multiplicador al enviar un mensaje de plantilla Al enviar un mensaje utilizando una plantilla con Max Price, puedes aplicar un multiplicador por mensaje mayor que 0 para aumentar o disminuir el Max Price efectivo de un mensaje individual. 2.2.3 Calcular el Max Price efectivo
Max Price efectivo = maxBid de plantilla x countryPriceAdjustments.multiplier de plantilla x per_message_bid_multiplier
Ejemplo: Para una plantilla con maxBid: "0.1" en USD, los multiplicadores por país de 0.8 para la India y 1.3 para Malasia generan estos límites de precio efectivos: Los importes utilizan la moneda de facturación de tu cuenta de YCloud. Los países sin una anulación específica usan un multiplicador de 1. Omite todo el objeto bidSpec a nivel de mensaje para usar un multiplicador por mensaje de 1.

2.3 Reglas de cobro dinámico

El precio de cada mensaje entregado correctamente se calcula de forma dinámica para su destinatario:
  • El Max Price configurado en la plantilla representa únicamente el importe máximo que la empresa está dispuesta a pagar.
  • El cobro final por la entrega de un mensaje es dinámico; Meta cobra dicho precio máximo o uno inferior por la entrega.
  • Diferentes destinatarios en un mismo envío pueden tener precios de mensaje reales distintos.
  • Los mensajes que no se entregan no generan ningún cargo por entrega.
  • Un Max Price influye en la puja y en la oportunidad de entrega, pero no garantiza la entrega. Los resultados reales también pueden verse afectados por las pujas en tiempo real, el estado del destinatario y las comprobaciones de idoneidad de Meta.

2.4 ¿Qué es la herramienta de estimación de alcance?

La herramienta de estimación de alcance ayuda a las empresas a seleccionar un Max Price adecuado. Antes de realizar el envío, las empresas pueden usar el endpoint de estimación para consultar el volumen de entrega estimado y el rango de costes en diferentes niveles de Max Price, y luego elegir una estrategia de precios según los objetivos de su campaña y su presupuesto. Las estimaciones se facilitan únicamente con fines de planificación y no garantizan los resultados de entrega reales ni los importes finales de facturación. Los resultados reales pueden verse afectados por las pujas en tiempo real, el estado del destinatario y las comprobaciones de idoneidad de Meta.

3. Flujo de integración recomendado

  1. Llama a reachEstimate antes de enviar para comparar el rendimiento estimado con diferentes niveles de precio.
  2. Configura el Max Price a nivel de plantilla mediante bidSpec al crear la plantilla de marketing.
  3. De forma opcional, pasa per_message_bid_multiplier al enviar un mensaje para ajustar el Max Price para un destinatario individual.

4. Crear una plantilla con Max Price

4.1 Endpoint

Añade un objeto bidSpec al crear una plantilla de mensaje de marketing.

4.2 Parámetros de la solicitud

El objeto bidSpec contiene los siguientes campos:

4.3 Ejemplo de solicitud

4.4 Reglas

  • Solo las plantillas de tipo MARKETING admiten Max Price.
  • maxBid puede ser inferior a la tarifa publicada. Envía los importes y los multiplicadores como cadenas decimales, no como números JSON.
  • Si se omite bidSpec, la plantilla utiliza el precio estándar de la tarifa publicada.
  • Crear una plantilla con bidSpec: {} no es válido. Proporciona un maxBid válido al crear con bidSpec.

4.5 Ejemplo de respuesta

Tras crear la plantilla, la respuesta incluye el objeto de la plantilla y su configuración de bidSpec.

5. Añadir, actualizar o borrar Max Price

5.1 Endpoint

Usa PATCH /v2/whatsapp/templates/{wabaId}/{name}/{language} para editar una plantilla de marketing, incluida una creada sin Max Price.

5.2 Elegir el comportamiento de edición

Un objeto cuyas propiedades sean todas null, como {"maxBid": null, "countryPriceAdjustments": null}, también borra los ajustes. Las cadenas vacías, los arrays vacíos y otras propiedades que no sean nulas no se consideran una configuración vacía. Por ejemplo, {"countryPriceAdjustments": []} sin un maxBid válido no es válido. Para añadir o actualizar Max Price, usa los campos de Crear una plantilla con Max Price. Incluye la lista completa de países que quieras guardar. La lista enviada reemplaza a la lista almacenada localmente; omitirla o enviar una lista vacía no borra de forma explícita las anulaciones por país ya almacenadas por Meta. Para eliminar todos los ajustes de puja, envía bidSpec: {}. Incluye todos los componentes que quieras conservar. El siguiente ejemplo borra la configuración de pujas y conserva el cuerpo:

5.3 Reglas

  • Añadir, actualizar y borrar Max Price sigue el flujo existente de edición de plantillas y la validación de Meta. Solo se pueden editar las plantillas con estado APPROVED, REJECTED o PAUSED.
  • Proporciona los componentes que quieras conservar incluso si solo cambias el precio. Una edición correcta sigue el flujo existente de revisión y sincronización de estados.
  • Tras borrarlo correctamente, la respuesta de la plantilla ya no contiene un objeto bidSpec. Si falla Meta o la persistencia local, el endpoint devuelve un error.

6. Establecer un multiplicador de puja por mensaje al enviar un mensaje

6.1 Endpoint

Añade un objeto bidSpec a nivel de mensaje a cualquiera de los endpoints de envío:
  • POST /v2/whatsapp/messages/sendDirectly envía el mensaje de forma síncrona.
  • POST /v2/whatsapp/messages pone en cola el mensaje para su procesamiento asíncrono.
Usa el multiplicador con una plantilla de mensaje de marketing con Max Price enviada a través de Marketing Messages Lite. Llamar al endpoint sendDirectly no selecciona por sí solo el producto independiente Utility o Authentication Direct Send.

6.2 Parámetros de la solicitud

El objeto bidSpec a nivel de mensaje contiene el siguiente campo:

6.3 Ejemplo de solicitud

6.4 Reglas

  • per_message_bid_multiplier debe ser mayor que 0 y como máximo 999.999, con un máximo de tres decimales. Un valor mayor que 1 aumenta el Max Price efectivo, mientras que un valor entre 0 y 1 lo disminuye.
  • El multiplicador solo se aplica a una plantilla de marketing que tenga habilitado Max Price mediante bidSpec.
  • Si la solicitud del mensaje contiene un objeto bidSpec, per_message_bid_multiplier es obligatorio. A diferencia de la edición de una plantilla, bidSpec: {} en el mensaje no es válido. Para usar el multiplicador predeterminado de 1, omite todo el objeto bidSpec.

6.5 Respuesta

El endpoint de envío sigue utilizando la respuesta estándar de mensajes de WhatsApp. Pasar bidSpec no introduce una estructura de respuesta independiente. Cuando el estado devuelto es accepted, totalPrice es un precio estimado. En este ejemplo, el destinatario de EE. UU. no tiene ninguna invalidación por país, por lo que 0.05 x 1 x 1.1 = 0.055 USD. Consulta el webhook de entregado/leído para ver el cargo final.

7. Cargos finales y webhooks de estado del mensaje

7.1 Evento de Webhook

YCloud envía el evento de webhook whatsapp.message.updated cuando cambia el estado de un mensaje de WhatsApp. Para los mensajes enviados con Max Price, el webhook identifica el modo de fijación de precios y proporciona el cargo final después de que se entrega el mensaje.

7.2 Ejemplo de carga útil de Webhook

En este ejemplo:
  • totalPrice es el cargo final porque el estado del mensaje es delivered o read.
  • pricingCategory: marketing_lite_bidding identifica la categoría de precios de Max Price.
  • bidPricingFlag: true confirma que el mensaje se envió utilizando los precios de Max Price.

8. Estimar la entrega y el coste antes de enviar

8.1 Endpoint

  • Endpoint: GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate
  • Caso de uso: usa el endpoint de estimación de alcance antes de enviar para ver los rangos estimados de entrega y coste en distintos niveles de precio.

8.2 Parámetros de la solicitud

Ejemplo de solicitud:

8.3 Estructura de la respuesta

Cada elemento en estimates contiene:

8.4 Ejemplo de respuesta

Interpretación:
  1. Cuando el Max Price por mensaje es 395 / 1000 USD = USD 0.395, un lote de 1000 destinatarios tiene un rango estimado de tasa de entrega de 4.8% to 23.4% y un rango de coste estimado de aproximadamente USD 344.46 to USD 396.
  2. Cuando el Max Price por mensaje es 495 / 1000 USD = USD 0.495, un lote de 1000 destinatarios tiene un rango estimado de tasa de entrega de 6.3% to 26.3% y un rango de coste estimado de aproximadamente USD 353.067 to USD 429.597.

Preguntas frecuentes

¿Puedo saber el precio real de entrega para un destinatario específico antes de enviar?

No. El precio de entrega para cada destinatario es dinámico y no se puede saber por adelantado. La empresa solo necesita establecer el precio máximo que está dispuesta a pagar. Un mensaje entregado con éxito se cobra a su precio real de entrega, que no superará el Max Price efectivo.

¿Por qué los resultados reales de entrega difieren de la estimación?

El endpoint de estimación solo proporciona valores de referencia. Los resultados reales pueden verse afectados por las pujas en tiempo real, el estado del destinatario y las comprobaciones de idoneidad de Meta. Si la diferencia es considerable, ponte en contacto con YCloud para recibir asistencia.

¿Se devolverá el cargo real después de que se entregue un mensaje?

Sí. Cuando el estado del mensaje es delivered o read, totalPrice representa el cargo final basado en el precio real de entrega del destinatario. Cuando el mensaje se acepta inicialmente o su estado es sent, YCloud devuelve un precio estimado en lugar del cargo final.