Skip to main content

UC-017 — Connect Social Profiles

FieldValue
IDUC-017
GoalView connected social profiles and monitor token status
ChannelWhatsApp, Facebook Messenger, Instagram
ComplexityBasic
Estimated time5 minutes
APIs involvedGET /api/v1/partner-gateway/socials, GET /api/v1/partner-gateway/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://lora-api.agiletelecom.com/api/v1/partner-gateway/socials \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Connected profiles​

{
  "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 Expired tokens If a profile shows status: "TOKEN_EXPIRED", messages to that channel will fail. Renew the token 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 refresh: For Facebook and Instagram, the gateway attempts an automatic token refresh 7 days before expiration. If the refresh fails, the status changes to TOKEN_EXPIRING.
  3. Expiration: When the token expires, the status becomes TOKEN_EXPIRED and API calls for that channel return 503 Service Unavailable.
  4. WhatsApp: WhatsApp Business profiles use a persistent connection (not based on tokens with expiration), but can show DISCONNECTED in case of issues with the Business API provider.

Step 2 — Details for a specific platform​

Query a single platform to get advanced details.

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

Response — Facebook details​

{
  "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 Check permissions The permissions field indicates the granted OAuth permissions. To send Messenger messages, at least pages_messaging is required. :::

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: If during the connection 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 /socialsList of all profiles with status and token expiry
2GET /socials/{platform}Platform details with permissions and last activity

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

# 2. Check expiring tokens (next 30 days)
echo "=== Expiring Tokens ==="
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. Facebook detail for audit
echo "=== Facebook Details ==="
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}'

Variants​

Automatic token monitoring with alerts​

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

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

Common errors​

401 Unauthorized — Invalid API Key​

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

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

404 Not Found — Platform not connected​

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

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

Next steps​

References​