1. Visão geral
Para ajudar as empresas a obterem maior controle e otimizarem 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 Preço Máximo (Max Price) e a Ferramenta de estimativa de alcance (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 Preço Máximo é definido, a Meta cobra esse valor ou menos por cada mensagem entregue. Antes do envio, as empresas também podem usar a Ferramenta de estimativa de alcance para entender o volume de entrega estimado 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 (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 mensagens
- Estimar o volume de entrega e o custo em diferentes níveis de Preço Máximo (Max Price) antes do envio
2. Conceitos principais
2.1 O que é o Preço Máximo (Max Price)?
Um 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 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 Preço Máximo no mesmo nível, abaixo ou acima da tarifa publicada pela Meta:
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 todas as mensagens entregues serão cobradas por esse valor. 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 Definindo 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 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 Preço Máximo 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 Preço Máximo 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 Preço Máximo no nível do modelo será de USD 0,10.
Preço Máximo efetivo = maxBid do modelo x countryPriceAdjustments.multiplier do modelo x per_message_bid_multiplier
maxBid: "0.1" em USD, multiplicadores por país de 0.8 para a Índia e 1.3 para a Malásia produzem estes tetos de preço efetivos:
Os valores usam a sua moeda de cobrança da YCloud. Países sem substituição usam um multiplicador de
1. Omita todo o objeto bidSpec no nível da mensagem para usar um multiplicador por mensagem de 1.
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 Preço Máximo configurado no modelo representa apenas o valor máximo que a empresa está disposta a pagar.
- A cobrança final por uma mensagem de entrega é dinâmica; a Meta cobra por esse preço máximo ou inferior pela entrega.
- Destinatários diferentes no mesmo envio podem ter preços reais de mensagem diferentes.
- Mensagens que não forem entregues não geram cobrança de entrega.
- Um Preço Máximo 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 Preço Máximo 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 Preço Máximo e, em seguida, escolher uma estratégia de preços com base nos objetivos da campanha e no orçamento. As estimativas são fornecidas apenas para fins de planejamento e não garantem resultados reais de entrega nem 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
reachEstimateantes do envio para comparar o desempenho estimado em diferentes níveis de preço. - Configure o Preço Máximo no nível do modelo por meio de
bidSpecao criar o modelo de marketing. - Opcionalmente, passe
per_message_bid_multiplierao enviar uma mensagem para ajustar o Preço Máximo para um destinatário individual.
4. Criar um modelo com Preço Máximo
4.1 Endpoint
Adicione um objetobidSpec ao criar um modelo de mensagem de marketing.
- Endpoint: https://api.ycloud.com/v2/whatsapp/templates
- Caso de uso: definir um Preço Máximo no nível do modelo ao criar um modelo de marketing
4.2 Parâmetros da requisição
O objetobidSpec contém os seguintes campos:
4.3 Exemplo de requisição
4.4 Regras
- Apenas modelos de
MARKETINGoferecem suporte ao Preço Máximo. maxBidpode ser inferior à taxa publicada. Envie valores e multiplicadores como strings decimais, não como números JSON.- Se
bidSpecfor omitido, o modelo usará os preços padrão da taxa publicada. - Criar um modelo com
bidSpec: {}é inválido. Forneça ummaxBidválido ao criar combidSpec.
4.5 Exemplo de resposta
Depois que o modelo for criado, a resposta incluirá o objeto do modelo e sua configuração debidSpec.
5. Adicionar, atualizar ou limpar o Preço Máximo
5.1 Endpoint
UsePATCH /v2/whatsapp/templates/{wabaId}/{name}/{language} para editar um modelo de marketing, incluindo um criado sem Preço Máximo.
5.2 Escolher o comportamento de edição
Um objeto cujas propriedades sejam todas
null, como {"maxBid": null, "countryPriceAdjustments": null}, também limpa as configurações. Strings vazias, arrays vazios e outras propriedades não nulas não contam como uma configuração vazia. Por exemplo, {"countryPriceAdjustments": []} sem um maxBid válido é inválido.
Para adicionar ou atualizar o Preço Máximo, use os campos em Criar um modelo com Preço Máximo. Inclua a lista completa de países que você deseja armazenar. A lista enviada substitui a lista armazenada localmente; omiti-la ou enviar uma lista vazia não limpa explicitamente as substituições de países já armazenadas pela Meta. Para remover todas as configurações de lances, envie bidSpec: {}.
Inclua todos os componentes que deseja manter. O exemplo a seguir limpa a configuração de lances e mantém o corpo:
5.3 Regras
- Adicionar, atualizar e limpar o Preço Máximo segue o fluxo existente de edição de modelos e validação da Meta. Apenas modelos no status
APPROVED,REJECTEDouPAUSEDpodem ser editados. - Forneça os componentes que deseja manter mesmo quando alterar apenas a precificação. Uma edição bem-sucedida segue o fluxo existente de revisão e sincronização de status.
- Após uma limpeza bem-sucedida, a resposta do modelo não contém mais um objeto
bidSpec. Se a Meta ou a persistência local falhar, o endpoint retornará um erro.
6. Definir um multiplicador de lance por mensagem ao enviar uma mensagem
6.1 Endpoint
Adicione um objetobidSpec no nível da mensagem a qualquer um dos endpoints de envio:
POST /v2/whatsapp/messages/sendDirectlyenvia a mensagem de forma síncrona.POST /v2/whatsapp/messagesenfileira a mensagem para processamento assíncrono.
sendDirectly não seleciona por si só o produto separado Utility ou Authentication Direct Send.
6.2 Parâmetros da requisição
O objetobidSpec no nível da mensagem contém o seguinte campo:
6.3 Exemplo de requisição
6.4 Regras
-
per_message_bid_multiplierdeve ser maior que0e no máximo999.999, com no máximo três casas decimais. Um valor maior que1aumenta o Preço Máximo efetivo, enquanto um valor entre0e1o diminui. -
O multiplicador se aplica apenas a um modelo de marketing que tenha o Preço Máximo ativado por meio de
bidSpec. -
Se a requisição da mensagem contiver um objeto
bidSpec,per_message_bid_multiplierserá obrigatório. Ao contrário de uma edição de modelo,bidSpec: {}na mensagem é inválido. Para usar o multiplicador padrão de1, omita todo o objetobidSpec.
6.5 Resposta
O endpoint de envio continua a usar a resposta padrão de mensagem do WhatsApp. PassarbidSpec não introduz uma estrutura de resposta separada.
Quando o status retornado for accepted, totalPrice será um preço estimado. Neste exemplo, o destinatário nos EUA não tem substituição de país, portanto 0.05 x 1 x 1.1 = 0.055 USD. Use o webhook de entregue/lido para a cobrança final.
7. Cobranças finais e Webhooks de status de mensagem
7.1 Evento de Webhook
A YCloud envia o evento de Webhookwhatsapp.message.updated quando o status de uma mensagem do WhatsApp é alterado. Para mensagens enviadas usando Preço Máximo, o webhook identifica o modo de precificação e fornece a cobrança final após a entrega da mensagem.
7.2 Exemplo de payload de webhook
totalPriceé a cobrança final porque o status da mensagem édeliveredouread.pricingCategory: marketing_lite_biddingidentifica a categoria de precificação com Preço Máximo.bidPricingFlag: trueconfirma que a mensagem foi enviada usando a precificação por Preço Máximo.
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 os intervalos estimados de entrega e custo em diferentes níveis de preço.
8.2 Parâmetros da requisição
Exemplo de requisição:
8.3 Estrutura de resposta
Cada item em
estimates contém:
8.4 Exemplo de resposta
- Quando o Max Price por mensagem for
395 / 1000 USD = USD 0.395, um lote de 1.000 destinatários terá uma faixa de taxa de entrega estimada de4.8% to 23.4%e uma faixa de custo estimada de aproximadamenteUSD 344.46 to USD 396. - Quando o Max Price por mensagem for
495 / 1000 USD = USD 0.495, um lote de 1.000 destinatários terá uma faixa de taxa de entrega estimada de6.3% to 26.3%e uma faixa de custo estimada de aproximadamenteUSD 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 Max Price vigente.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.O valor cobrado real será retornado após a entrega de uma mensagem?
Sim. Quando o status da mensagem fordelivered ou read, totalPrice representará a cobrança final com base no preço real de entrega do destinatário. Quando a mensagem for aceita inicialmente ou seu status for sent, a YCloud retornará um preço estimado em vez da cobrança final.
