socialchimp

One simple way to connect your app to social networks.

Status: 0.1.0, the first release. All nine networks below work. The way platforms are written is now settled - see the promise about changes before you write your own.

Mastodon · Bluesky · Facebook Pages · Instagram · YouTube · TikTok · X · Pinterest · Threads

What it does

Your app needs to let people connect their social accounts, then post for them and read what happens. Every network does this differently. socialchimp gives you one way to do it, and gets out of the way when you need the network's own features.

• Connect accounts. Sign in with Mastodon, Bluesky, Facebook, Instagram, YouTube, TikTok, X, Pinterest, Threads and more.
• Keep tokens working. Refresh them before they expire, safely, even when several workers run at once.
• Post and read. Text, pictures, video. Read posts and their numbers back.
• Know what happened. Comments and likes reach you the same way whether the network pushes them to you or we have to check on a timer.

What it does not do

• It does not touch your database. No models, no migrations. You write a small storage class, socialchimp hands you data to save. Your schema stays yours, and it works the same on Django, FastAPI, Flask, or nothing at all.
• It does not pretend networks are the same. Pinterest needs a board. Bluesky cannot schedule. YouTube has no text-only post. Where networks differ, the API says so instead of guessing for you.

Install

pip install socialchimp

Add your framework if you want the ready-made routes:

pip install "socialchimp[django]"    # or [fastapi], or [flask]

A first look

from socialchimp import SocialChimp, Post

sc = SocialChimp(storage=MyStorage())

# Post to a connected account.
account = sc.account(connection_id)
result = await account.post(Post(text="Hello from socialchimp"))
print(result.url)

Need something only that network can do? Same connection, direct access:

await account.direct.post(
    "/api/v1/statuses",
    json={"status": "Hello", "visibility": "unlisted"},
)

Tokens, retries and rate limits are still handled for you. Only the request is yours.

Documentation

• Getting started - from nothing to a post
• Networks - what each one can do, and what it needs
• Frameworks - ready-made routes for Django, FastAPI and Flask
• Adding a platform - a network we do not support yet
• Plan - what is built and what is coming
• Changelog - what changed, and what it means for you
• Releasing - how a release goes out
• Examples - runnable programs

Contributing

Contributions are welcome. A few things to know first:

• Tests come first. Write the failing test, then make it pass.
• Coverage must stay at 100%. CI fails below it.
• Types must be strict. mypy --strict with no ignores.

git clone https://github.com/raghulj/socialchimp
cd socialchimp
uv sync --all-extras --dev
uv run pre-commit install --hook-type pre-commit --hook-type pre-push
uv run pytest

Licence

MIT. See LICENSE.