> ## 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 do Max Price
Este recurso está atualmente em versão beta. Para solicitar acesso, entre em contato com a YCloud.
## 1. Visão geral
Para ajudar as empresas a obter maior controle e otimizar seus gastos com mensagens de marketing no WhatsApp, a YCloud oferece suporte aos novos recursos de preços introduzidos pela Meta para a API de Mensagens de Marketing em 2026, incluindo o **Max Price** e a **Reach Estimation Tool**.
Com a API da YCloud, as empresas podem definir o preço máximo que estão dispostas a pagar por cada mensagem de marketing do WhatsApp entregue e ajustar sua estratégia de preços com base no custo da campanha e nos objetivos de entrega. Quando um Max Price é definido, a Meta cobra esse valor ou um valor inferior para cada mensagem entregue. Antes do envio, as empresas também podem usar a Reach Estimation Tool para entender o volume estimado de entrega e o custo em diferentes níveis de Max Price.
Este guia explica como usar a API da YCloud para:
1. Definir um **Max Price** e um **multiplicador por país** em um modelo de mensagem de marketing
2. Opcionalmente, aplicar um **multiplicador por mensagem** ao enviar uma mensagem
3. Obter a **cobrança final por meio de webhooks de status de mensagem**
4. Estimar o volume de entrega e o custo em diferentes níveis de **Max Price** antes do envio
## 2. Conceitos fundamentais
### 2.1 O que é o Max Price?
O Max Price é o **valor máximo que uma empresa está disposta a pagar por cada mensagem de marketing do WhatsApp entregue com sucesso**. Quando um Max Price é definido, a Meta cobra esse preço ou um valor menor pela entrega. A cobrança real não excederá o limite de preço configurado.
Dependendo do objetivo de uma campanha de marketing, uma empresa pode definir seu Max Price no mesmo nível, abaixo ou acima da taxa publicada pela Meta:
| Estratégia de preços | Objetivo | Resultado esperado |
| - | - | - |
| Igual à taxa publicada | Controlar custos enquanto mantém taxas de entrega semelhantes às campanhas existentes no WhatsApp | Custos potencialmente menores enquanto mantém um nível semelhante de entrega |
| Menor que a taxa publicada | Alcançar grupos de clientes adequados a um custo menor | Reduzir o preço máximo aceitável por mensagem, embora o volume de entrega possa mudar proporcionalmente |
| Maior que a taxa publicada | Melhorar as taxas de entrega durante feriados, grandes promoções ou períodos de pico de vendas | Aumentar a competitividade e melhorar a oportunidade de entregar mais mensagens |
**O Max Price é um teto de preço, não uma cobrança fixa.** Definir um Max Price não significa que cada mensagem entregue será cobrada por esse preço. O preço de cada mensagem é calculado dinamicamente e pode ser igual ou inferior ao Max Price configurado.
### 2.2 Como definir o Max Price
**2.2.1 Definir o preço máximo em um modelo**
Você pode definir um Max Price fixo (`maxBid`) para um modelo e configurar diferentes multiplicadores (`countryPriceAdjustments.multiplier`) para diferentes países ou regiões. Por exemplo, suponha que o `maxBid` esteja definido como USD 0,10, com um multiplicador de 0,8× para a Índia e um multiplicador de 1,3× para a Malásia:
* Quando o modelo for usado para enviar uma mensagem para a Índia, o Max Price no nível do modelo será de USD 0,10 × 0,8 = USD 0,08.
* Quando o modelo for usado para enviar uma mensagem para a Malásia, o Max Price no nível do modelo será de USD 0,10 × 1,3 = USD 0,13.
* Quando o modelo for enviado para qualquer outro país, o Max Price no nível do modelo será de USD 0,10.
**2.2.2 Ajustar o multiplicador ao enviar uma mensagem de modelo**
Ao enviar uma mensagem usando um modelo com Max Price, você pode aplicar um multiplicador por mensagem maior que 0 para aumentar ou diminuir o Max Price efetivo para uma mensagem individual.
**2.2.3 Calcular o Max Price efetivo**
Max Price efetivo = maxBid do modelo x countryPriceAdjustments.multiplier do modelo x per\_message\_bid\_multiplier
Exemplo:
Você criou um modelo com as seguintes configurações de Max Price no nível do modelo:
* maxBid: 0.1 USD,
* countryPriceAdjustments.multiplier:
* IN: 0.8x
* MY: 1.3x
Considerando 4 destinatários aos quais você envia com diferentes multiplicadores por mensagem\*\*,\*\* os Max Prices efetivos são calculados da seguinte forma:
| Destinatários | Multiplicador por mensagem aplicado | País | **Max Price efetivo** |
| - | - | - | - |
| Mike | 1.2 | IN | 0.1(maxBid) x 0.8(multiplicador IN) x 1.2(multiplicador por mensagem) = 0.096 USD |
| Bob | 0.5 | MY | 0.1(maxBid) \* 1.3(multiplicador **MY** ) \* 0.5(multiplicador por mensagem)= 0.065 USD |
| Jane | 0,7 | SG | 0,1(maxBid) x 1(multiplicador padrão) x 0,7(multiplicador por mensagem) = 0,07 USD |
| Jack | Nenhum | IN | 0,1(maxBid) \* 0,8(multiplicador **IN** ) \* 1(multiplicador padrão)= 0,08 USD |
### 2.3 Regras de cobrança dinâmica
O preço de cada mensagem entregue com sucesso é calculado dinamicamente para o seu destinatário:
* O Max Price configurado no modelo representa apenas o valor máximo que a empresa está disposta a pagar.
* A cobrança final para uma mensagem entregue é dinâmica; a Meta cobra esse preço máximo ou menos pela entrega.
* Destinatários diferentes no mesmo envio podem ter preços reais de mensagem diferentes.
* Mensagens que não são entregues não geram cobrança de entrega.
* Um Max Price afeta o lance e a oportunidade de entrega, mas não garante a entrega. Os resultados reais também podem ser afetados por lances em tempo real, status do destinatário e verificações de elegibilidade da Meta.
### 2.4 O que é a ferramenta de estimativa de alcance?
A Ferramenta de Estimativa de Alcance ajuda as empresas a selecionar um Max Price adequado. Antes de enviar, as empresas podem usar o endpoint de estimativa para visualizar o volume de entrega estimado e a faixa de custo em diferentes níveis de Max Price, escolhendo então uma estratégia de preços com base nos objetivos e no orçamento da campanha.
As estimativas são fornecidas apenas para fins de planejamento e não garantem resultados reais de entrega ou valores finais de faturamento. Os resultados reais podem ser afetados por lances em tempo real, status do destinatário e verificações de elegibilidade da Meta.
## 3. Fluxo de integração recomendado
1. Chame `reachEstimate` antes de enviar para comparar o desempenho estimado em diferentes níveis de preço.
2. Configure o Max Price no nível de modelo por meio de `bidSpec` ao criar o modelo de marketing.
3. Opcionalmente, passe `per_message_bid_multiplier` ao enviar uma mensagem para ajustar o Max Price para um destinatário individual.
## 4. Criar um modelo com Max Price
### 4.1 Endpoint
Adicione um objeto `bidSpec` ao criar um modelo de mensagem de marketing.
* Endpoint: [https://api.ycloud.com/v2/whatsapp/templates](https://api.ycloud.com/v2/whatsapp/templates)
* Caso de uso: Definir um Max Price no nível de modelo ao criar um modelo de marketing
### 4.2 Parâmetros da requisição
O objeto `bidSpec` contém os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `maxBid` | string | Obrigatório se `bidSpec` for fornecido | Preço máximo permitido pelo modelo. A moeda padrão é a moeda de cobrança da sua conta YCloud.
|
| `countryPriceAdjustments` | string | Não | Mapeamento do país de destino para um multiplicador de lance. Os países que você não listar usam um multiplicador de `1.0` (o `maxBid` sem modificação).
Até 50 entradas.
Até 50 entradas. |
| `countryPriceAdjustments.countryCode` | string | Obrigatório se `countryPriceAdjustments` for fornecido | As chaves devem ser códigos de país ISO 3166-1 alfa-2 válidos (por exemplo, `MX`, `IN`, `BR`). |
| `countryPriceAdjustments.multiplier` | string | Obrigatório se `countryPriceAdjustments` for fornecido | Cada multiplicador deve ser maior que `0` e no máximo `10`. |
### 4.3 Exemplo de requisição
```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 Regras
* `maxBid` deve ser maior que `0` e pode ser menor que a tarifa publicada.
* Se `bidSpec` for omitido, o modelo usará os preços padrão da tarifa publicada.
### 4.5 Exemplo de resposta
Após a criação do modelo, a resposta inclui o objeto do modelo e sua configuração 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. Atualizar o Max Price em um modelo
### 5.1 Endpoint
Adicione um objeto `bidSpec` ao atualizar um modelo de mensagem 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 o Max Price
### 5.2 Parâmetros da requisição e exemplo
Consulte [Criar um modelo com Max Price](#4-create-a-template-with-max-price)
## 4. Criar um modelo com Max Price
### 5.3 Regras
* Você não pode adicionar `bidSpec` a um modelo existente que foi criado sem ele. Você deve criar um novo modelo com `bidSpec` incluído.
* **Modelos aprovados**: até 100 edições por hora, 2.400 por dia. As edições de conteúdo ainda seguem o limite existente de 1 por dia e 10 a cada 30 dias.
* **Modelos rejeitados ou pausados**: edições ilimitadas
## 6. Definir um multiplicador de lance por mensagem ao enviar uma mensagem
### 6.1 Endpoint
Adicione um objeto `bidSpec` ao enviar uma mensagem diretamente.
* Endpoint: [https://api.ycloud.com/v2/whatsapp/messages/sendDirectly](https://api.ycloud.com/v2/whatsapp/messages/sendDirectly)
* Caso de uso: Ajustar o Max Price efetivo para um destinatário individual
### 6.2 Parâmetros da requisição
O objeto `bidSpec` no nível de mensagem contém o seguinte campo:
| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `per_message_bid_multiplier` | string | Condicional | Multiplicador aplicado ao Max Price efetivo no nível do modelo para esta mensagem. Deve ser maior que 0 e aceita até três casas decimais. Se `bidSpec` for incluído na requisição, este campo será obrigatório. Para usar o multiplicador padrão de `1`, omita todo o objeto `bidSpec`. |
### 6.3 Exemplo de requisição
```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 Regras
* `per_message_bid_multiplier` deve ser maior que 0 e aceita até três casas decimais. Um valor maior que 1 aumenta o Max Price efetivo, enquanto um valor entre 0 e 1 o diminui.
* O multiplicador se aplica apenas a um modelo de marketing que tenha o Max Price habilitado por meio de `bidSpec`.
* Se a requisição da mensagem contiver um objeto `bidSpec`, `per_message_bid_multiplier` será obrigatório. Para usar o multiplicador padrão de `1`, omita todo o objeto `bidSpec`.
### 6.5 Resposta
O endpoint de envio continua usando a resposta padrão de mensagem do WhatsApp. Passar `bidSpec` não introduz uma estrutura de resposta separada.
Quando o status retornado for `accepted`, `totalPrice` será um preço estimado e não a cobrança 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. Cobranças finais e Webhooks de status de mensagem
### 7.1 Evento de Webhook
A YCloud envia o evento de Webhook `whatsapp.message.updated` quando o status de uma mensagem do WhatsApp é alterado. Para mensagens enviadas usando Max Price, o webhook identifica o modo de precificação e fornece a cobrança final após a entrega da mensagem.
| Campo | Novo campo/valor | Descrição |
| - | - | - |
| `bidPricingFlag` | Novo campo | Booleano. `true` indica que a mensagem foi enviada usando a precificação Max Price; `false` indica a precificação padrão da tarifa publicada |
| `pricingCategory` | Novo valor | Mensagens de marketing com Max Price usam `marketing_lite_bidding` |
| `totalPrice` | Campo existente | Preço dinâmico da mensagem. O valor pode variar por destinatário. Ele se torna a cobrança final quando o status da mensagem for `delivered` ou `read` |
### 7.2 Exemplo de payload de 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*******"
}
}'
```
Neste exemplo:
* `totalPrice` é a cobrança final porque o status da mensagem é `delivered` ou `read`.
* `pricingCategory: marketing_lite_bidding` identifica a categoria de precificação do Max Price.
* `bidPricingFlag: true` confirma que a mensagem foi enviada usando a precificação Max Price.
## 8. Estimar entrega e custo antes de enviar
### 8.1 Endpoint
* Endpoint: `GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate`
* Caso de uso: use o endpoint de estimativa de alcance antes de enviar para ver os intervalos estimados de entrega e custo em diferentes níveis de preço.
### 8.2 Parâmetros da requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `wabaId` | string | Sim | ID da conta do WhatsApp Business |
| `targetCountry` | string | Sim | Código do país de destino. As chaves devem ser códigos de país ISO 3166-1 alfa-2 válidos (por exemplo, `MX`, `IN`, `BR`).. As chaves devem ser códigos de país ISO 3166-1 alfa-2 válidos (por exemplo, `MX`, `IN`, `BR`). |
| `dateInterval` | string | Não | Período de análise histórica dos dados usados para gerar as estimativas. Um de: `L1D` (último 1 dia), `L7D` (últimos 7 dias), `L14D` (últimos 14 dias), `L28D` (últimos 28 dias).
Padrão `L28D` |
Exemplo de requisição:
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D
```
### 8.3 Estrutura da resposta
| Campo | Tipo | Descrição |
| - | - | - |
| `waba_currency` | string | Moeda da WABA |
| `estimates` | array | Lista de níveis de preço estimados |
| `dateInterval` | string | Período de análise histórica dos dados usados para gerar as estimativas |
Cada item em `estimates` contém:
| Campo | Tipo | Descrição |
| - | - | - |
| `bid_amount` | number | Valor máximo que a empresa está disposta a pagar por um lote de 1.000 destinatários |
| `users` | number | Número de destinatários-alvo; atualmente fixado em `1000` |
| `deliveries_lower_bound` | string | Número mínimo estimado de mensagens entregues por 1.000 destinatários |
| `deliveries_upper_bound` | string | Número máximo estimado de mensagens entregues por 1.000 destinatários |
| `cost_lower_bound` | number | Custo mínimo estimado para o lote |
| `cost_upper_bound` | number | Custo máximo estimado para o lote |
### 8.4 Exemplo de resposta
```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
}
]
}
```
Interpretação:
1. Quando o Preço Máximo por mensagem é `395 / 1000 USD = USD 0.395`, um lote de 1.000 destinatários tem uma faixa estimada de taxa de entrega de `4.8% to 23.4%` e uma faixa estimada de custo de aproximadamente `USD 344.46 to USD 396`.
2. Quando o Preço Máximo por mensagem é `495 / 1000 USD = USD 0.495`, um lote de 1.000 destinatários tem uma faixa estimada de taxa de entrega de `6.3% to 26.3%` e uma faixa estimada de custo de aproximadamente `USD 353.067 to USD 429.597`.
## Perguntas Frequentes
### Posso saber o preço real de entrega para um destinatário específico antes do envio?
Não. O preço de entrega para cada destinatário é dinâmico e não pode ser conhecido com antecedência. A empresa só precisa definir o preço máximo que está disposta a pagar. Uma mensagem entregue com sucesso é cobrada pelo seu preço real de entrega, que não excederá o Preço Máximo em vigor.
### Por que os resultados reais de entrega diferem da estimativa?
O endpoint de estimativa fornece apenas valores de referência. Os resultados reais podem ser afetados por lances em tempo real, status do destinatário e verificações de qualificação da Meta. Se a diferença for significativa, entre em contato com a YCloud para obter assistência.
### A cobrança real será retornada após a entrega de uma mensagem?
Sim. Quando o status da mensagem for `delivered` ou `read`, `totalPrice` representa a cobrança final com base no preço real de entrega do destinatário. Quando a mensagem é inicialmente aceita ou seu status for `sent`, a YCloud retorna um preço estimado em vez da cobrança final.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.