Connecting social accounts is the hardest part of any integration because OAuth flows are pain. We offer two ways to handle this.
1. The Easy Way (Hosted Flow)
We host the UI. You just send the user to a link, they click buttons, and get redirected back to you.
Endpoint: POST /api/v1/social-account/create-portal-link
Test it in Swagger or the API Reference Client.
Parameters
| Parameter | Required | Description |
|---|
teamId | Yes | The team ID to connect the social accounts to. |
redirectUrl | Yes | The URL to redirect to after clicking the back button. |
socialAccountTypes | Yes | The social account types to connect (e.g. ['INSTAGRAM', 'LINKEDIN']). |
logoUrl | No | The URL of the logo to display on the top of the page. |
userLogoUrl | No | The URL of the user logo/avatar to display. |
userName | No | The name of the user to display. |
goBackButtonText | No | The text of the back button. |
language | No | The language of the page. |
hidePoweredBy | No | Whether to hide the “powered by” text. |
hideGoBackButton | No | Whether to hide the back button. |
hideUserLogo | No | Whether to hide the user logo. |
hideUserName | No | Whether to hide the user name. |
hideLanguageSwitcher | No | Whether to hide the language switcher. |
showModalOnConnectSuccess | No | Show a modal on connect success asking what to do next - go back to redirectUrl or close and connect more accounts. |
maxSocialAccountsConnected | No | The maximum number of social accounts that can be connected. |
Supported Languages
| Code | Language |
|---|
en | English |
pl | Polish |
fr | French |
hi | Hindi |
sv | Swedish |
de | German |
es | Spanish |
it | Italian |
nl | Dutch |
pt | Portuguese |
ru | Russian |
tr | Turkish |
zh | Chinese |
Hosted Page Preview
2. The Hard Way (Custom UI)
You build the UI. You trigger the OAuth flows. You look like a hero.
Connect Social Account Flow
For most platforms, the flow is straightforward. The exceptions are YouTube, Facebook, Instagram, LinkedIn, and Google Business where you need to select a channel after the initial connection.
Channel Selection Required:
- YouTube: Select a YouTube channel.
- Facebook: Select a Facebook Page.
- Instagram: Select an Instagram account (connected to a Facebook Page).
- LinkedIn: Select a LinkedIn Company Page.
- Google Business: Select a business location.
Handling Callbacks
Whether you use Hosted or Custom, the user eventually comes back to your URL with query parameters.
Success Messages
We append success flags to your redirect URL:
| Parameter | Message |
|---|
twitter-callback | Twitter connected successfully |
pinterest-callback | Pinterest connected successfully |
tiktok-callback | TikTok connected successfully |
facebook-callback | Facebook connected successfully |
instagram-callback | Instagram connected successfully |
linkedin-callback | LinkedIn connected successfully |
reddit-callback | Reddit connected successfully |
discord-callback | Discord connected successfully |
slack-callback | Slack connected successfully |
youtube-callback | YouTube connected successfully |
threads-callback | Threads connected successfully |
mastodon-callback | Mastodon connected successfully |
bluesky-callback | Bluesky connected successfully |
google-business-callback | Google Business connected successfully |
Error Messages
If things go wrong, we tell you why. Here’s the complete list:
| Parameter | Message |
|---|
twitter-callback | Error connecting Twitter |
twitter-not-enough-permissions | You didn’t grant all the necessary permissions |
Pinterest
| Parameter | Message |
|---|
pinterest-callback | Error connecting Pinterest |
pinterest-not-enough-permissions | You didn’t grant all the necessary permissions |
TikTok
| Parameter | Message |
|---|
tiktok-callback | Error connecting TikTok |
tiktok-not-enough-permissions | You didn’t grant all the necessary permissions |
Facebook
| Parameter | Message |
|---|
facebook-callback | Error connecting Facebook |
facebook-not-enough-pages | You don’t have enough permissions in any of your Facebook pages |
facebook-not-enough-permissions | You didn’t grant all the necessary permissions |
Instagram
| Parameter | Message |
|---|
instagram-callback | Error connecting Instagram |
instagram-not-enough-accounts | You don’t have enough permissions in any of your Instagram accounts, or none of your Facebook pages has an Instagram account connected |
instagram-not-enough-permissions | You didn’t grant all the necessary permissions |
LinkedIn
| Parameter | Message |
|---|
linkedin-callback | Error connecting LinkedIn |
linkedin-not-enough-channels | You don’t have enough permissions in any of your LinkedIn organizations |
linkedin-not-enough-permissions | You didn’t grant all the necessary permissions |
Reddit
| Parameter | Message |
|---|
reddit-callback | Error connecting Reddit |
reddit-not-enough-permissions | You didn’t grant all the necessary permissions |
Discord
| Parameter | Message |
|---|
discord-callback | Error connecting Discord |
discord-not-enough-servers | You don’t have enough permissions in any of your Discord servers |
discord-not-enough-permissions | You didn’t grant all the necessary permissions |
Slack
| Parameter | Message |
|---|
slack-callback | Error connecting Slack |
slack-not-enough-workspaces | You don’t have enough permissions in any of your Slack workspaces |
slack-not-enough-permissions | You didn’t grant all the necessary permissions |
YouTube
| Parameter | Message |
|---|
youtube-callback | Error connecting YouTube |
youtube-not-enough-channels | You don’t have enough permissions in any of your YouTube channels |
youtube-not-enough-permissions | You didn’t grant all the necessary permissions |
Threads
| Parameter | Message |
|---|
threads-callback | Error connecting Threads |
threads-not-enough-permissions | You didn’t grant all the necessary permissions |
Mastodon
| Parameter | Message |
|---|
mastodon-callback | Error connecting Mastodon |
mastodon-not-enough-permissions | You didn’t grant all the necessary permissions |
Bluesky
| Parameter | Message |
|---|
bluesky-callback | Error connecting Bluesky |
bluesky-not-enough-permissions | You didn’t grant all the necessary permissions |
Google Business
| Parameter | Message |
|---|
google-business-callback | Error connecting Google Business |
Pro Tip: Always handle the not-enough-permissions error gracefully. Tell the user: “Hey, we need those permissions to actually post. Please try again and don’t uncheck the boxes.”
Unset Channel (Switch Pages)
Some platforms let your user pick from multiple pages or channels under one OAuth connection (Facebook Pages, LinkedIn Company Pages, YouTube channels, Instagram accounts via Facebook, Google Business locations). Sometimes they pick the wrong one. Or they want to switch.
Instead of disconnecting and re-authenticating from scratch, you can unset the current channel and let them pick a new one.
Endpoint: POST /api/v1/social-account/unset-channel
{
"type": "FACEBOOK",
"teamId": "team_123"
}
| Platform | Supported | Note |
|---|
| Facebook | Yes | |
| Instagram | Yes | Only when connected via Facebook. Direct Instagram connections can’t be unset. |
| LinkedIn | Yes | |
| YouTube | Yes | |
| Google Business | Yes | |
What Happens
- The selected page/channel is cleared from the social account.
- The OAuth connection stays intact — no re-auth needed.
- The account is removed from all draft and scheduled posts.
- Posts that only had this account become drafts.
social-account.updated and team.updated webhooks fire.
The Flow
- Call
POST /social-account/unset-channel to clear the current selection.
- Call
POST /social-account/set-channel with the new page/channel ID.
No OAuth dance. No popup. No “please grant permissions again.”
Unsetting removes the account from all draft and scheduled posts. If a post only had this one account, it becomes a draft. Make sure your users know before they switch.
