> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Usage & Cost Monitor

> Stima l'utilizzo dei template consegnati su WhatsApp e la spesa Meta a partire dai dati di messaggistica di Switchbord.

# Meta Usage & Cost Monitor

Switchbord ora espone due superfici correlate relative all'utilizzo Meta:

* **Insights → Billing** (`/insights`, scheda Billing) — legge i campi `pricing_analytics` e `analytics` della WABA Meta e li inserisce in tabelle di rollup giornaliere locali, mostrando poi messaggi inviati/consegnati, consegne per categoria, ripartizione tra traffico gratuito e a pagamento, e i costi totali approssimativi nella valuta della WABA.
* **Settings → Usage** (`/settings/usage`) — una vista di stima operativa basata sui dati di messaggistica di Switchbord e sull'attribuzione delle campagne.

<Info>
  I totali di utilizzo Meta sono stime operative. Le fatture Meta, gli export di billing e gli strumenti di billing Meta a livello di account restano la fonte di verità per la liquidazione dei conti.
</Info>

## Cosa mostra Insights → Billing

* **Messaggi inviati / consegnati** — dal campo `analytics` della WABA.
* **Consegnati per categoria** — dalle righe di categoria di `pricing_analytics` come `MARKETING`, `UTILITY`, `AUTHENTICATION` e `SERVICE`.
* **Gratuito vs a pagamento** — ripartisce le righe `FREE_CUSTOMER_SERVICE`, `FREE_ENTRY_POINT` e quelle a pagamento `REGULAR`.
* **Costi totali approssimativi** — somma calcolata da `pricing_analytics.cost` nella valuta della WABA.

## Cosa mostra Settings → Usage

* **Costo Meta stimato** — calcolato dai messaggi template consegnati e dalla tabella tariffaria configurata.
* **Template consegnati** — consegne di template fatturabili per le categorie marketing, utility e authentication.
* **Tasso di lettura** — eventi di lettura divisi per messaggi template consegnati per la finestra selezionata.
* **Messaggi gratuiti** — traffico freeform in entrata e traffico nella finestra di servizio, contati separatamente dalla consegna di template a pagamento.
* **Andamento della spesa** — costo stimato giornaliero insieme al volume di template consegnati.
* **Costo per categoria** — categorie marketing, utility, authentication e service.
* **Attribuzione per campagna** — volume di template consegnati, tasso di lettura e costo stimato per ogni campagna.

## Finestre temporali

La dashboard supporta tre finestre:

* `7d` — ultimi sette giorni.
* `30d` — ultimi trenta giorni.
* `MTD` — mese in corso ad oggi.

Switchbord recupera ogni finestra separatamente lato server, così le etichette delle schede non ri-etichettano lo stesso dataset.

## Fonti dei dati

Il monitor legge dati con ambito workspace da:

* `messaging_events` quando gli eventi includono già status, categoria, paese e metadati di campagna.
* `messages`, `templates`, `contacts` e `campaign_recipients` come fallback, così i workspace esistenti possono continuare a stimare l'utilizzo mentre vengono introdotti payload di eventi di messaggistica più ricchi.

Ogni query è delimitata dal `workspace_id` risolto dalla sessione autenticata dell'operatore.

## Modello di pricing

Switchbord segue lo schema di pricing dei template consegnati adottato da Meta dopo luglio 2025:

* I messaggi template consegnati possono essere fatturabili.
* Il traffico freeform nella finestra di servizio viene contato separatamente.
* Le tariffe variano in base alla categoria del template e al paese/regione del prefisso di chiamata del destinatario.

<Warning>
  L'implementazione iniziale include una tabella tariffaria operativa per le stime. Mantieni la tabella tariffaria versionata e riconciliala con gli export di billing Meta prima di usare questi numeri per la fatturazione o per il pass-through di fatturazione ai clienti.
</Warning>

## Attribuzione delle campagne

Le righe di campagna sono derivate da `campaign_recipients.message_id` e dallo stato di consegna dei messaggi. Usa questa vista per identificare quale campagna turistica, flusso di re-engagement o promemoria di prenotazione sta guidando la spesa Meta attuale.

## Prossimi passi

* Importare una tabella tariffaria Meta completa e versionata per paese/prefisso di chiamata e data di validità.
* Aggiungere una riconciliazione esplicita degli export di billing rispetto alle fatture Meta.
* Memorizzare payload di stato più ricchi al momento della scrittura dell'evento di messaggistica, così i join di fallback potranno essere ridotti nel tempo.
* Aggiungere l'export CSV per le revisioni finance e customer success.