> ## 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 precios de mensajes de WhatsApp

> Comprende los campos de precios de mensajes de WhatsApp, las reglas de cobro y la definitividad de los precios en los webhooks de YCloud.

YCloud proporciona información de precios por mensaje a través de webhooks de actualización de mensajes de WhatsApp. Esta guía describe el evento de suscripción, los campos de precios, las reglas de cobro y el momento en que los precios de los mensajes pasan a ser definitivos.

YCloud solo cobra por los mensajes de WhatsApp salientes (mensajes enviados desde tu empresa a los usuarios). Los mensajes entrantes son gratuitos.

## 1. Evento de suscripción

YCloud envía actualizaciones de estado y precios de los mensajes a través del evento `whatsapp.message.updated`. Las suscripciones están disponibles en **Desarrolladores → Webhook** en la consola de YCloud.

La siguiente solicitud crea una suscripción a través de la API. Consulta [Crear un endpoint de webhook](/api-reference/webhook-endpoints/create-a-webhook-endpoint) para la referencia del endpoint:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": ["whatsapp.message.updated"],
  "status": "active"
}
```

`url` especifica el endpoint de recepción del webhook. La gestión de eventos y la verificación de firmas se describen en la [Guía de integración de webhooks](/es/api-reference/guides/api-fundamentals/configure-webhooks).

## 2. Campos de precios

La información de precios se incluye en el objeto `whatsappMessage` del callback:

| Campo | Descripción |
| - | - |
| `pricingModel` | Siempre `PMP`, lo que significa precio por mensaje. |
| `pricingType` | El tipo de precio facturable o gratuito del mensaje. |
| `pricingCategory` | La categoría de precio del mensaje, como `marketing`, `utility`, `authentication`, `service` o `referral_conversion` (punto de entrada gratuito). Cuando `pricingType=free_entry_point`, este campo es `referral_conversion`. |
| `totalPrice` | El importe informado por YCloud para este mensaje. |
| `currency` | La moneda del importe, como `USD`, obtenida de la configuración de moneda del tenant. |

Los demás campos se describen en [Recuperar un mensaje](/api-reference/whatsapp-messages/retrieve-a-message).

## 3. Reglas de precios

### 3.1 Definitividad del precio

YCloud informa precios estimados o definitivos según el estado del mensaje:

| Estado del mensaje | Significado del precio |
| - | - |
| `accepted` / `sent` | Precio estimado. |
| `delivered` / `read` | Precio definitivo. La facturación utiliza el `totalPrice` y la `currency` reportados en esta etapa. |
| `failed` | Envío fallido. YCloud no cobra por el mensaje. |

### 3.2 Tipos de precios facturables y gratuitos

YCloud informa los siguientes tres tipos de precios a través de `pricingType`:

| `pricingType` | Significado |
| - | - |
| `regular` | Precio facturable regular. El importe real informado por YCloud está en `totalPrice`. |
| `free_customer_service` | Un mensaje gratuito dentro de la ventana de atención al cliente. YCloud informa un importe de `0`. Según la [actualización de precios de WhatsApp](/es/documentation/pricing-and-billing/whatsapp-pricing-and-billing), a partir del 1 de octubre de 2026, cada número de teléfono comercial recibe 1000 mensajes de servicio entregados gratuitos por mes. Los mensajes de servicio individuales dentro de este cupo continúan utilizando este tipo de precio. |
| `free_entry_point` | Un mensaje de punto de entrada gratuito cubierto por las reglas de punto de entrada gratuito de 72 horas. Su `pricingCategory` es `referral_conversion`, y YCloud informa un importe de `0`. |

A partir del 1 de octubre de 2026, el cupo de servicio se reinicia mensualmente para cada número de teléfono comercial. El cupo no utilizado no se acumula, y los mensajes de servicio individuales y grupales comparten el mismo cupo. Una vez agotado, los mensajes de servicio individuales utilizan el precio `regular`, a menos que apliquen las reglas de punto de entrada gratuito.

A partir de la misma fecha, las plantillas de utilidad dentro de la ventana de atención al cliente ya no son gratuitas solo porque la ventana esté abierta y no están cubiertas por el cupo de servicio. Los mensajes que cumplen con los requisitos para el precio de punto de entrada gratuito siguen utilizando `free_entry_point`.

Una ventana de punto de entrada gratuito se abre cuando un usuario envía un mensaje a una empresa a través de un anuncio que dirige a WhatsApp o de un botón de WhatsApp en una página de Facebook mediante WhatsApp para Android o iOS, y la empresa responde dentro de las 24 horas. La ventana dura 72 horas a partir de la respuesta de la empresa. Los clientes de WhatsApp para escritorio y web no cumplen con los requisitos para esta regla de punto de entrada.

## 4. Ejemplos de payload de Webhook

Los siguientes extractos de callback representan mensajes individuales. Los ID y los importes de cobro son ilustrativos, no cotizaciones de tarifas reales. Para ver los payloads completos, consulta [Ejemplos de webhook de mensaje de WhatsApp actualizado](/es/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples).

### 4.1 Mensaje de marketing: facturable

Un mensaje de marketing entregado utiliza el precio `regular`. El importe definitivo ilustrativo es `0.05 USD`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000001",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.05,
    "currency": "USD"
  }
}
```

### 4.2 Mensaje de servicio: facturable

A partir del 1 de octubre de 2026, cuando el número de teléfono comercial haya agotado su cupo mensual de 1000 mensajes de servicio gratuitos y el mensaje no cumpla con los requisitos para el precio de punto de entrada gratuito, YCloud informa `pricingType=regular`. El importe definitivo ilustrativo es `0.01 USD`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000002",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "service",
    "totalPrice": 0.01,
    "currency": "USD"
  }
}
```

### 4.3 Mensaje de servicio: dentro de la asignación gratuita

A partir del 1 de octubre de 2026, para un mensaje cubierto por la asignación mensual de 1.000 mensajes de servicio gratuitos del número de teléfono comercial, YCloud informa `pricingType=free_customer_service` y un importe final de `0`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000003",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_customer_service",
    "pricingCategory": "service",
    "totalPrice": 0,
    "currency": "USD"
  }
}
```

### 4.4 Mensaje de punto de entrada gratuito

Para un mensaje entregado dentro de la ventana de 72 horas del punto de entrada gratuito, YCloud informa `pricingType=free_entry_point`, `pricingCategory=referral_conversion` y un importe final de `0`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000004",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_entry_point",
    "pricingCategory": "referral_conversion",
    "totalPrice": 0,
    "currency": "USD"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.