Guía de integración de Max Price

Esta función se encuentra actualmente en versión beta. Para solicitar acceso, ponte en contacto con YCloud.

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 precios introducidas por Meta para la API de Marketing Messages en 2026, incluyendo 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 menor por cada mensaje entregado. Antes del envío, las empresas también pueden usar la Reach Estimation Tool para conocer el volumen de entrega estimado y el costo en 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 multiplicador por mensaje al enviar un mensaje
Obtener el cargo final a través de webhooks de estado del mensaje
Estimar el volumen de entrega y el costo en diferentes niveles de Max Price antes de enviar

2. Conceptos básicos

2.1 ¿Qué es un Max Price?

Un Max Price es la cantidad máxima 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 inferior 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 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, grandes promociones 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 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 diferentes países o regiones. Por ejemplo, supongamos que el maxBid se establece en USD 0.10, con un multiplicador de 0.8× para India y un multiplicador de 1.3× para Malasia:

Cuando la plantilla se utiliza para enviar un mensaje a India, el Max Price a nivel de plantilla es USD 0.10 × 0.8 = USD 0.08.
Cuando la plantilla se utiliza para enviar un mensaje a Malasia, el Max Price a nivel de plantilla es USD 0.10 × 1.3 = USD 0.13.
Cuando la plantilla se envía a cualquier otro país, el Max Price a nivel de plantilla es USD 0.10.

2.2.2 Ajustar el multiplicador al enviar un mensaje de plantilla Al enviar un mensaje usando una plantilla con Max Price, puedes aplicar un multiplicador por mensaje mayor a 0 para aumentar o disminuir el Max Price efectivo para un mensaje individual. 2.2.3 Calcular el Max Price efectivo

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

Ejemplo: Creaste una plantilla y los ajustes de Max Price a nivel de plantilla son los siguientes

maxBid: 0.1 USD,
countryPriceAdjustments.multiplier:
- IN: 0.8x
- MY: 1.3x

Luego hay 4 destinatarios; les envías con diferentes multiplicadores por mensaje**,** los Max Prices efectivos se calculan de la siguiente manera:

Destinatarios	Multiplicador por mensaje aplicado	País	Max Price efectivo
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 por defecto) x 0.7(multiplicador por mensaje) = 0.07 USD
Jack	Ninguno	IN	0.1(maxBid) * 0.8(multiplicador de IN ) * 1(multiplicador por defecto)= 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 la entrega de un mensaje es dinámico; Meta cobra ese precio máximo o uno inferior por la entrega.
Diferentes destinatarios en un mismo envío pueden tener diferentes precios reales de mensaje.
Los mensajes que no se entregan no generan ningún cargo por entrega.
Un Max Price afecta a la puja y a la oportunidad de entrega, pero no garantiza la entrega. Los resultados reales también pueden verse afectados por la puja 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 ver el volumen estimado de entrega y el rango de costes en diferentes niveles de Max Price, y luego elegir una estrategia de precios basada en los objetivos de su campaña y su presupuesto. Las estimaciones se proporcionan solo con fines de planificación y no garantizan los resultados reales de entrega ni los importes finales de facturación. Los resultados reales pueden verse afectados por la puja en tiempo real, el estado del destinatario y las comprobaciones de idoneidad de Meta.

3. Flujo de integración recomendado

Llame a reachEstimate antes de enviar para comparar el rendimiento estimado en diferentes niveles de precio.
Configure el Max Price a nivel de plantilla a través de bidSpec al crear la plantilla de marketing.
Opcionalmente, pase 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ñada un objeto bidSpec al crear una plantilla de mensaje de marketing.

Endpoint: https://api.ycloud.com/v2/whatsapp/templates
Caso de uso: Establecer 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	Requerido	Descripción
`maxBid`	string	Requerido si se proporciona `bidSpec`	Precio máximo permitido por la plantilla. La moneda se establece por defecto en su moneda de facturación de YCloud.
`countryPriceAdjustments`	string	No	Mapeo del país de destino a un multiplicador de puja. Los países que no liste usarán un multiplicador de `1.0` (el `maxBid` sin modificar). Hasta 50 entradas. Hasta 50 entradas.
`countryPriceAdjustments.countryCode`	string	Requerido si se proporciona `countryPriceAdjustments`	Las claves deben ser códigos de país ISO 3166-1 alpha-2 válidos (por ejemplo, `MX`, `IN`, `BR`).
`countryPriceAdjustments.multiplier`	string	Requerido si se proporciona `countryPriceAdjustments`	Cada multiplicador debe ser superior a `0` y como máximo de `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 superior a 0 y puede ser inferior a la tarifa publicada.
Si se omite bidSpec, la plantilla utiliza el precio 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ñada 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 max price

5.2 Parámetros de la solicitud y ejemplo

Consulte Crear una plantilla con Max Price

4. Crear una plantilla con Max Price

5.3 Reglas

No puede añadir bidSpec a una plantilla existente creada sin él. Debe crear una nueva plantilla que incluya bidSpec.
Plantillas aprobadas: hasta 100 ediciones por hora, 2400 por día. Las ediciones de contenido siguen sujetas al límite existente de 1 por día y 10 cada 30 días.
Plantillas rechazadas o en pausa: ediciones ilimitadas

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

6.1 Endpoint

Añada 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	Requerido	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`, omite 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 reduce.
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. Para usar el multiplicador predeterminado de 1, omite todo el objeto bidSpec.

6.5 Respuesta

El endpoint de envío continúa utilizando la respuesta de mensaje estándar de WhatsApp. Pasar bidSpec no introduce una estructura de respuesta separada. 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 mensajes

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 mediante 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 modelo de precios Max Price; `false` indica precios estándar de tarifa publicada
`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 diferir según el destinatario. Se convierte en el cargo final cuando el estado del mensaje es `delivered` o `read`

7.2 Ejemplo de payload del 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 precios de Max Price.
bidPricingFlag: true confirma que el mensaje se envió mediante precios de 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: Utiliza el endpoint de estimación de alcance antes de enviar para consultar los rangos estimados de entrega y costo en diferentes niveles de precio.

8.2 Parámetros de solicitud

Parámetro	Tipo	Requerido	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 ISO 3166-1 alfa-2 válidos (por ejemplo, `MX`, `IN`, `BR`).. Las claves deben ser códigos de país ISO 3166-1 alfa-2 válidos (por ejemplo, `MX`, `IN`, `BR`).
`dateInterval`	string	No	Periodo retrospectivo para los datos históricos utilizados para generar las estimaciones. Uno de: `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 precio estimados
`dateInterval`	string	Periodo retrospectivo de los datos históricos utilizados para generar las estimaciones

Cada elemento en estimates contiene:

Campo	Tipo	Descripción
`bid_amount`	number	Monto máximo que el negocio está dispuesto a pagar por un lote de 1000 destinatarios
`users`	number	Número de destinatarios objetivo; actualmente fijado en `1000`
`deliveries_lower_bound`	string	Cantidad mínima estimada de mensajes entregados por cada 1000 destinatarios
`deliveries_upper_bound`	string	Cantidad máxima estimada de mensajes entregados por cada 1000 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 Precio Máximo 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 de costo estimado de aproximadamente USD 344.46 to USD 396.
Cuando el Precio Máximo 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 de costo 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 conocer de antemano. 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 excederá el Precio Máximo efectivo.

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

El endpoint de estimación proporciona únicamente valores de referencia. Los resultados reales pueden verse afectados por las subastas en tiempo real, el estado del destinatario y las comprobaciones 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 establecer 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 mensajes

​7.1 Evento de Webhook

​7.2 Ejemplo de payload del 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 establecer 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 mensajes

7.1 Evento de Webhook

7.2 Ejemplo de payload del 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?