Felo API PlatformFelo API Platform

Contenuti

Trasforma le conversazioni social in un brief settimanale di ascolto

Cerca i post X dell’ultima settimana su brand e concorrenti, aggiungi contesto web con fonti, leggi le pagine dietro e archivia ogni edizione perché la settimana dopo parta da ciò che si sa.

Tempo25 minutiLivelloIntermedioAggiornato2026-10-30
Per chiBrand e comunicazioneProduct marketingGestione community

Copia il prompt

Sostituisci i campi tra parentesi quadre e incolla in Claude Code, Codex o qualsiasi IA con accesso al terminale. Installa lo skill Felo, chiede prima di spendere crediti ed esegue il workflow.

Esegui un brief di social listening per [brand, prodotto o categoria].

Termini monitorati: [brand], [nome prodotto], [nomi concorrenti], [parole chiave categoria].
Finestra: ultimi [7 / 14] giorni. Fuso orario: [fuso]. Pubblico: [team].
Fonti consentite: solo post pubblici su X e pagine web pubbliche.

Produci:
1. Un riepilogo in cinque righe di cosa è cambiato nella conversazione.
2. Temi, ciascuno con ciò che dicono le persone, i post che lo sostengono e l’intervallo di date coperto.
3. Menzioni dei concorrenti: chi viene consigliato e in quale contesto.
4. Rischi: lamentele, disservizi, domande ripetute o reazioni negative.
5. Prossimi passi, divisi in «rispondere ora», «osservare» e «passare al prodotto».
6. Un elenco di fonti con ogni post e pagina, URL e data.

Regole:
- Riporta solo post e pagine restituiti dall’API. Non inventare mai punteggi di sentiment, numeri di engagement, citazioni o fonti.
- Tratta X come segnale, non come sondaggio rappresentativo. Dillo quando il campione è troppo piccolo per concludere.
- Separa le parole del cliente dal tuo riepilogo e cita brevemente con link.
- Trasforma la finestra in date esplicite di inizio e fine e indica il fuso.
- Prima di consumare crediti, mostra le ricerche ed estrazioni previste e attendi la mia approvazione.
- Non rispondere, pubblicare, seguire né scrivere a nessuno. Questo brief è in sola lettura.
- Scrivi il risultato in ./social-listening.md e riassumilo in chat.

La copia include anche i passaggi di installazione e le regole di sicurezza.

Cosa ottieni

Output di esempio di un'esecuzione. Non è generazione dal vivo.

Esempio di brief (estratto)

Brief di social listening — 2026-10-30

Cosa è cambiato

  • Le lamentele sul flusso di esportazione sono ora il tema principale.
  • Un rivale più economico viene consigliato nei thread sui prezzi.
  • Il disservizio del 2026-10-27 non viene più menzionato.

Temi

  1. Esportazioni lente dall’aggiornamento — @example_dev: «Il pulsante esporta ora impiega minuti per un documento di 40 pagine.» (2026-10-28); @example_ops: «Altri vedono esportazioni in coda a fine mese?» (2026-10-29)
  2. Viene consigliata un’alternativa più economica — Example Rival appare nei thread in cui si chiede un prezzo più basso

Concorrenti

Example Rival viene consigliato quando si chiede un’alternativa più economica; il consiglio riguarda il prezzo, non le funzioni.

Rischi

La lamentela sull’esportazione appare in thread vicini al supporto e può arrivare alle conversazioni di abbandono.

Prossimi passi

  • Rispondere ora: il thread export del 2026-10-28.
  • Osservare: se la lamentela si estende al pubblico API.
  • Passare al prodotto: latenza di esportazione a fine mese.

Fonti

  • https://x.com/example_dev/status/... — 2026-10-28
  • https://example.com/export-thread — 2026-10-29

Le chiamate esatte

Per gli sviluppatori: lo stesso workflow come codice, nell'ordine di esecuzione.

Mostra le chiamate API reali
  1. Cerca i post della settimana

    Usa X Search per brand e concorrenti negli ultimi 7 giorni, conservando account e date.

    listening.ts
    const BASE = "https://openapi.felo.ai";
    const headers = {
      Authorization: `Bearer ${process.env.FELO_API_KEY}`,
      "Content-Type": "application/json",
    };
    
    async function felo<T>(path: string, body?: unknown): Promise<T> {
      const res = await fetch(`${BASE}${path}`, {
        method: body ? "POST" : "GET",
        headers,
        body: body ? JSON.stringify(body) : undefined,
      });
      if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
      return res.json() as Promise<T>;
    }
    
    type XData = {
      data: {
        tweets: {
          content: string;
          author: { username: string };
          created_at: string;
          metrics: { retweet_count: number; favorite_count: number; reply_count: number };
          url: string;
        }[];
      };
    };
    
    const since = Math.floor((Date.now() - 7 * 24 * 60 * 60 * 1000) / 1000);
    
    const search = await felo<XData>("/v2/x/tweet/search", {
      query: '"Acme" OR "Acme app"',
      limit: 50,
      since_time: since,
    });
    
    const posts = search.data.tweets;

    Output di esempio

    { "data": { "tweets": [
      {
        "content": "The export flow is slow again.",
        "author": { "username": "example_dev" },
        "created_at": "2026-10-28T09:14:00Z",
        "metrics": { "retweet_count": 4, "favorite_count": 21, "reply_count": 6 },
        "url": "https://x.com/example_dev/status/..."
      }
    ] } }
  2. Aggiungi contesto web con fonti

    Chiedi a Chat il contesto delle discussioni e ottieni un elenco di pagine con fonti.

    listening.ts
    type ChatData = {
      data: {
        answer: string;
        resources: { link: string; title: string; snippet: string }[];
      };
    };
    
    const context = await felo<ChatData>("/v2/chat", {
      query: "Recent customer complaints and competitor mentions around Acme",
    });
    
    const sources = context.data.resources.slice(0, 5);

    Output di esempio

    {
      "answer": "The main threads are …",
      "sources": [
        { "link": "https://example.com/thread", "title": "…", "snippet": "…" }
      ]
    }
  3. Leggi le pagine dietro

    Con Web Fetch leggi le due o tre pagine più rilevanti e aggiungi fatti e link.

    listening.ts
    type ExtractData = { data: { content: string } };
    
    const pages = await Promise.all(
      sources.slice(0, 3).map((source) =>
        felo<ExtractData>("/v2/web/extract", {
          url: source.link,
          output_format: "markdown",
          with_readability: true,
          with_cache: true,
        }).then((page) => ({ ...source, content: page.data.content })),
      ),
    );

    Output di esempio

    // pages[0].content
    "# Example thread summary\n\nExtracted page content…"
  4. Scrivi il report per tema

    Componi un Markdown con temi, post rappresentativi, contesto, rischi e punti di attenzione.

    listening.ts
    const date = new Date().toISOString().slice(0, 10);
    
    const ranked = [...posts].sort(
      (a, b) => b.metrics.favorite_count - a.metrics.favorite_count,
    );
    
    const brief = [
      `# Social listening brief — ${date}`,
      "",
      "## What the web says",
      context.data.answer,
      "",
      "## What people are posting",
      ...ranked.slice(0, 10).map(
        (post) =>
          `- @${post.author.username} (${post.created_at.slice(0, 10)}): ${post.content}\n  ${post.url}`,
      ),
      "",
      "## Pages behind the answer",
      ...pages.map((page) => `- [${page.title}](${page.link})`),
      "",
      "## Sources",
      ...sources.map((source) => `- [${source.title}](${source.link})`),
    ].join("\n");
    
    console.log(brief);
  5. Archivia e confronta con la settimana prima

    Salva report e fonti nel LiveDoc e la settimana dopo consulta l’edizione precedente.

    listening.ts
    type LiveDocData = { data: { short_id: string } };
    
    const archive = await felo<LiveDocData>("/v2/livedocs", {
      name: "Social listening archive",
      description: "One document resource per weekly brief",
    });
    
    await felo(`/v2/livedocs/${archive.data.short_id}/resources/doc`, {
      title: `Social listening — ${date}`,
      content: brief,
    });
    
    type Retrieved = { data: { title: string; content: string; score: number }[] };
    
    const previous = await felo<Retrieved>(
      `/v2/livedocs/${archive.data.short_id}/resources/retrieve`,
      { query: "what changed since last week" },
    ).then((res) => res.data.filter((hit) => hit.score >= 0.7));

    Output di esempio

    [
      { "title": "Social listening — 2026-10-23", "content": "…", "score": 0.88 }
    ]

Cosa include

  • Post X datati della settimana
  • Contesto web con fonti
  • Riepilogo delle discussioni per tema
  • Report settimanale pronto da condividere
  • LiveDoc con ogni edizione

Cosa non fa

  • La copertura X è incompleta e non rappresenta tutti gli utenti
  • Nessuna conclusione definitiva sul sentiment
  • Non pubblica né risponde automaticamente
  • Niente DM o community private
  • Un’esecuzione a settimana; la pianificazione spetta al tuo agent o cron

Domande

Cosa conta come fonte?

Ogni post X conserva link, account e data; il contesto web viene da pagine pubbliche Chat e Web Fetch. Le affermazioni senza fonte non entrano.

Posso seguire i concorrenti?

Sì. Cerca brand e concorrenti insieme e raggruppali nel report.

Misura il sentiment?

Riassume temi e tono, ma lo marca come giudizio editoriale e non dichiara una percentuale esatta.

Quanto indietro guarda?

Per impostazione predefinita gli ultimi 7 giorni per il report settimanale; per una finestra più ampia cambia `since_time`.

Posso eseguirlo ogni settimana?

Sì. Metti lo stesso prompt in cron o in uno scheduler agent e scrivi nello stesso LiveDoc.

Quanto costa un brief?

X Search, Chat ed estrazione sono a consumo; le tariffe sono nella pagina prezzi e il prompt chiede approvazione prima di spendere.

Workflow correlati

Adattala a te

La stessa ricetta, adattata a come lavori davvero.

Solo un argomento

Restringi a un lancio o a una polemica per focalizzare il brief.

Aggiungi opinioni YouTube

Integra con una trascrizione video, ma marca come esperienza personale.

Trasformalo in mensile

Passa a frequenza mensile per brand e PR.

Le pagine di riferimento dietro questa ricetta e i prossimi passi.