Skip to main content

UC-017 — Connect Social Profiles

FieldValue
IDUC-017
GoalView connected social profiles and monitor token status
ChannelFacebook, Instagram, LinkedIn, Google, TikTok
ComplexityBasic
Estimated time5 minutes
APIs involvedGET /api/partner-gateway/v1/socials, GET /api/partner-gateway/v1/socials/{platform}

Real-world scenarios​

  • View Facebook pages: The social media manager at BrandCo checks which Facebook pages are connected for sending messages via Messenger.
  • Monitor tokens: The DevOps team sets up an automatic check that verifies the validity of connected OAuth tokens and prevents service interruptions.
  • Profile audit: Before go-live, the technical lead runs an audit of all connected social profiles to ensure they are the correct ones.

Query flow​

The diagram shows the two main queries: general listing and per-platform details.

Prerequisites​

  • Active API Key with social profile read permissions
  • At least one social profile connected via the Qlara dashboard
  • Valid OAuth token for the platform of interest

Step 1 — List all connected social profiles​

Retrieve the full list of social profiles associated with your account.

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

Response — Connected profiles​

[
  {
    "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
  }
]
Expired tokens

If a profile shows disconnected: true, its OAuth token has expired or been revoked: messages to that channel will fail. Reconnect the profile from the Qlara dashboard.

Behind the scenes — Social token management
  1. OAuth flow: Connecting a social profile is done via OAuth 2.0 from the dashboard. The gateway saves the access token in encrypted form.
  2. Token expiry: In GET /socials/{platform}, each page reports in expireDate when its token expires; null means that no expiry date is recorded.
  3. Disconnection: When a token expires or is revoked, the profile (or the single page) shows disconnected: true and stays that way until you reconnect it from the dashboard.
  4. WhatsApp: WhatsApp Business numbers are not social profiles and do not appear here: list them with GET /whatsapp/phone-numbers.

Step 2 — Details for a specific platform​

Query a single platform to get advanced details.

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

Response — Facebook details​

{
  "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
    }
  ]
}
Check the pages

Each entry in pages has its own disconnected flag and expireDate: check them page by page, not only on the profile.

Behind the scenes — OAuth permissions and scopes
  1. Facebook Messenger: Requires pages_messaging to send messages and pages_read_engagement to read metrics.
  2. Instagram: Requires instagram_basic and instagram_manage_messages for direct messaging.
  3. Minimum scopes: The scopes are granted during the connection from the dashboard and are not returned by this API. If the user does not grant all required scopes, some features will be limited.
  4. Scope renewal: To add missing permissions, you need to disconnect and reconnect the profile from the dashboard.

Expected result​

StepActionResult
1GET /socialsArray of profiles with the disconnected flag and pageCount
2GET /socials/{platform}Platform details with its pages, each with expireDate and disconnected

Complete end-to-end example​

Scenario DevOps BrandCo: social profile health check script.

# 1. Retrieve all profiles
echo "=== Social Profiles ==="
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. Profiles to reconnect (token expired or revoked)
echo "=== Disconnected Profiles ==="
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. Facebook detail for audit
echo "=== Facebook Details ==="
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}'

Variants​

Automatic token monitoring with alerts​

Integrate the check into a job that notifies the team when a token is about to expire:

# Check Facebook pages with tokens expiring within 7 days
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 Facebook pages with expiring tokens!"
fi

Common errors​

401 Unauthorized — Invalid API Key​

{
  "error": "Invalid API Key"
}

Solution: Verify that the X-Api-Key header is present and the key is active.

404 Not Found — Platform not connected​

GET /socials/{platform} answers 404 with an empty body when no profile is connected for that platform (for example GET /socials/telegram).

Solution: The requested platform has no connected profiles. Connect one from the Qlara dashboard or verify the correct platform name (facebook, instagram, linkedin, google, tiktok).

Next steps​

References​