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

# Guia de integração de preços de mensagens do WhatsApp

> Entenda os campos de preços de mensagens do WhatsApp, regras de cobrança e finalidade do preço nos webhooks da YCloud.

A YCloud fornece informações de preços por mensagem por meio de webhooks de atualização de mensagens do WhatsApp. Este guia descreve o evento de assinatura, os campos de preços, as regras de cobrança e quando os preços das mensagens se tornam definitivos.

A YCloud cobra apenas por mensagens enviadas (outbound) no WhatsApp (mensagens enviadas da sua empresa para os usuários). Mensagens recebidas (inbound) são gratuitas.

## 1. Evento de assinatura

A YCloud envia atualizações de status e preços de mensagens por meio do evento `whatsapp.message.updated`. As assinaturas estão disponíveis em **Desenvolvedores → Webhook** no Console da YCloud.

A solicitação a seguir cria uma assinatura por meio da API. Consulte [Criar um endpoint de webhook](/api-reference/webhook-endpoints/create-a-webhook-endpoint) para a referência do 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 o endpoint de recebimento do webhook. O tratamento de eventos e a verificação de assinatura são descritos no [Guia de Integração de Webhook](/pt/api-reference/guides/api-fundamentals/configure-webhooks).

## 2. Campos de preços

As informações de preços estão incluídas no objeto `whatsappMessage` do retorno de chamada (callback):

| Campo | Descrição |
| - | - |
| `pricingModel` | Sempre `PMP`, significando cobrança por mensagem. |
| `pricingType` | O tipo de preço da mensagem: cobrável ou gratuito. |
| `pricingCategory` | A categoria de preço da mensagem, como `marketing`, `utility`, `authentication`, `service` ou `referral_conversion` (ponto de entrada gratuito). Quando `pricingType=free_entry_point`, este campo é `referral_conversion`. |
| `totalPrice` | O valor informado pela YCloud para esta mensagem. |
| `currency` | A moeda do valor, como `USD`, obtida a partir da configuração de moeda da conta (tenant). |

Outros campos são descritos em [Recuperar uma mensagem](/api-reference/whatsapp-messages/retrieve-a-message).

## 3. Regras de preços

### 3.1 Definição final de preço

A YCloud relata preços estimados ou finais de acordo com o status da mensagem:

| Status da mensagem | Significado do preço |
| - | - |
| `accepted` / `sent` | Preço estimado. |
| `delivered` / `read` | Preço final. O faturamento utiliza o `totalPrice` e o `currency` informados nesta etapa. |
| `failed` | Falha no envio. A YCloud não cobra pela mensagem. |

### 3.2 Tipos de preços cobráveis e gratuitos

A YCloud relata os três tipos de preços a seguir por meio de `pricingType`:

| `pricingType` | Significado |
| - | - |
| `regular` | Preço cobrável padrão. O valor real informado pela YCloud está em `totalPrice`. |
| `free_customer_service` | Uma mensagem gratuita dentro da janela de atendimento ao cliente. A YCloud informa um valor de `0`. De acordo com a [atualização de preços do WhatsApp](/pt/documentation/pricing-and-billing/whatsapp-pricing-and-billing), a partir de 1º de outubro de 2026, cada número de telefone comercial receberá 1.000 mensagens de serviço entregues gratuitas por mês. Mensagens de serviço individuais (one-to-one) dentro dessa franquia continuam a usar esse tipo de preço. |
| `free_entry_point` | Uma mensagem de ponto de entrada gratuito coberta pelas regras de ponto de entrada gratuito de 72 horas. Seu `pricingCategory` é `referral_conversion`, e a YCloud relata um valor de `0`. |

A partir de 1º de outubro de 2026, a franquia de serviço será reiniciada mensalmente para cada número de telefone comercial. A franquia não utilizada não acumula para o mês seguinte, e mensagens de serviço individuais e em grupo compartilham a mesma franquia. Quando esgotada, as mensagens de serviço individuais passam a usar o preço `regular`, a menos que as regras de ponto de entrada gratuito se apliquem.

A partir da mesma data, modelos de utilidade dentro da janela de atendimento ao cliente não serão mais gratuitos apenas porque a janela está aberta e não serão cobertos pela franquia de serviço. Mensagens qualificadas para preços de ponto de entrada gratuito continuarão a usar `free_entry_point`.

Uma janela de ponto de entrada gratuito é iniciada quando um usuário envia uma mensagem para uma empresa por meio de um anúncio de clique para o WhatsApp ou de um botão do WhatsApp em uma Página do Facebook usando o WhatsApp para Android ou iOS, e a empresa responde dentro de 24 horas. A janela dura 72 horas a partir da resposta da empresa. Os clientes do WhatsApp para computador (desktop) e web não são elegíveis para essa regra de ponto de entrada.

## 4. Exemplos de payload de webhook

Os seguintes trechos de retorno de chamada representam mensagens individuais (one-to-one). Os IDs e valores cobrados são meramente ilustrativos, não cotações de tarifas reais. Para obter payloads completos, consulte [Exemplos de webhook de mensagem atualizada do WhatsApp](/pt/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples).

### 4.1 Mensagem de marketing: cobrável

Uma mensagem de marketing entregue utiliza o preço `regular`. O valor final ilustrativo é `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 Mensagem de serviço: cobrável

A partir de 1º de outubro de 2026, quando o número de telefone comercial tiver esgotado sua franquia mensal de 1.000 mensagens de serviço gratuitas e a mensagem não for elegível para o preço de ponto de entrada gratuito, a YCloud relatará `pricingType=regular`. O valor final ilustrativo é `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 Mensagem de serviço: dentro do limite gratuito

A partir de 1º de outubro de 2026, para uma mensagem coberta pela franquia mensal de 1.000 mensagens de serviço gratuitas do número de telefone comercial, a YCloud informa `pricingType=free_customer_service` e um valor 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 Mensagem de ponto de entrada gratuito

Para uma mensagem entregue dentro da janela de 72 horas do ponto de entrada gratuito, a YCloud informa `pricingType=free_entry_point`, `pricingCategory=referral_conversion` e um valor 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.