Get started

Connecting accounts

How accounts are connected, and how to tell what each one can do.

Accounts are connected in the dashboard, under Accounts, by workspace owners and admins. There’s no API for connecting accounts: your API key posts to the accounts your workspace has connected.

How each platform connects

Sign in: LinkedIn, Facebook, Instagram, Google Search Console, Google Analytics, YouTube and Google Ads. You approve access on the platform’s own screen, through SocialHelper’s app. One sign-in can connect more than one account where the platform allows it.

Credentials: Bluesky, Mastodon, Telegram and Discord. The connect form asks for:

Bluesky · Handle or email text: Your Bluesky handle, or the email you sign in with.
Bluesky · App password password: Create one in Bluesky under Settings → Privacy and security → App passwords. Do not use your account password.
Mastodon · Server url: The address of your Mastodon server.
Mastodon · Access token password: In Mastodon, open Preferences → Development → New application. Tick the scopes read:accounts, read:statuses, write:statuses and write:media, save, then open the application and copy “Your access token”.
Telegram · Bot token password: Create a bot with @BotFather and paste the token it gives you. Then add the bot to your channel as an administrator allowed to post messages.
Telegram · Channel or group text: The public @username, or the numeric chat id of a private channel or group, such as -1001234567890.
Discord · Webhook URL url: In Discord, open the channel’s settings → Integrations → Webhooks → New Webhook, then click Copy Webhook URL.

Credentials and tokens are encrypted at rest and never returned by the API.

Listing accounts

curl https://socialhelper.app/api/v1/accounts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY"

Each account has:

id string: Use it in accounts when you create a post, and in the tools endpoints.
platform string: The platform key, e.g. bluesky or linkedin.
status string: active, or needs_reconnect when the platform withdrew access. status_reason explains why.
can_publish boolean: Whether the account can receive posts.
tools array: The names of the account’s tools, if it has any. See Account tools.
name, username, avatar_url, profile_url string: How the account appears on the platform.
connected_at, last_published_at string: ISO 8601 timestamps in UTC.

GET /api/v1/platforms lists the platforms you can connect right now, with each one’s posting rules (or null if it doesn’t publish) and its tools.

When an account needs reconnecting

If a platform withdraws access (a password change, an expired grant, a revoked app), the account’s status becomes needs_reconnect, the workspace owner gets an email, and an account.needs_reconnect webhook is sent. Reconnect it from Accounts in the dashboard.

Disconnecting

Disconnecting an account deletes its credentials, cancels any of its posts that haven’t started publishing and, where the platform allows it, revokes SocialHelper’s access there. Posts that are already live stay on the platform.