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:

Definir um Max Price 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 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

Chame reachEstimate antes de enviar para comparar o desempenho estimado em diferentes níveis de preço.
Configure o Max Price no 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 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

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.

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

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.

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

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:

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

{
  "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 estimada de custo 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 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.

​1. Visão geral

​2. Conceitos fundamentais

​2.1 O que é o Max Price?

​2.2 Como definir o Max Price

​2.3 Regras de cobrança dinâmica

​2.4 O que é a ferramenta de estimativa de alcance?

​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 o 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 requisiçã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 de Webhook

​8. Estimar entrega e custo antes de enviar

​8.1 Endpoint

​8.2 Parâmetros da requisição

​8.3 Estrutura da 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 de uma mensagem?

1. Visão geral

2. Conceitos fundamentais

2.1 O que é o Max Price?

2.2 Como definir o Max Price

2.3 Regras de cobrança dinâmica

2.4 O que é a ferramenta de estimativa de alcance?

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 o 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 requisiçã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 de Webhook

8. Estimar entrega e custo antes de enviar

8.1 Endpoint

8.2 Parâmetros da requisição

8.3 Estrutura da 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 de uma mensagem?