Connecting social platforms to Postwoo

Updated 17 October 2026 · 12 min read

Postwoo connects to every platform through its official API and OAuth login. You sign in on the platform's own page, choose what Postwoo may access, and the platform hands Postwoo a token. Postwoo stores that token encrypted, never your password, and you can revoke access at any time from the platform or from Postwoo.

There are two sides to every connection:

1. Your agency's Postwoo instance must be registered as an app with the platform once (done by whoever operates Postwoo). Section B explains that.
2. Each client account is then connected in a few clicks by someone who manages that account on the platform. Section A explains that.

If you use a hosted Postwoo, section B has already been done for you; start at section A.

A. Connecting a client's accounts (Manager role or above)

1. Open Connections in the left menu and press Connect.
2. Pick the platform. Postwoo shows exactly what it will ask for before you leave the page.
3. Sign in on the platform's page with the account that manages the business profile (see the table below for the role you need) and approve the requested access.
4. You land back in Postwoo. It discovers the pages, profiles, channels or locations that account can manage and lists them.
5. Assign each discovered account to a client (you can hide the ones you do not manage). Assignment is what makes posts, reviews and stats show up under the right client.
6. Press Run health check. Green means the token works and every needed permission was granted.

Ask your client to connect

If the login belongs to your client (common for Google Business Profile, TikTok and Threads), you don't need their password. Send them an invite instead:

1. Open Connections, press Connect, then Invite the client to connect. You can also start an invite from the Invites view or from the client's Connections tab.
2. Pick the client and the platforms you need. Add their name, e-mail and a short note if you like, and choose how long the link lasts (14 days by default, up to 60).
3. Copy the link now, because it is shown only once. You can also let Postwoo e-mail it, branded with your agency name and the platforms you asked for.
4. Your client opens the link on any device. For each platform they see which login to use, the role they need (the table above), what Postwoo will and will not be able to do, and a big Connect button. They sign in on the platform's own page; for Bluesky they paste an app password on the card.
5. Each connection is created for that client, and its accounts are assigned to them automatically. You get a notification for each platform and another when everything is connected. Follow progress and a timeline in the Invites view, where you can also resend or revoke the link.

Good to know:

• Your client does not get a Postwoo login, and you never get their password or admin rights on their platform account.
• An invite cannot take over a connection or account you already manage for a different client. If the client signs in with such a login, nothing is changed and they are asked to contact you; a duplicate account stays unassigned for you to review.
• Revoking an invite, or letting it expire, makes the link show "This invite can't be used". Accounts that are already connected stay connected.

After connecting

• Nothing is posted by connecting. Publishing happens only when a post is scheduled or approved.
• Tokens expire; Postwoo refreshes them automatically. If a platform revokes access (password change, removed admin, expired app review), the connection shows Reconnect and you will get an alert. Reconnecting keeps all history.
• Each connection lists its capability matrix: what the platform's API allows (text, images, video, scheduling, insights, reviews). "Pending verification" means Postwoo built the integration to the official specification but has not yet confirmed it end to end with approved production credentials; Postwoo will say so rather than pretend.

Google Business Profile specifics

• Reviews and local posts come from Google's Business Profile APIs, which Google only enables for approved projects (see B). Until the project is approved, Google's side reports quota 0 and Postwoo marks the connection as not configured.
• Google does not allow phone numbers in post text and rejects images under 250×250 px. Postwoo's pre-flight check tells you before you schedule.
• Review replies are posted as the business, under the Google account that connected.

Instagram specifics

• Only Professional Instagram accounts linked to a Facebook Page can be connected; personal accounts have no publishing API.
• Media is published by URL. Postwoo therefore needs a public APP_URL or an S3 bucket so Instagram can fetch the image or video.

LinkedIn specifics

• Posting to a Company Page requires LinkedIn's Community Management API access for the app (section B). Without it, only the connecting member's personal profile is available.

Threads specifics

• Threads is connected separately from Instagram, even though you sign in with the same Instagram login.
• Like Instagram, Threads downloads images and videos from Postwoo's public media URL, so the instance needs a public APP_URL or S3 storage.
• Posts are limited to 500 characters; carousels to 10 items in Postwoo. Threads posts cannot be edited.

Pinterest specifics

• Every pin must go to a board. In the composer, ticking a Pinterest account shows its boards; pick one or more (each board gets its own pin). Boards are never all selected by default.
• The first line of the post (or the Pin title option) becomes the title (100 characters); the body is the description (800).
• Account analytics only exist for business accounts; personal accounts show them as unavailable.

Bluesky specifics

• Bluesky has no "Sign in with Bluesky" page in this version. Press Connect with app password, enter the handle (e.g. yourname.bsky.social) and an app password. Never enter the main password: Postwoo refuses anything that does not look like an app password.
• Postwoo exchanges the app password for a session once and stores only that session, encrypted. Revoking the app password on bsky.app disconnects Postwoo; reconnect with a new one from the account's Reconnect button.
• Accounts on a self-hosted PDS can fill in the optional Service URL.
• Posts are limited to 300 characters (an emoji counts as one). Links, @mentions and #hashtags become clickable automatically; images over 1 MB are shrunk before upload. Video is not available yet.

TikTok specifics

• Until TikTok audits the app, videos can only be posted as private (SELF_ONLY); this is a TikTok rule and Postwoo shows it in the capability matrix.

Troubleshooting

B. Registering Postwoo with each platform (operator, once per installation)

Every platform needs an app that represents your Postwoo installation. For each one you will get a client id and secret; put them in .env and restart the workers. The redirect URI is always:

https://YOUR-POSTWOO-DOMAIN/oauth/{platform}/callback

with {platform} one of google_business_profile, facebook, instagram, linkedin, youtube, tiktok, threads, pinterest (Bluesky needs no app and no redirect URI). Use the exact domain from APP_URL; platforms compare it character by character.

Google Business Profile

1. Create a Google Cloud project. Enable My Business Account Management API, My Business Business Information API, Business Profile Performance API, My Business Q&A API and the legacy Google My Business API (v4) (reviews and local posts still live there).
2. Request Business Profile API access for the project (Google's access request form). The default quota is 0 until Google approves. Use your agency's real business and website in the request.
3. Configure the OAuth consent screen (external), scope https://www.googleapis.com/auth/business.manage, plus openid email profile. Submit for verification; until then add your team as test users.
4. Create an OAuth client of type Web application with the redirect URI above. Put the values in .env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
5. Optional, for instant review alerts: create a Pub/Sub topic and a push subscription to https://YOUR-DOMAIN/webhooks/google_business_profile?token=… (GOOGLE_PUBSUB_VERIFY_TOKEN), then run php bin/postwoo gbp:notifications --connection=… --topic=…. Without it reviews are polled every 30 minutes.

Facebook Pages and Instagram (one Meta app)

1. In Meta for Developers create a Business type app and complete Business verification.
2. Add Facebook Login for Business and set the redirect URI above (both the facebook and instagram variants).
3. Request these permissions through App Review: pages_show_list, pages_read_engagement, pages_manage_posts, pages_read_user_content, read_insights, business_management, and for Instagram instagram_basic, instagram_content_publish, instagram_manage_insights. Record a screencast of the connection flow in Postwoo; Meta asks for one.
4. Put META_APP_ID, META_APP_SECRET in .env (META_GRAPH_VERSION defaults to the current Graph version).
5. Optional webhooks: subscribe the app to Page feed events pointing at https://YOUR-DOMAIN/webhooks/facebook with META_WEBHOOK_VERIFY_TOKEN.

Until App Review is complete, only people listed as app testers/developers can connect, and Postwoo keeps the capabilities marked pending verification.

LinkedIn

1. Create an app at the LinkedIn Developer portal, associated with your agency's Company Page, and verify it from that page.
2. Request the Share on LinkedIn, Sign In with LinkedIn using OpenID Connect and Community Management API products. Company Page posting and organization statistics depend on Community Management approval.
3. Add the redirect URI and copy LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET into .env. LinkedIn versions its API monthly (LINKEDIN_API_VERSION); keep it within LinkedIn's supported window.

Scopes Postwoo requests: openid profile email w_member_social r_organization_social w_organization_social rw_organization_admin r_organization_admin.

YouTube

1. In the same or a separate Google Cloud project, enable YouTube Data API v3 and YouTube Analytics API.
2. The consent screen must be verified because the YouTube scopes (youtube.upload, youtube.readonly, yt-analytics.readonly) are sensitive.
3. Create a Web application OAuth client with the youtube redirect URI and set YOUTUBE_CLIENT_ID / YOUTUBE_CLIENT_SECRET (they may equal the Google Business Profile client if you add both redirect URIs to one client).

TikTok

1. Register an app at TikTok for Developers, add Login Kit and Content Posting API, and set the redirect URI.
2. Request scopes user.info.basic, user.info.profile, video.publish, video.upload.
3. Submit the app for audit; until it passes, posts can only be made as private.
4. Set TIKTOK_CLIENT_KEY / TIKTOK_CLIENT_SECRET.

Threads

1. In Meta for Developers open (or create) an app and add the use case "Access the Threads API". Threads has its own app id and secret shown in that use case's settings — not the Facebook META_APP_ID.
2. Add the redirect URI https://YOUR-DOMAIN/oauth/threads/callback (plus the uninstall/delete callbacks Meta asks for).
3. Request threads_basic, threads_content_publish, threads_manage_insights, threads_manage_replies, threads_read_replies. Until App Review approves them, only people added as Threads testers can connect; switch the app to Live after approval.
4. Set THREADS_APP_ID / THREADS_APP_SECRET (THREADS_API_VERSION defaults to v1.0).

Pinterest

1. Create an app at developers.pinterest.com and add the redirect URI https://YOUR-DOMAIN/oauth/pinterest/callback.
2. New apps get trial access: they only work against the sandbox and the developer's own account. While testing set PINTEREST_API_BASE=https://api-sandbox.pinterest.com.
3. Apply for standard access with a short recording of connecting and pinning from Postwoo. Once approved, set PINTEREST_API_BASE=https://api.pinterest.com so client accounts can connect.
4. Set PINTEREST_APP_ID / PINTEREST_APP_SECRET. Scopes requested: boards:read boards:write pins:read pins:write user_accounts:read.

Bluesky

Nothing to register. Bluesky's AT Protocol API is open; each account connects with its own app password. Optionally set BLUESKY_SERVICE if most of your clients use a PDS other than https://bsky.social.

Checking the setup

php bin/postwoo integrations:report     # which platforms have credentials and each capability's status
php bin/postwoo health:check            # probes every connected account

The Integrations page in the app and GET /api/v1/integrations show the same matrix.

C. Platforms that could be added next

Postwoo only adds platforms that offer an official API for the feature in question. Threads, Pinterest and Bluesky have been added (see above). These are the remaining realistic candidates, roughly in order of usefulness for local-business agencies; each would ship as pending verification until proven with live credentials:

Tell us which of these your clients ask for and we will prioritise accordingly.