UC-017 — Collegare Profili Social

Campo	Valore
ID	UC-017
Obiettivo	Visualizzare i profili social collegati e monitorare lo stato dei token
Canale	Facebook, Instagram, LinkedIn, Google, TikTok
Complessità	Base
Tempo stimato	5 minuti
API coinvolte	GET /api/partner-gateway/v1/socials, GET /api/partner-gateway/v1/socials/{platform}

Scenari reali

• Visualizzare pagine Facebook: Il social media manager di BrandCo verifica quali pagine Facebook sono collegate per l'invio di messaggi tramite Messenger.
• Monitorare token: Il team DevOps configura un check automatico che verifica la validita dei token OAuth collegati ed evita interruzioni di servizio.
• Audit profili: Prima del go-live, il responsabile tecnico esegue un audit di tutti i profili social collegati per assicurarsi che siano quelli corretti.

Flusso di consultazione

Il diagramma mostra le due query principali: lista generale e dettaglio per piattaforma.

Prerequisiti

• API Key attiva con permessi di lettura profili social
• Almeno un profilo social collegato tramite la dashboard Qlara
• Token OAuth valido per la piattaforma di interesse

Step 1 — Elenca tutti i profili social collegati

Recupera la lista completa dei profili social associati al tuo account.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/socials \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Profili collegati

[
  {
    "platform": "facebook",
    "username": "marco.bianchi.brandco",
    "profileName": "Marco Bianchi",
    "profilePicture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/marco-bianchi-profile.jpg",
    "connectionDate": "2026-01-10 13:30:00.000+0000",
    "disconnected": false,
    "pageCount": 2
  },
  {
    "platform": "linkedin",
    "username": "brandco",
    "profileName": "BrandCo",
    "profilePicture": "https://media.licdn.com/dms/image/brandco-logo.png",
    "connectionDate": "2026-02-20 08:00:00.000+0000",
    "disconnected": false,
    "pageCount": 1
  },
  {
    "platform": "instagram",
    "username": "brandco_official",
    "profileName": "BrandCo",
    "profilePicture": "https://scontent.cdninstagram.com/v/brandco-official-profile.jpg",
    "connectionDate": "2025-12-01 09:00:00.000+0000",
    "disconnected": true,
    "pageCount": 1
  }
]

Token scaduti

Se un profilo mostra disconnected: true, il suo token OAuth è scaduto o è stato revocato: i messaggi verso quel canale falliranno. Ricollega il profilo dalla dashboard Qlara.

Dietro le quinte — Gestione dei token social

1. OAuth flow: Il collegamento di un profilo social avviene tramite OAuth 2.0 dalla dashboard. Il gateway salva il token di accesso in forma cifrata.
2. Scadenza del token: In GET /socials/{platform}, ogni pagina indica in expireDate quando scade il suo token; null significa che non è registrata una data di scadenza.
3. Disconnessione: Quando un token scade o viene revocato, il profilo (o la singola pagina) risulta disconnected: true e resta così finché non lo ricolleghi dalla dashboard.
4. WhatsApp: I numeri WhatsApp Business non sono profili social e non compaiono qui: elencali con GET /whatsapp/phone-numbers.

Step 2 — Dettaglio di una piattaforma specifica

Interroga una singola piattaforma per ottenere dettagli avanzati.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/socials/facebook \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Dettaglio Facebook

{
  "platform": "facebook",
  "username": "marco.bianchi.brandco",
  "profileName": "Marco Bianchi",
  "profilePicture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/marco-bianchi-profile.jpg",
  "website": null,
  "biography": null,
  "linksCount": null,
  "connectionDate": "2026-01-10 13:30:00.000+0000",
  "disconnected": false,
  "pages": [
    {
      "pageId": "104857392018475",
      "pageName": "BrandCo Official",
      "profilePicture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/brandco-official-page.jpg",
      "username": "brandco.official",
      "website": "https://www.brandco.it",
      "biography": "Moda e accessori made in Italy.",
      "linksCount": null,
      "connectionDate": "2026-01-10 13:31:05.000+0000",
      "expireDate": "2026-06-15 00:00:00.000+0000",
      "disconnected": false
    },
    {
      "pageId": "118204736591024",
      "pageName": "BrandCo Outlet",
      "profilePicture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/brandco-outlet-page.jpg",
      "username": "brandco.outlet",
      "website": "https://outlet.brandco.it",
      "biography": "Le occasioni BrandCo tutto l'anno.",
      "linksCount": null,
      "connectionDate": "2026-01-10 13:31:05.000+0000",
      "expireDate": null,
      "disconnected": false
    }
  ]
}

Verifica le pagine

Ogni elemento di pages ha il proprio flag disconnected e la propria expireDate: controllali pagina per pagina, non solo sul profilo.

Dietro le quinte — Permessi e scopes OAuth

1. Facebook Messenger: Richiede pages_messaging per inviare messaggi e pages_read_engagement per leggere le metriche.
2. Instagram: Richiede instagram_basic e instagram_manage_messages per la messaggistica diretta.
3. Scopes minimi: Gli scopes vengono concessi durante il collegamento dalla dashboard e non sono restituiti da questa API. Se l'utente non concede tutti gli scopes richiesti, alcune funzionalità risulteranno limitate.
4. Rinnovo scopes: Per aggiungere permessi mancanti, e necessario scollegare e ricollegare il profilo dalla dashboard.

Risultato atteso

Step	Azione	Risultato
1	GET /socials	Array dei profili con il flag disconnected e pageCount
2	GET /socials/{platform}	Dettaglio della piattaforma con le sue pages, ognuna con expireDate e disconnected

Esempio completo end-to-end

Scenario DevOps BrandCo: script di health check dei profili social.

# 1. Recupera tutti i profili
echo "=== Profili Social ==="
curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/socials \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.[] | {platform, profileName, disconnected}'

# 2. Profili da ricollegare (token scaduto o revocato)
echo "=== Profili disconnessi ==="
curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/socials \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.[] | select(.disconnected == true) | {platform, profileName, connectionDate}'

# 3. Dettaglio Facebook per audit
echo "=== Dettaglio Facebook ==="
curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/socials/facebook \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.pages[] | {pageName, expireDate, disconnected}'

Varianti

Monitoraggio automatico token con alert

Integra il check in un job che notifica il team quando un token sta per scadere:

# Controlla le pagine Facebook con token in scadenza entro 7 giorni
EXPIRING=$(curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/socials/facebook \
  -H "X-Api-Key: YOUR_API_KEY" | jq '[.pages[] | select(.expireDate != null and (.expireDate[0:10] | strptime("%Y-%m-%d") | mktime) < (now + 7 * 86400))] | length')

if [ "$EXPIRING" -gt 0 ]; then
  echo "ALERT: $EXPIRING pagine Facebook con token in scadenza!"
fi

Errori comuni

401 Unauthorized — API Key non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e la chiave sia attiva.

404 Not Found — Piattaforma non collegata

GET /socials/{platform} risponde 404 con body vuoto quando per quella piattaforma non è collegato alcun profilo (ad esempio GET /socials/telegram).

Soluzione: La piattaforma richiesta non ha profili collegati. Collegane uno dalla dashboard Qlara o verifica il nome corretto della piattaforma (facebook, instagram, linkedin, google, tiktok).

Prossimi passi

• UC-018 — Gestire l'Inbox: Gestisci le conversazioni ricevute sui canali social
• UC-003 — Invio WhatsApp Template: Invia messaggi WhatsApp dai tuoi numeri WhatsApp Business
• UC-014 — API Key Management: Gestisci le chiavi di accesso

Riferimenti

• API Reference — Socials