Connecting Accounts

Before you can publish, a social account has to be connected to a workspace. There are two ways to connect, and a small set of endpoints to keep accounts healthy afterward.

Connecting someone else’s accounts - an end-customer of your product? Use a Profile connect link: a hosted, single-use page they open with no SmartlyQ login.

1. Connect from the dashboard (all platforms)

The simplest path — and the only one for most platforms — is the Developer Dashboard: open Social Accounts, choose a platform, and complete the OAuth flow. The account immediately becomes available to the API and appears in GET /v1/social/accounts.

2. Headless connect (your own UI)

Every OAuth platform can be connected from your own app — Facebook, Instagram, X (Twitter), LinkedIn, YouTube, TikTok, Threads, Bluesky, Pinterest, Reddit, Snapchat, Tumblr, Google Business, and Discord (its server-webhook authorize flow works the same way) — without sending the user through the SmartlyQ dashboard. Telegram is the one non-OAuth platform - it connects with credentials instead of an authorize link. Call the same endpoint with the bot’s token and target chat in the body, and the account connects immediately (no connect_url, nothing for the user to open):

curl -X POST https://api.smartlyq.com/v1/social/connect/telegram \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "bot_token": "123456:AA...", "chat": "@yourchannel" }'

The token is verified with Telegram before saving (the bot must exist and have posting rights in that chat; private chats are rejected), the plan’s account limit is enforced, and the token is stored encrypted. A 201 returns the connected account; failures return typed errors (VALIDATION_ERROR, PROVIDER_NOT_CONFIGURED, LIMIT_REACHED).

Request a connect link

Call POST /v1/social/connect/{platform} with scope social:write. Pass an optional return_url to send the user back to your app afterward.

curl -X POST https://api.smartlyq.com/v1/social/connect/facebook \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://yourapp.com/connected" }'

Response (201)

{
  "success": true,
  "data": {
    "platform": "facebook",
    "connect_url": "https://www.facebook.com/v24.0/dialog/oauth?...",
    "expires_at": "2026-06-06T12:15:00Z"
  }
}

Send the user to connect_url

Open connect_url in a browser (redirect, popup, or new tab). The link is single-use and expires in 15 minutes. The user authorizes on the platform.

The account connects automatically

When the user approves, the platform’s OAuth callback completes the connection on SmartlyQ’s side and — if you supplied return_url — redirects the user back to your app with ?connected=<count>&platform=<name>. The new account now shows up in GET /v1/social/accounts. Platforms that expose multiple targets (YouTube channels, Google Business locations, Tumblr blogs, a member’s LinkedIn pages) connect them all automatically — there’s no in-flow picker.

(Optional) Poll for completion

If your app can’t observe the return_url redirect (e.g. a server-to-server flow, or the user closed the tab), poll with the state_token from the connect_url:

curl https://api.smartlyq.com/v1/social/connect/{state_token} \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx"

Returns status of pending, connected (with the new account), or expired.

Calling POST /v1/social/connect/{platform} with an unrecognized platform returns 422 UNSUPPORTED_PLATFORM (the response lists the supported ones). A platform whose OAuth app isn’t configured on your SmartlyQ instance returns 422 PROVIDER_NOT_CONFIGURED. If headless connect is disabled, the endpoint returns 404 NOT_ENABLED.

Managing connected accounts

Action	Endpoint
List accounts	`GET /v1/social/accounts`
Check token health	`GET /v1/social/accounts/{id}/health`
Get a re-auth link	`GET /v1/social/accounts/{id}/reconnect-url`
Pause / resume posting	`POST /v1/social/accounts/{id}/pause` · `/resume`
Disconnect	`DELETE /v1/social/accounts/{id}`

Reconnecting an account

Access tokens expire (lifetimes vary by platform — some in hours, some in months). SmartlyQ refreshes them automatically, but if an account’s health turns unhealthy — or you receive an account.token_expired webhook — get a reconnect link and send the user through it:

curl https://api.smartlyq.com/v1/social/accounts/123/reconnect-url \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx"

The user re-authorizes and the same account resumes — no new account is created, and scheduled posts keep their target.

Pausing an account (/pause) skips it during publishing without disconnecting it — useful for temporarily taking a brand offline. Disconnecting is irreversible; the user must reconnect to use it again.

See Platforms for which platforms support headless connect, comments, DMs, and analytics.

SDKs & CLI

Guides

Connecting Accounts

1. Connect from the dashboard (all platforms)

2. Headless connect (your own UI)

Managing connected accounts

Reconnecting an account

​1. Connect from the dashboard (all platforms)

​2. Headless connect (your own UI)

​Managing connected accounts

​Reconnecting an account

1. Connect from the dashboard (all platforms)

2. Headless connect (your own UI)

Managing connected accounts

Reconnecting an account