> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
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 **cargo final a través de webhooks de estado del mensaje**
4. 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
1. Llame a `reachEstimate` antes de enviar para comparar el rendimiento estimado en diferentes niveles de precio.
2. Configure el Max Price a nivel de plantilla a través de `bidSpec` al crear la plantilla de marketing.
3. 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](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
```bash highlight={11-23} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.
```json highlight={6-18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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}](https://docs.ycloud.com/reference/whatsapp_template-edit-by-name-and-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-create-a-template-with-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](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
```bash highlight={8-9} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```json highlight={18} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```bash highlight={28-30} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 `delivered`o`read`.
* `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:
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
1. 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`.
2. 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.