Saltar para o conteúdo principal

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:
  1. Definir um Preço Máximo (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 mensagens
  4. 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.
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 de 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: Para um modelo com 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

  1. Chame reachEstimate antes do envio para comparar o desempenho estimado em diferentes níveis de preço.
  2. Configure o Preço Máximo no nível do 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 Preço Máximo para um destinatário individual.

4. Criar um modelo com Preço Máximo

4.1 Endpoint

Adicione um objeto bidSpec ao criar um modelo de mensagem de marketing.

4.2 Parâmetros da requisição

O objeto bidSpec contém os seguintes campos:

4.3 Exemplo de requisição

4.4 Regras

  • Apenas modelos de MARKETING oferecem suporte ao Preço Máximo.
  • maxBid pode ser inferior à taxa publicada. Envie valores e multiplicadores como strings decimais, não como números JSON.
  • Se bidSpec for omitido, o modelo usará os preços padrão da taxa publicada.
  • Criar um modelo com bidSpec: {} é inválido. Forneça um maxBid válido ao criar com bidSpec.

4.5 Exemplo de resposta

Depois que o modelo for criado, a resposta incluirá o objeto do modelo e sua configuração de bidSpec.

5. Adicionar, atualizar ou limpar o Preço Máximo

5.1 Endpoint

Use PATCH /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, REJECTED ou PAUSED podem 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 objeto bidSpec no nível da mensagem a qualquer um dos endpoints de envio:
  • POST /v2/whatsapp/messages/sendDirectly envia a mensagem de forma síncrona.
  • POST /v2/whatsapp/messages enfileira a mensagem para processamento assíncrono.
Use o multiplicador com um modelo de marketing com Preço Máximo enviado por meio do Marketing Messages Lite. Chamar o endpoint sendDirectly não seleciona por si só o produto separado Utility ou Authentication Direct Send.

6.2 Parâmetros da requisição

O objeto bidSpec no nível da mensagem contém o seguinte campo:

6.3 Exemplo de requisição

6.4 Regras

  • per_message_bid_multiplier deve ser maior que 0 e no máximo 999.999, com no máximo três casas decimais. Um valor maior que 1 aumenta o Preço Máximo efetivo, enquanto um valor entre 0 e 1 o 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_multiplier será obrigatório. Ao contrário de uma edição de modelo, bidSpec: {} na mensagem é inválido. Para usar o multiplicador padrão de 1, omita todo o objeto bidSpec.

6.5 Resposta

O endpoint de envio continua a usar 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. 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 Webhook whatsapp.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

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 com Preço Máximo.
  • bidPricingFlag: true confirma 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

Interpretação:
  1. 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 de 4.8% to 23.4% e uma faixa de custo estimada de aproximadamente USD 344.46 to USD 396.
  2. 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 de 6.3% to 26.3% e uma faixa de custo estimada 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 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 for delivered 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.