Custos e consumo

Preço por mensagem entregue, franquia de serviço, consumo do mês e como aplicar o preço.

A Meta cobra por mensagem entregue do negócio para o contato; mensagem que não chega a delivered não é cobrada. O hub não calcula valor: repassa o que a Meta informa e conta o nível gratuito.

Campos de preço. O pricing do whatsapp.message.status (source: "meta") vem no sent e em um de delivered/read:

Campo	Valores
`category`	`service`, `group_service`, `utility`, `marketing`, `marketing_lite`, `authentication`, `authentication-international`, `referral_conversion`, `group_marketing`, `group_utility` (como a Meta manda; trate valor novo como desconhecido)
`type`	`regular` (cobrada), `free_customer_service` (serviço 1:1 dentro do nível gratuito), `free_group_customer_service` (serviço de grupo dentro do nível gratuito) ou `free_entry_point` (grátis por estar numa janela de ponto de entrada gratuito); trate outro valor como desconhecido
`subtype`	`paid_exempt` para conta de governo ou sem fins lucrativos isenta
`billable`	Obsoleto na Meta; decida por `type`
`model`	Modelo de preço, como a Meta manda

Observado em testes com o app real: reação enviada pelo hub recebeu só o status sent, sem pricing; texto, interativo e imagem vieram com category: "service" e type: "free_customer_service".

Nível gratuito de serviço. Desde 01/10/2026 a mensagem de serviço (resposta livre, sem template) volta a ser cobrada, com 1.000 mensagens de serviço entregues grátis por número por mês. Não acumula e vira à meia-noite no fuso da conta de mensagens na Meta. Template de utilidade dentro da janela de atendimento também passou a ser cobrado (type: "regular").

GET /v1/connections/:connectionId/usage → { "usage": { ... } }:

{
  "month": "2026-10",
  "timezone": "America/Sao_Paulo",
  "limit": 1000,
  "delivered": 812,
  "free": 812,
  "charged": 0,
  "remaining": 188,
  "exhausted": false
}

delivered: mensagens de serviço entregues no mês, cada uma contada uma vez (pelo primeiro delivered ou read com category: "service"). free são as de type: "free_customer_service", charged as de type: "regular"; uma de serviço com outro type (como free_entry_point) conta em delivered e em nenhum dos dois, então delivered pode passar de free + charged. exhausted fica true com a primeira cobrada ou com free em 1.000; remaining é 0 quando exhausted, senão limit - free.
Mês. Vira à meia-noite no fuso da conta de mensagens, lido da Meta (timezone, nome IANA); conta cujo fuso a Meta não informou usa o padrão do hub (America/Sao_Paulo).
Aproximação. Os status ficam 30 dias no hub: no dia 31 o primeiro dia do mês já pode ter saído e a conta fica menor que a real. A conta é por conexão, e a Meta conta por número: se o número veio de outro workspace no meio do mês, a contagem recomeça do zero aqui e o aviso de 800 pode não sair. Mensagem de serviço de grupo (group_service) desconta da mesma franquia na Meta, mas não entra nesta conta. A fonte da verdade é a fatura da Meta.

O evento whatsapp.usage.free_tier avisa sem consulta:

{
  "phoneNumberId": "109876543210987",
  "month": "2026-10",
  "timezone": "America/Sao_Paulo",
  "level": "warning",
  "limit": 1000,
  "free": 800,
  "charged": 0
}

level é warning ao chegar a 800 gratuitas e exhausted na primeira mensagem de serviço cobrada. Cada nível sai uma vez por número e mês.

Método de pagamento. Passadas as 1.000 gratuitas, sem método de pagamento válido a Meta não entrega mensagens de serviço. O envio recusado na hora sai failed com errorCode: "payment_method_required" (Meta 131042); recusado depois do aceite, o whatsapp.message.status failed traz 131042 em errors.

Janela de ponto de entrada gratuito (FEP). Quando o contato escreve por um anúncio Click-to-WhatsApp (Android/iOS) e o negócio responde dentro da janela de atendimento, a resposta é grátis e abre uma janela de até 7 dias em que marketing, utilidade, autenticação e serviço saem grátis (mensagem do Meta Business Agent continua cobrada). O hub lê o fim dela de conversation.expiration_timestamp (só vem no sent) e devolve em freeEntryPoint.expiresAt no GET …/windows. Ela só muda o preço: mensagem livre continua exigindo a janela de 24 h, e fora dela só template.

Consumo do mês. GET /v1/connections/:connectionId/consumption?month=YYYY-MM (sem month, o mês corrente; aceita o corrente e os 12 anteriores, no fuso da conta; fora disso, 400 CONSUMPTION_MONTH_OUT_OF_RANGE) → { "consumption": { ... } }:

{
  "month": "2026-10",
  "timezone": "America/Sao_Paulo",
  "currency": "BRL",
  "hub": [
    { "category": "marketing", "type": "regular", "delivered": 1 },
    { "category": "service", "type": "free_customer_service", "delivered": 1 },
    { "category": "utility", "type": "regular", "delivered": 1 }
  ],
  "meta": {
    "fetchedAt": "2026-10-23T18:06:32.265Z",
    "items": [
      { "category": "MARKETING", "type": "REGULAR", "country": "BR", "tier": "0:MAX", "volume": 1 },
      { "category": "SERVICE", "type": "FREE_CUSTOMER_SERVICE", "country": "BR", "tier": null, "volume": 1 },
      { "category": "UTILITY", "type": "REGULAR", "country": "BR", "tier": "0:250000", "volume": 1 }
    ]
  }
}

hub: contado dos status de entrega desta conexão, cada mensagem uma vez (pelo primeiro delivered ou read com pricing), por category e type como o webhook manda (minúsculas). Só o que passou pela conexão, e só 30 dias (retenção dos status).
meta: o pricing_analytics da Meta para o número da conexão, lido todo dia às 6:00 (mês corrente e anterior), por categoria, tipo, país e faixa de volume, como a Meta manda (maiúsculas; AUTHENTICATION_INTERNATIONAL corresponde a authentication-international do webhook). Inclui o que o hub não vê (mensagens mandadas pelo app no Coexistence). A Meta avisa que o dado é aproximado e pode diferir da fatura. Número que veio de outro workspace do hub mostra só a partir do dia seguinte ao da troca. null antes da primeira leitura.
tier (<inferior>:<superior>, ou null em mensagem grátis) é a faixa de volume do par país e categoria: existe só para utilidade e autenticação; marketing vem 0:MAX. A faixa não chega pelo webhook.
currency é a moeda de cobrança da conta na Meta (null enquanto a Meta não informa).
O preço é do app. O hub não lê o custo em dinheiro: o token da conexão lê o volume, mas a Meta recusa o custo (permissão). Para estimar, multiplique cada linha de meta.items com type: "REGULAR" pelo preço da tabela da Meta para o país, a categoria e a faixa, na moeda da conta; os tipos grátis valem zero. A tabela muda só no início de cada trimestre (1º de janeiro, abril, julho e outubro), com aviso de 1 mês.

Como gastar menos.

Uma mensagem em vez de várias: cada balão entregue conta. Junte o texto que sairia em sequência.
Mídia com caption em vez de mídia seguida de texto.
Resposta de agente de IA num balão só, sem quebrar em frases.