socialchimp

One simple way to connect your app to social networks.

Read this as a website: raghulj.github.io/socialchimp — the tutorial, the reference and everything below, searchable and easier to read than markdown files in a repository.

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

New here? Start with the tutorial. It assumes you have built a web app before but have never touched a social network API, and explains why this is harder than one HTTP request.

Learning

• Tutorial - the ideas, and how the classes fit together
• Getting started - from nothing to a post, in six steps

Three things people actually build

• A shop posting to its Facebook Page - Django. Sign-in that pauses to ask which Page, and real scheduling.
• A creator tool uploading video to TikTok - FastAPI. Large files sent in pieces, and the audit trap that makes working code look broken.
• Publishing YouTube Shorts - Flask. A network with no text-only post at all, and why you cannot ask for a Short.

Reference

• Networks - what each one can do, and what it needs
• Frameworks - the ready-made routes in detail
• Adding a platform - a network we do not support yet
• Examples - runnable programs
• Changelog - what changed, and what it means for you

Project

• Plan - what is built and what is coming
• Contributing - the three rules that are not negotiable
• Releasing - how a release goes out

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.