Guia de integração do Preço Máximo

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 Marketing Messages em 2026, incluindo o Preço Máximo e a Ferramenta de estimativa de alcance. 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 Preço Máximo é definido, a Meta cobra esse valor ou menos por cada mensagem entregue. Antes de enviar, as empresas também podem usar a Ferramenta de estimativa de alcance para entender o volume estimado de entrega e o custo em diferentes níveis de Preço Máximo. Este guia explica como usar a API da YCloud para:

Definir um Preço Máximo e um Multiplicador por país em um modelo de mensagem de marketing
Opcionalmente, aplicar um multiplicador por mensagem ao enviar uma mensagem
Obter a cobrança final por meio de webhooks de status de mensagem
Estimar o volume de entrega e o custo em diferentes níveis de Preço Máximo antes do envio

2. Conceitos principais

2.1 O que é o Preço Máximo?

O Preço Máximo é o valor máximo que uma empresa está disposta a pagar por cada mensagem de marketing do WhatsApp entregue com sucesso. Quando um Preço Máximo é definido, a Meta cobra esse valor ou menos pela entrega. A cobrança real não excederá o limite de preço configurado. Dependendo do objetivo de uma campanha de marketing, a empresa pode definir seu Preço Máximo no mesmo valor, abaixo ou acima da taxa publicada pela Meta:

Estratégia de preços	Objetivo	Resultado esperado
Igual à taxa publicada	Controlar custos mantendo taxas de entrega semelhantes às campanhas existentes no WhatsApp	Custos potencialmente mais baixos, mantendo um nível de entrega semelhante
Inferior à taxa publicada	Alcançar grupos adequados de clientes a um custo menor	Reduzir o preço máximo aceitável por mensagem, embora o volume de entrega possa mudar de acordo
Superior à 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 entrega de mais mensagens

O Preço Máximo é um teto de preço, não uma cobrança fixa. Definir um Preço Máximo 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 Preço Máximo configurado.

2.2 Como definir o Preço Máximo

2.2.1 Como definir o Preço Máximo em um modelo Você pode definir um Preço Máximo fixo (maxBid) para um modelo e configurar diferentes multiplicadores (countryPriceAdjustments.multiplier) para diferentes países ou regiões. Por exemplo, suponha que o maxBid seja 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 Preço Máximo no nível do modelo será USD 0,10 × 0,8 = USD 0,08.
Quando o modelo for usado para enviar uma mensagem para a Malásia, o Preço Máximo no nível do modelo será USD 0,10 × 1,3 = USD 0,13.
Quando o modelo for enviado para qualquer outro país, o Preço Máximo no nível do modelo será USD 0,10.

2.2.2 Ajustando o multiplicador ao enviar uma mensagem de modelo Ao enviar uma mensagem usando um modelo com Preço Máximo, você pode aplicar um multiplicador por mensagem maior que 0 para aumentar ou diminuir o Preço Máximo efetivo para uma mensagem individual. 2.2.3 Calcular o Preço Máximo efetivo

Preço Máximo efetivo = maxBid do modelo x countryPriceAdjustments.multiplier do modelo x per_message_bid_multiplier

Exemplo: Você criou um modelo, e as configurações de Preço Máximo no nível do modelo são as seguintes

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

Então, há 4 destinatários; você envia para eles com diferentes multiplicadores por mensagem**,** e os Preços Máximos efetivos são calculados da seguinte forma:

Destinatários	Multiplicador por mensagem aplicado	País	Preço Máximo 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 por 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 nã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 Reach Estimation Tool?

A Reach Estimation Tool ajuda as empresas a selecionar um Max Price adequado. Antes de enviar, as empresas podem usar o endpoint de estimativa para visualizar o volume estimado de entrega e a faixa de custo em diferentes níveis de Max Price, escolhendo então uma estratégia de preços com base em seus objetivos de campanha e orçamento. As estimativas são fornecidas apenas para fins de planejamento e não garantem resultados reais de entrega ou valores finais de cobrança. 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

Chame reachEstimate antes do envio para comparar o desempenho estimado em diferentes níveis de preço.
Configure o Max Price em nível de modelo por meio de bidSpec ao criar o modelo de marketing.
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
Caso de uso: Definir um Max Price em 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 YCloud.
`countryPriceAdjustments`	string	Não	Mapeamento do país de destino para um multiplicador de lance. Países que você não listar usam um multiplicador de `1.0` (o `maxBid` não modificado). 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

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 da tarifa padrão 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.

{
  "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 um 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}
Caso de uso: Ajustar o max price

5.2 Parâmetros da requisição e exemplo

Consulte Criar um modelo com Max Price

4. Criar um modelo com Max Price

5.3 Regras

Você não pode adicionar bidSpec a um modelo existente criado sem ele. É necessário criar um novo modelo incluindo bidSpec.
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
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 da 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 de modelo para esta mensagem. Deve ser maior que 0 e aceita até três casas decimais. Se `bidSpec` for incluído na solicitação, este campo é obrigatório. Para usar o multiplicador padrão de `1`, omita todo o objeto `bidSpec`.

6.3 Exemplo de solicitação

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 solicitação de 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 utilizando 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 em vez da cobrança 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. Cobranças finais e Webhooks de status de mensagem

7.1 Evento de Webhook

O YCloud envia o evento de webhook whatsapp.message.updated quando o status de uma mensagem do WhatsApp é alterado. Para mensagens enviadas usando o 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 por Max Price; `false` indica a precificação padrão por tarifa pública
`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 de acordo com o destinatário. Torna-se a cobrança final quando o status da mensagem for `delivered` ou `read`

7.2 Exemplo de payload do 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*******"
    }
  }'

Neste exemplo:

totalPrice é a cobrança final porque o status da mensagem é deliveredouread.
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 por Max Price.

8. Estimar a entrega e o custo antes do envio

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 faixas estimadas de entrega e custo em diferentes níveis de preço.

8.2 Parâmetros da solicitaçã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 retrospectiva dos dados históricos usados para gerar estimativas. Um destes: `L1D` (último 1 dia), `L7D` (últimos 7 dias), `L14D` (últimos 14 dias), `L28D` (últimos 28 dias). Padrão `L28D`

Exemplo de solicitação:

GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D

8.3 Estrutura de 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 retrospectiva para os dados históricos usados para gerar 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; fixado atualmente 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

{
  "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:

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 de custo estimado de aproximadamente USD 344.46 to USD 396.
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 de custo estimado 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 efetivo.

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 elegibilidade 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 da 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 é sent, a YCloud retorna um preço estimado em vez da cobrança final.

​1. Visão geral

​2. Conceitos principais

​2.1 O que é o Preço Máximo?

​2.2 Como definir o Preço Máximo

​2.3 Regras de cobrança dinâmica

​2.4 O que é a Reach Estimation Tool?

​3. Fluxo de integração recomendado

​4. Criar um modelo com Max Price

​4.1 Endpoint

​4.2 Parâmetros da requisição

​4.3 Exemplo de requisição

​4.4 Regras

​4.5 Exemplo de resposta

​5. Atualizar um Max Price em um modelo

​5.1 Endpoint

​5.2 Parâmetros da requisição e exemplo

​4. Criar um modelo com Max Price

​5.3 Regras

​6. Definir um multiplicador de lance por mensagem ao enviar uma mensagem

​6.1 Endpoint

​6.2 Parâmetros da requisição

​6.3 Exemplo de solicitação

​6.4 Regras

​6.5 Resposta

​7. Cobranças finais e Webhooks de status de mensagem

​7.1 Evento de Webhook

​7.2 Exemplo de payload do Webhook

​8. Estimar a entrega e o custo antes do envio

​8.1 Endpoint

​8.2 Parâmetros da solicitação

​8.3 Estrutura de resposta

​8.4 Exemplo de resposta

​Perguntas Frequentes

​Posso saber o preço real de entrega para um destinatário específico antes do envio?

​Por que os resultados reais de entrega diferem da estimativa?

​A cobrança real será retornada após a entrega da mensagem?

1. Visão geral

2. Conceitos principais

2.1 O que é o Preço Máximo?

2.2 Como definir o Preço Máximo

2.3 Regras de cobrança dinâmica

2.4 O que é a Reach Estimation Tool?

3. Fluxo de integração recomendado

4. Criar um modelo com Max Price

4.1 Endpoint

4.2 Parâmetros da requisição

4.3 Exemplo de requisição

4.4 Regras

4.5 Exemplo de resposta

5. Atualizar um Max Price em um modelo

5.1 Endpoint

5.2 Parâmetros da requisição e exemplo

4. Criar um modelo com Max Price

5.3 Regras

6. Definir um multiplicador de lance por mensagem ao enviar uma mensagem

6.1 Endpoint

6.2 Parâmetros da requisição

6.3 Exemplo de solicitação

6.4 Regras

6.5 Resposta

7. Cobranças finais e Webhooks de status de mensagem

7.1 Evento de Webhook

7.2 Exemplo de payload do Webhook

8. Estimar a entrega e o custo antes do envio

8.1 Endpoint

8.2 Parâmetros da solicitação

8.3 Estrutura de resposta

8.4 Exemplo de resposta

Perguntas Frequentes

Posso saber o preço real de entrega para um destinatário específico antes do envio?

Por que os resultados reais de entrega diferem da estimativa?

A cobrança real será retornada após a entrega da mensagem?