Il report settimanale per il cliente, scritto da un agente ogni lunedì prima che tu ti svegli

Un agente può scrivere il report settimanale di distribuzione di un cliente prendendo tre cose da Shager: i post pubblicati nella settimana con l'esito per ogni account, i clic per account e per post da get_analytics, e l'elenco di tutto ciò che è fallito. Poi incrocia quei clic con i contatti del CRM del cliente usando il valore utm_content che identifica ogni account. Fallo girare in modo programmato con una chiave di sola lettura, e il lunedì mattina il report ti aspetta in una cartella.

La parte che richiede riflessione non è il codice. È decidere cosa il cliente ha davvero bisogno di vedere, ed essere onesti su cosa misurano i numeri.

Cosa deve contenere un report settimanale di distribuzione?

Bastano quattro sezioni. Tutto il resto va nella revisione mensile.

1. Consegna. Quanti post sono usciti, su quanti account, e quali account hanno avuto problemi. I clienti raramente lo chiedono finché qualcosa non manca all'appello, e da quel momento è l'unica cosa che chiedono.
2. Clic per account. Quali pagine, filiali o canali hanno portato persone sul sito. È la sezione che sposta i budget.
3. Clic per post. Quali contenuti hanno funzionato, su tutti gli account.
4. Azioni. Cosa deve fare il cliente: ricollegare un account, approvare le bozze della settimana successiva, inviare i materiali mancanti.

Nota cosa manca: copertura, impression, like. Shager misura i clic sui propri link tracciati, per account e per post. Non pretende di essere una suite di analytics per i social, e il report non deve far finta del contrario.

Scorri di lato per vedere tutto il diagramma

Le chiamate per i dati

Per il workspace di un cliente, l'agente esegue questa sequenza. I nomi sono quelli reali degli strumenti MCP; gli equivalenti REST sono nel documento OpenAPI.

1. list_workspaces per trovare per nome il workspace del cliente.
2. list_posts con status impostato su PUBLISHED, poi di nuovo con PARTIALLY_PUBLISHED e FAILED. limit arriva fino a 100.
3. get_post per ogni post della settimana, per ottenere lo stato per account, gli URL pubblicati e i messaggi di errore.
4. get_analytics con from e to che coprono la settimana.
5. list_channels, per associare gli ID dei canali a nomi di account leggibili e individuare gli account il cui stato di collegamento è cambiato.

La chiamata agli analytics via REST:

curl -s "https://app.shager.ai/api/v1/workspaces/ws_example/analytics?from=2026-09-14T00:00:00%2B03:00&to=2026-09-20T23:59:59%2B03:00" \
  -H "Authorization: Bearer $SHAGER_READ_KEY"

In quell'URL ci sono due dettagli in cui si inciampa spesso. Il + dell'offset va codificato come %2B in una query string, altrimenti il server lo legge come uno spazio. E i confini della settimana vanno calcolati nel fuso orario del cliente, non in quello del server. Se from viene omesso, get_analytics usa per default gli ultimi 30 giorni, che non è ciò che serve a un report settimanale.

I clic non sono contatti: incrociali

Shager assegna a ogni account il proprio link breve e i propri tag UTM, con utm_content che identifica l'account. È questo che rende possibile l'incrocio. Il CRM registra i contatti con i valori UTM raccolti dal modulo della landing page; l'agente li abbina ai clic per account di Shager sullo stesso utm_content.

La tabella che ne risulta è il cuore del report:

Account	Post	Clic (Shager)	Contatti (CRM)	Nota
Aurora Downtown	4	...	...
Aurora Northside	4	...	...	da ricollegare

Le differenze tra le colonne sono già un'informazione. Tanti clic e nessun contatto indicano un problema di landing page o di offerta, non di distribuzione. La nostra guida precedente sull'attribuzione dei contatti per account spiega i campi del modulo e la mappatura nel CRM che rendono affidabile la colonna dei contatti, mentre misurare i contatti generati dai contenuti degli agenti affronta il lato dell'agente.

Se non hai accesso al CRM, il report funziona anche solo con i clic. Scrivilo nell'intestazione. Un report che chiama i clic «risultati» è il modo in cui le agenzie perdono la fiducia del cliente un trimestre dopo.

Farlo girare senza supervisione con Claude Code

Claude Code può funzionare in modo non interattivo con claude -p, come descritto nella sua documentazione sulla modalità headless. Così il report settimanale diventa un cron job.

Prima di tutto, una cartella di progetto per i report con un .mcp.json che legge la chiave dall'ambiente. La documentazione MCP di Claude Code supporta l'espansione ${VAR} negli header:

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_READ_KEY}" }
    }
  }
}

Poi le istruzioni, salvate come skill, così la logica vive in un file e non in una riga di crontab. Claude Code carica le skill di progetto da .claude/skills/<name>/SKILL.md, come spiega la sua documentazione sulle skill:

---
name: weekly-report
description: Compile the weekly distribution report for one client workspace from Shager. Use when asked for a weekly client report.
---

The argument is the client workspace name: $ARGUMENTS

1. Resolve the workspace with list_workspaces. Read its timezone.
2. Compute last Monday 00:00 to Sunday 23:59:59 in that timezone, with offsets.
3. Collect posts with list_posts (PUBLISHED, PARTIALLY_PUBLISHED, FAILED) and
   keep those published in the window. Call get_post for each.
4. Call get_analytics for the window. Map channel ids to names with list_channels.
5. If crm/<workspace>.csv exists, join leads on utm_content.
6. Write reports/<workspace>/<YYYY-MM-DD>.md with four sections: Delivery,
   Clicks by account, Clicks by post, Actions. Use tables. No adjectives about
   performance; numbers and one plain sentence per section.
7. Never call any tool that creates, schedules or cancels anything.

E il comando programmato, che pre-approva solo gli strumenti di lettura e la scrittura dei file:

cd ~/agency-reports && claude -p "/weekly-report Aurora" \
  --allowedTools "mcp__shager__list_*,mcp__shager__get_*,mcp__shager__whoami,Write" \
  --output-format json > logs/aurora-$(date +%F).json

La sintassi delle regole di autorizzazione con il prefisso mcp__<server>__ e un carattere jolly finale è documentata nel riferimento sui permessi di Claude Code. Tutto ciò che non è in quell'elenco non viene approvato automaticamente in un'esecuzione senza supervisione.

Scorri di lato per vedere tutto il diagramma

Perché qui conta una chiave di sola lettura

La skill dice al modello di non scrivere. La chiave lo rende impossibile. Crea nella dashboard degli agenti una chiave separata, solo con l'ambito read, dedicata ai report, e non usarla da nessun'altra parte. Se un giorno quella chiave finisse in mani sbagliate, il danno peggiore sarebbe che qualcuno legga dei conteggi di clic. Il modello completo degli ambiti è spiegato in chiavi API, ambiti e registro.

Ogni chiamata dell'agente che compila i report compare anche nel registro di quella dashboard: un buon modo per verificare, nei primi lunedì, che chiami ciò che ti aspetti e nient'altro.

Scrivere la parte di commento

Lascia che l'agente scriva una o due frasi per sezione, ma con dei vincoli. Senza regole, i modelli descrivono una variazione del 4 per cento come «un aumento significativo». La mia istruzione è secca: indica il numero, confrontalo con la settimana precedente se disponibile, e non dire nulla sulle cause a meno che i dati non le mostrino. Se la pagina di una filiale ha avuto zero clic perché il suo collegamento è scaduto martedì, quella è una causa che i dati mostrano. La «stanchezza del pubblico» no.

Domande frequenti

L'agente può inviare il report direttamente al cliente?

Può farlo se gli dai uno strumento per le email, ma io non lo farei dal primo giorno. Fagli scrivere il file, rivedi qualche settimana di risultati, poi automatizza l'invio. Il report è il modo in cui il cliente vede il tuo lavoro, e un numero sbagliato inviato in automatico costa più del tempo risparmiato.

get_analytics include i contatti?

No. Restituisce i clic sui link tracciati di Shager, per account e per post, in un intervallo di date. I contatti arrivano dal CRM o dallo strumento per i moduli del cliente, abbinati su utm_content. Il report deve tenere le due fonti ben separate anche visivamente.

Quanto indietro può guardare il report?

get_analytics accetta qualsiasi from e to tu gli passi, con un default degli ultimi 30 giorni quando from è omesso. Per i confronti mese su mese, esegui la stessa skill con un intervallo diverso invece di usare i report passati come fonte di verità.

Da dove partire

Se non hai ancora una chiave, il punto di accesso per agenti mostra come crearne una o come lasciare che un agente si registri da solo. Comincia con un cliente, leggi tu stesso i report di tre lunedì, e solo dopo aggiungi tutti gli altri.