Guía de integración de Max Price

1. Descripció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 fijación 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 costo 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 estimado de entrega y el costo con diferentes niveles de Max Price. Esta guía explica cómo usar la API de YCloud para:

Establecer un Max Price y un Country multiplier en una plantilla de mensaje de marketing
Aplicar opcionalmente un per-message multiplier al enviar un mensaje
Obtener el cargo final mediante webhooks de estado de mensajes
Estimar el volumen de entrega y el costo con diferentes niveles de Max Price antes de enviar

2. Conceptos básicos

2.1 ¿Qué es un Max Price?

Un Max Price es el monto 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 cargo 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 por Meta:

Estrategia de precios	Objetivo	Resultado esperado
Igual a la tarifa publicada	Controlar los costos manteniendo tasas de entrega similares a las de las campañas existentes de WhatsApp	Costos potencialmente más bajos manteniendo un nivel de entrega similar
Inferior a la tarifa publicada	Llegar a cohortes de clientes adecuadas a un menor costo	Reducir el precio máximo aceptable por mensaje, aunque el volumen de entrega puede variar en consecuencia
Superior a la tarifa publicada	Mejorar las tasas de entrega durante días festivos, promociones importantes o periodos pico de ventas	Aumentar la competitividad y mejorar la oportunidad de que se entreguen más mensajes

Un Max Price es un límite de precio máximo, no un cargo fijo. Establecer un Max Price no significa que cada mensaje entregado se cobrará a ese precio. El precio de cada mensaje se calcula de forma dinámica y puede ser igual o menor que el Max Price configurado.

2.2 Cómo configurar el Max Price

2.2.1 Configuración del precio máximo en una plantilla Puedes establecer un Max price fijo (maxBid) para una plantilla y configurar diferentes multiplicadores (countryPriceAdjustments.multiplier) para diferentes países o regiones. Por ejemplo, supongamos que 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 de 0,10 USD.

2.2.2 Ajuste del multiplicador al enviar un mensaje de plantilla Al enviar un mensaje mediante una plantilla con Max Price, puedes aplicar un multiplicador por mensaje superior a 0 para aumentar o disminuir el Max Price efectivo para un mensaje individual. 2.2.3 Cálculo del Max Price efectivo

Effective Max Price = Template maxBid x Template countryPriceAdjustments.multiplier x per_message_bid_multiplier

Ejemplo: Creaste una plantilla y la configuración de Max price a nivel de plantilla es la siguiente

maxBid: 0,1 USD,
countryPriceAdjustments.multiplier:
- IN: 0,8x
- MY: 1,3x

Luego hay 4 destinatarios; les envías con diferentes Per-message multiplier**,** los Effective Max Prices se calculan de la siguiente manera:

Destinatarios	Multiplicador por mensaje aplicado	País	Effective Max Price
Mike	1.2	IN	0.1(maxBid) x 0.8(multiplicador IN) x 1.2(multiplicador por mensaje) = 0.096 USD
Bob	0.5	MY	0.1(maxBid) * 1.3(multiplicador MY ) * 0.5(multiplicador por mensaje)= 0.065 USD
Jane	0.7	SG	0.1(maxBid) x 1(multiplicador predeterminado) x 0.7(multiplicador por mensaje) = 0.07 USD
Jack	None	IN	0.1(maxBid) * 0.8(multiplicador de IN ) * 1(multiplicador predeterminado)= 0.08 USD

2.3 Reglas de cobro dinámico

El precio de cada mensaje entregado con éxito se calcula dinámicamente 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 un mensaje entregado es dinámico; Meta cobra dicho precio máximo o uno menor por la entrega.
Diferentes destinatarios en un mismo envío pueden tener distintos precios reales por mensaje.
Los mensajes no entregados no generan cargos por entrega.
Un Max Price afecta a las pujas y a 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 elegibilidad 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 utilizar el endpoint de estimación para consultar el volumen de entrega estimado y el rango de costos a diferentes niveles de Max Price, y luego elegir una estrategia de precios basada en sus objetivos de campaña y presupuesto. Las estimaciones se proporcionan solo 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 elegibilidad de Meta.

3. Flujo de integración recomendado

Llama a reachEstimate antes de realizar el envío para comparar el rendimiento estimado a diferentes niveles de precio.
Configura el Max Price a nivel de plantilla mediante bidSpec al crear la plantilla de marketing.
Opcionalmente, 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.

Endpoint: https://api.ycloud.com/v2/whatsapp/templates
Caso de uso: Definir un Max Price a nivel de plantilla al crear una plantilla de marketing

4.2 Parámetros de la solicitud

El objeto bidSpec contiene los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
`maxBid`	string	Obligatorio si se proporciona `bidSpec`	Precio máximo permitido por la plantilla. La moneda predeterminada es la moneda de facturación de tu YCloud.
`countryPriceAdjustments`	string	No	Mapa del país de destino a un multiplicador de puja. Los países que no listes utilizan un multiplicador de `1.0` (el `maxBid` sin modificar). Hasta 50 entradas. Hasta 50 entradas.
`countryPriceAdjustments.countryCode`	string	Obligatorio si se proporciona `countryPriceAdjustments`	Las claves deben ser códigos de país válidos ISO 3166-1 alfa-2 (por ejemplo, `MX`, `IN`, `BR`).
`countryPriceAdjustments.multiplier`	string	Obligatorio si se proporciona `countryPriceAdjustments`	Cada multiplicador debe ser mayor que `0` y como máximo `10`.

4.3 Ejemplo de solicitud

curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/templates' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "category": "MARKETING",
    "wabaId": "{{YOUR_WABA_ID}}",
    "name": "market",
    "language": "en",
    "bidSpec": {
      "maxBid": "0.123",
      "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
    },
    "components": [
      {
        "type": "BODY",
        "text": "Hi, Black Friday is coming!"
      }
    ]
  }'

4.4 Reglas

maxBid debe ser mayor que 0 y puede ser inferior a la tarifa publicada.
Si se omite bidSpec, la plantilla utiliza los precios estándar de la tarifa publicada.

4.5 Ejemplo de respuesta

Una vez creada la plantilla, la respuesta incluye el objeto de la plantilla y su configuración de bidSpec.

{
  "officialTemplateId": "1763024734605057",
  "wabaId": "{{YOUR_WABA_ID}}",
  "name": "marketing_friday",
  "language": "en",
  "bidSpec": {
    "maxBid": "0.123",
    "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
  },
  "messageSendTtlSeconds": -1,
  "components": [
    {
      "type": "BODY",
      "text": "Hi, Black Friday is coming!"
    }
  ],
  "category": "MARKETING",
  "status": "PENDING",
  "qualityRating": "UNKNOWN",
  "createTime": "2026-08-12T15:18:42.356Z",
  "updateTime": "2026-08-12T15:18:42.356Z",
  "ctaUrlLinkTrackingOptedOut": true
}

5. Actualizar un Max Price en una plantilla

5.1 Endpoint

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

Endpoint: https://api.ycloud.com/v2/whatsapp/templates/{wabaId}/{name}/{language}
Caso de uso: Ajustar el precio máximo

5.2 Parámetros de la solicitud y ejemplo

Consulta Crear una plantilla con Max Price

4. Crear una plantilla con Max Price

5.3 Reglas

No puedes añadir bidSpec a una plantilla existente que se haya creado sin ella. Debes crear una nueva plantilla que incluya bidSpec.
Plantillas aprobadas: Hasta 100 ediciones por hora, 2,400 por día. Las ediciones de contenido siguen respetando el límite existente de 1 por día y 10 cada 30 días.
Plantillas rechazadas o pausadas: Ediciones ilimitadas

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

6.1 Endpoint

Añade un objeto bidSpec al enviar un mensaje directamente.

Endpoint: https://api.ycloud.com/v2/whatsapp/messages/sendDirectly
Caso de uso: Ajustar el Max Price efectivo para un destinatario individual

6.2 Parámetros de la solicitud

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

Campo	Tipo	Obligatorio	Descripción
`per_message_bid_multiplier`	string	Condicional	Multiplicador aplicado al Max Price efectivo a nivel de plantilla para este mensaje. Debe ser mayor que 0 y admite hasta tres decimales. Si se incluye `bidSpec` en la solicitud, este campo es obligatorio. Para usar el multiplicador predeterminado de `1`, omita todo el objeto `bidSpec`.

6.3 Ejemplo de solicitud

curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "template",
    "bidSpec": {
      "per_message_bid_multiplier": "1.2"
    },
    "template": {
      "language": {
        "code": "en"
      },
      "name": "marketing_friday"
    },
    "from": "+1555*****",
    "to": "+62*****"
  }'

6.4 Reglas

per_message_bid_multiplier debe ser mayor que 0 y admite hasta 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 Max Price habilitado a través de bidSpec.
Si la solicitud del mensaje contiene un objeto bidSpec, per_message_bid_multiplier es obligatorio. Para usar el multiplicador predeterminado de 1, omita todo el objeto bidSpec.

6.5 Respuesta

El endpoint de envío continúa 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 lugar del cargo final.

{
  "id": "6a7c922697330900cf11ca2f",
  "wamid": "wamid.HBgNODYxNTA2NzExMDI0NBUCABEYEkE1REJGMkIzOTMwQ0VENUIyMAA=",
  "status": "accepted",
  "from": "+1555*****",
  "to": "+62*****",
  "wabaId": "{{YOUR_WABA_ID}}",
  "type": "template",
  "template": {
    "name": "marketing_friday",
    "language": {
      "code": "en"
    }
  },
  "createTime": "2026-08-12T15:32:54.571Z",
  "updateTime": "2026-08-12T15:32:55.228Z",
  "totalPrice": 0.1845,
  "pricingCategory": "marketing_lite_bidding",
  "currency": "USD",
  "regionCode": "ID",
  "bizType": "whatsapp"
}

7. Cargos finales y Webhooks de estado de 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 utilizando Max Price, el Webhook identifica el modo de fijación de precios y proporciona el cargo final una vez entregado el mensaje.

Campo	Nuevo campo/valor	Descripción
`bidPricingFlag`	Nuevo campo	Booleano. `true` indica que el mensaje se envió con el precio Max Price; `false` indica la tarifa publicada estándar
`pricingCategory`	Nuevo valor	Los mensajes de marketing con Max Price usan `marketing_lite_bidding`
`totalPrice`	Campo existente	Precio dinámico del mensaje. El valor puede variar según el destinatario. Se convierte en el cargo final cuando el estado del mensaje es `delivered` o `read`

7.2 Ejemplo de carga útil de Webhook

curl --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "evt_6a7d30d9c038963ead5945f3",
    "type": "whatsapp.message.updated",
    "apiVersion": "v2",
    "createTime": "2026-08-13T02:50:01.057Z",
    "whatsappMessage": {
      "id": "6a7d30c92733962aed9f0fda",
      "wamid": "wamid.HBgLNTE5OTc5NTMwOTQVAgARGBI5MUJBNTE0Qjk4Q0E5NTIzMDgA",
      "status": "read",
      "from": "+1555***",
      "to": "+62***",
      "wabaId": "{{YOUR_WABA_ID}}",
      "recipient": "ID.12*******",
      "type": "template",
      "template": {
        "name": "marketing_friday",
        "language": {
          "code": "en"
        },
        "components": []
      },
      "createTime": "2026-08-13T02:49:45.403Z",
      "sendTime": "2026-08-13T02:49:50.000Z",
      "deliverTime": "2026-08-13T02:49:50.000Z",
      "readTime": "2026-08-13T02:50:00.000Z",
      "totalPrice": 0.0703,
      "pricingCategory": "marketing_lite_bidding",
      "bidPricingFlag": true,
      "pricingType": "regular",
      "pricingModel": "PMP",
      "currency": "USD",
      "regionCode": "ID",
      "bizType": "whatsapp",
      "recipientUserId": "ID.12*******"
    }
  }'

En este ejemplo:

totalPrice es el cargo final porque el estado del mensaje es deliveredoread.
pricingCategory: marketing_lite_bidding identifica la categoría de precio Max Price.
bidPricingFlag: true confirma que el mensaje se envió utilizando el precio Max Price.

8. Estimar la entrega y el costo antes de enviar

8.1 Endpoint

Endpoint: GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate
Caso de uso: utilice el endpoint de estimación de alcance antes de enviar para ver la entrega estimada y los rangos de costo en diferentes niveles de precio.

8.2 Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Descripción
`wabaId`	string	Sí	ID de la cuenta de WhatsApp Business
`targetCountry`	string	Sí	Código de país de destino. Las claves deben ser códigos de país válidos ISO 3166-1 alfa-2 (por ejemplo, `MX`, `IN`, `BR`).. Las claves deben ser códigos de país válidos ISO 3166-1 alfa-2 (por ejemplo, `MX`, `IN`, `BR`).
`dateInterval`	string	No	Período de referencia para los datos históricos utilizados para generar estimaciones. Uno de los siguientes: `L1D` (último 1 día), `L7D` (últimos 7 días), `L14D` (últimos 14 días), `L28D` (últimos 28 días). Predeterminado `L28D`

Ejemplo de solicitud:

GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D

8.3 Estructura de respuesta

Campo	Tipo	Descripción
`waba_currency`	string	Moneda de la WABA
`estimates`	array	Lista de niveles de precios estimados
`dateInterval`	string	Período de referencia para los datos históricos utilizados para generar estimaciones

Cada elemento en estimates contiene:

Campo	Tipo	Descripción
`bid_amount`	number	Importe máximo que la empresa está dispuesta a pagar por un lote de 1,000 destinatarios
`users`	number	Cantidad de destinatarios objetivo; actualmente fijado en `1000`
`deliveries_lower_bound`	string	Cantidad mínima estimada de mensajes entregados por cada 1,000 destinatarios
`deliveries_upper_bound`	string	Cantidad máxima estimada de mensajes entregados por cada 1,000 destinatarios
`cost_lower_bound`	number	Costo mínimo estimado para el lote
`cost_upper_bound`	number	Costo máximo estimado para el lote

8.4 Ejemplo de respuesta

{
  "waba_currency": "USD",
  "dateInterval": "L7D",
  "estimates": [
    {
      "bid_amount": 395,
      "users": 1000,
      "deliveries_lower_bound": 48,
      "deliveries_upper_bound": 234,
      "cost_lower_bound": 344.46,
      "cost_upper_bound": 396
    },
    {
      "bid_amount": 495,
      "users": 1000,
      "deliveries_lower_bound": 63,
      "deliveries_upper_bound": 263,
      "cost_lower_bound": 353.067,
      "cost_upper_bound": 429.597
    }
  ]
}

Interpretación:

Cuando el Max Price por mensaje es 395 / 1000 USD = USD 0.395, un lote de 1,000 destinatarios tiene un rango estimado de tasa de entrega de 4.8% to 23.4% y un rango estimado de costo de aproximadamente USD 344.46 to USD 396.
Cuando el Max Price por mensaje es 495 / 1000 USD = USD 0.495, un lote de 1,000 destinatarios tiene un rango estimado de tasa de entrega de 6.3% to 26.3% y un rango estimado de costo 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 conocer 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, el cual 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 verificaciones de elegibilidad de Meta. Si la diferencia es significativa, contacta a YCloud para obtener ayuda.

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

​1. Descripción general

​2. Conceptos básicos

​2.1 ¿Qué es un Max Price?

​2.2 Cómo configurar el Max Price

​2.3 Reglas de cobro dinámico

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

​3. Flujo de integración recomendado

​4. Crear una plantilla con Max Price

​4.1 Endpoint

​4.2 Parámetros de la solicitud

​4.3 Ejemplo de solicitud

​4.4 Reglas

​4.5 Ejemplo de respuesta

​5. Actualizar un Max Price en una plantilla

​5.1 Endpoint

​5.2 Parámetros de la solicitud y ejemplo

​4. Crear una plantilla con Max Price

​5.3 Reglas

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

​6.1 Endpoint

​6.2 Parámetros de la solicitud

​6.3 Ejemplo de solicitud

​6.4 Reglas

​6.5 Respuesta

​7. Cargos finales y Webhooks de estado de mensaje

​7.1 Evento de Webhook

​7.2 Ejemplo de carga útil de Webhook

​8. Estimar la entrega y el costo antes de enviar

​8.1 Endpoint

​8.2 Parámetros de solicitud

​8.3 Estructura de respuesta

​8.4 Ejemplo de respuesta

​Preguntas frecuentes

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

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

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

1. Descripción general

2. Conceptos básicos

2.1 ¿Qué es un Max Price?

2.2 Cómo configurar el Max Price

2.3 Reglas de cobro dinámico

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

3. Flujo de integración recomendado

4. Crear una plantilla con Max Price

4.1 Endpoint

4.2 Parámetros de la solicitud

4.3 Ejemplo de solicitud

4.4 Reglas

4.5 Ejemplo de respuesta

5. Actualizar un Max Price en una plantilla

5.1 Endpoint

5.2 Parámetros de la solicitud y ejemplo

4. Crear una plantilla con Max Price

5.3 Reglas

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

6.1 Endpoint

6.2 Parámetros de la solicitud

6.3 Ejemplo de solicitud

6.4 Reglas

6.5 Respuesta

7. Cargos finales y Webhooks de estado de mensaje

7.1 Evento de Webhook

7.2 Ejemplo de carga útil de Webhook

8. Estimar la entrega y el costo antes de enviar

8.1 Endpoint

8.2 Parámetros de solicitud

8.3 Estructura de respuesta

8.4 Ejemplo de respuesta

Preguntas frecuentes

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

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

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