Passa al contenuto principale

UC-017 — Collegare Profili Social

CampoValore
IDUC-017
ObiettivoVisualizzare i profili social collegati e monitorare lo stato dei token
CanaleWhatsApp, Facebook Messenger, Instagram
ComplessitàBase
Tempo stimato5 minuti
API coinvolteGET /api/v1/partner-gateway/socials, GET /api/v1/partner-gateway/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://lora-api.agiletelecom.com/api/v1/partner-gateway/socials \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Profili collegati​

{
  "profiles": [
    {
      "platform": "facebook",
      "profileId": "fb_page_123456",
      "name": "BrandCo Official",
      "status": "CONNECTED",
      "tokenExpiresAt": "2026-06-15T00:00:00+02:00",
      "connectedAt": "2026-01-10T14:30:00+01:00"
    },
    {
      "platform": "whatsapp",
      "profileId": "wa_biz_789012",
      "name": "BrandCo WhatsApp Business",
      "status": "CONNECTED",
      "phoneNumber": "+393491234567",
      "connectedAt": "2026-02-20T09:00:00+01:00"
    },
    {
      "platform": "instagram",
      "profileId": "ig_345678",
      "name": "brandco_official",
      "status": "TOKEN_EXPIRED",
      "tokenExpiresAt": "2026-03-01T00:00:00+01:00",
      "connectedAt": "2025-12-01T10:00:00+01:00"
    }
  ],
  "total": 3
}

:::warning Token scaduti Se un profilo mostra status: "TOKEN_EXPIRED", i messaggi verso quel canale falliranno. Rinnova il token 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. Token refresh: Per Facebook e Instagram, il gateway tenta un refresh automatico del token 7 giorni prima della scadenza. Se il refresh fallisce, lo stato passa a TOKEN_EXPIRING.
  3. Scadenza: Quando il token scade, lo stato diventa TOKEN_EXPIRED e le chiamate API per quel canale restituiscono 503 Service Unavailable.
  4. WhatsApp: I profili WhatsApp Business usano una connessione persistente (non basata su token con scadenza), ma possono risultare DISCONNECTED in caso di problemi con il Business API provider.

Step 2 — Dettaglio di una piattaforma specifica​

Interroga una singola piattaforma per ottenere dettagli avanzati.

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

Response — Dettaglio Facebook​

{
  "platform": "facebook",
  "profiles": [
    {
      "profileId": "fb_page_123456",
      "name": "BrandCo Official",
      "pageId": "1234567890",
      "category": "E-commerce",
      "status": "CONNECTED",
      "tokenExpiresAt": "2026-06-15T00:00:00+02:00",
      "permissions": ["pages_messaging", "pages_read_engagement"],
      "connectedAt": "2026-01-10T14:30:00+01:00",
      "lastActivityAt": "2026-04-09T12:00:00+02:00"
    }
  ]
}

:::tip Verifica i permessi Il campo permissions indica i permessi OAuth concessi. Per inviare messaggi Messenger, e necessario almeno pages_messaging. :::

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: Se durante il collegamento l'utente non concede tutti gli scopes richiesti, alcune funzionalita risulteranno limitate.
  4. Rinnovo scopes: Per aggiungere permessi mancanti, e necessario scollegare e ricollegare il profilo dalla dashboard.

Risultato atteso​

StepAzioneRisultato
1GET /socialsLista di tutti i profili con stato e scadenza token
2GET /socials/{platform}Dettaglio della piattaforma con permessi e ultima attivita

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://lora-api.agiletelecom.com/api/v1/partner-gateway/socials \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.profiles[] | {platform, name, status}'

# 2. Verifica token in scadenza (prossimi 30 giorni)
echo "=== Token in scadenza ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/socials \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.profiles[] | select(.status == "TOKEN_EXPIRED" or .status == "TOKEN_EXPIRING") | {platform, name, tokenExpiresAt}'

# 3. Dettaglio Facebook per audit
echo "=== Dettaglio Facebook ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/socials/facebook \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.profiles[] | {name, permissions, lastActivityAt}'

Varianti​

Monitoraggio automatico token con alert​

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

# Controlla profili con token in scadenza entro 7 giorni
EXPIRING=$(curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/socials \
  -H "X-Api-Key: YOUR_API_KEY" | jq '[.profiles[] | select(.status == "TOKEN_EXPIRING")] | length')

if [ "$EXPIRING" -gt 0 ]; then
  echo "ALERT: $EXPIRING profili 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​

{
  "status": "fail",
  "data": {
    "platform": "No connected profiles found for platform: telegram"
  }
}

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

Prossimi passi​

Riferimenti​