Copy page

SDKs: install and use the OmniSocials API in 8 languages

Official client libraries for the OmniSocials API in 8 languages. Every SDK has the same shape: resource-based clients (client.posts.create(...)), typed requests and responses, automatic retries with backoff, a shared error hierarchy, and a webhook signature verification helper. Pick your language and you are posting in five lines.

These pages are the reference. For an overview of the SDKs and what you can build with them, see omnisocials.com/sdk.

Install

Each language has its own page with full examples: install, auth, posting, media, analytics, the social inbox, Pinterest product tags, webhooks, and error handling.

Language	Package	Install	Docs
Node.js / TypeScript	@omnisocials/sdk	npm install @omnisocials/sdk	Node.js
Python	omnisocials	pip install omnisocials	Python
Go	github.com/OmniSocials/omnisocials-go	go get github.com/OmniSocials/omnisocials-go	Go
Ruby	omnisocials	gem install omnisocials	Ruby
Java	com.omnisocials:omnisocials-java	Maven / Gradle dependency	Java
PHP	omnisocials/omnisocials-php	composer require omnisocials/omnisocials-php	PHP
.NET	OmniSocials	dotnet add package OmniSocials	.NET
Rust	omnisocials	cargo add omnisocials	Rust

All 8 cover the full v1 surface: posts (including create-and-publish, retrying the failed platforms of a failed or partially failed post via posts.retry, approving or rejecting a post waiting in an approval workflow via posts.approve / posts.reject, reading the review of a post (steps, approvers, the rejection reason and the comment thread) via posts.getApproval, per-platform options, and thread chains on X, Bluesky, Mastodon, and Threads), media (URL, base64, multipart, PDF carousels, presigned large-file uploads), folders, hashtag sets (CRUD plus applying a set at post create via hashtag_set / hashtag_placement), approval workflows (approvalWorkflows.list), accounts, analytics (post, bulk, overview, accounts, best times), Instagram locations, Instagram Reel music search, Pinterest product Pins for product tags (pinterest.listProducts, pinterest.validateProduct), the social inbox, and webhooks (CRUD plus secret rotation and signature verification).

Social Inbox

Every SDK has an inbox resource for the DMs, comments and mentions of your connected accounts. It needs an API key with the opt-in inbox:read / inbox:write scopes.

Method (Node names)	What it does
inbox.listConversations()	Lists conversations. Filters: platform, type, unread, unanswered.
inbox.getMessages(conversationId)	Returns the messages of one conversation.
inbox.reply(conversationId, { text })	Sends a reply. Pass message_id on a comment thread.
inbox.markRead(conversationId)	Marks the conversation as read.
inbox.hide(messageId)	Hides or unhides a comment on one of your posts.
inbox.deleteMessage(messageId)	Deletes a comment on one of your posts.
inbox.next()	Hands out the next conversation that still needs an answer.

TypeScript
let { data: item } = await client.inbox.next();
while (item) {
  const reply = await client.inbox.reply(item.message.conversation_id, {
    text: "Thanks for reaching out!",
    message_id: item.message.id,
    include_next: true,
  });
  item = reply.next ?? null;
}

Each language page has the same calls in its own idiom. See the Social Inbox guide for the platforms, the reply rules and the error codes.

Pinterest product tags

Every SDK has a pinterest resource for product tagging: it lists the product Pins of the connected Pinterest account, so you can tag up to 24 of them on a Pin with product_tags in the pinterest options of a post. It uses the posts:read scope.

Method (Node names)	What it does
pinterest.listProducts()	Lists product Pins. Filters: source (catalog or pins), product_group_id, bookmark, page_size.
pinterest.validateProduct(id)	Checks one Pin id or Pin link before you use it as a product tag.

TypeScript
const list = await client.pinterest.listProducts();

if (!list.error) {
  await client.posts.create({
    content: "Our summer picks",
    channels: ["pinterest"],
    media_urls: ["https://example.com/summer-look.jpg"],
    pinterest: {
      board_id: "1234567890",
      product_tags: (list.products ?? []).slice(0, 3).map((product) => product.pin_id),
    },
  });
}

The list answers with HTTP 200 in both cases: products on success, or an error object (pinterest_not_connected, pinterest_catalog_access_required, platform_error) when it could not be read. Only product Pins of your own account can be tagged; products of other merchants cannot. The tags are added right after the Pin is published. A product that Pinterest refuses never fails the post: the post then carries pinterest.product_tags_result with the tagged and the skipped Pin ids. Each language page has the same calls in its own idiom.

Authentication

Every SDK reads the OMNISOCIALS_API_KEY environment variable, or takes the key in the constructor. Create a key in the OmniSocials app under Settings → API. Keys start with omsk_live_; there is no separate test mode.

Terminal
export OMNISOCIALS_API_KEY="omsk_live_<YOUR_KEY>"

Quickstart

Node.js / TypeScript

TypeScript
import { OmniSocials } from "@omnisocials/sdk";

const client = new OmniSocials(); // reads OMNISOCIALS_API_KEY from env
const post = await client.posts.create({
  content: "Hello from the SDK",
  channels: ["instagram", "linkedin"],
  scheduled_at: "2026-08-01T09:00:00Z",
});

Python

Python
from omnisocials import OmniSocials

client = OmniSocials()  # reads OMNISOCIALS_API_KEY from the environment
post = client.posts.create(content="Hello from Python", channels=["instagram", "linkedin"])
print(post["data"]["id"])

SDK names vs REST names

The SDKs send a few fields under other names than the REST examples in these docs. The API accepts both names, so either one works in a raw HTTP body too. If you move between an SDK and raw HTTP (or read both docs), map them like this:

SDK parameter	REST field
channels: ["instagram"]	accounts: ["instagram"]
scheduled_at	schedule_at
content: "one string"	content: { "default": "one string" }

Everything else has the same name in both.

A synchronous and an async client (AsyncOmniSocials) ship in the Python package. The Go, Ruby, PHP, Java, .NET, and Rust clients expose the same resources and methods adapted to each language's idiom. Full runnable examples for every resource live in each package's README (linked in the table above).

X link posts use credits. When a create targets X and the text contains a URL, the create response carries a top-level warnings array next to data (code x_url_post_credits): X's link-post fee passed through as prepaid credits. Every SDK returns it as part of the parsed response body (typed as PostWarning in the Node and Go SDKs). See Creating Posts for the shape and the publish-time behavior.

Configuration

Every client accepts the same options: apiKey, baseUrl, timeout (default 30s), and maxRetries (default 2). Retries use exponential backoff with jitter on 429, 5xx, and network errors, and honor the Retry-After header. Other 4xx responses are never retried.

Errors

Non-2xx responses raise a typed error from a shared hierarchy: a base error, an API error carrying status / code / body, and per-status subclasses (authentication, permission, not-found, validation, rate-limit with retry_after, server), plus a connection error and a webhook-verification error. See Rate limits and errors for the status codes.

Webhook verification

Each SDK ships a helper that verifies the X-OmniSocials-Signature header (HMAC-SHA256 over "{timestamp}.{rawBody}", constant-time compare, replay-window check) and returns the parsed event. Node example:

TypeScript
import { verifyWebhookSignature } from "@omnisocials/sdk";

app.post("/webhooks/omnisocials", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhookSignature({
    payload: req.body, // raw bytes, not parsed JSON
    signature: req.header("X-OmniSocials-Signature"),
    secret: process.env.OMNISOCIALS_WEBHOOK_SECRET,
  });
  // handle event.type ...
  res.sendStatus(200);
});

The events are post.scheduled, post.published, post.failed, post.approved and post.rejected. The two approval events carry data.approval with status, decided_by and reason. See Webhooks for event types and payloads.

Prefer a different integration?

• MCP Server for AI assistants (Claude, ChatGPT, Cursor, and more)
• Agent Skills for AI coding tools without MCP support
• API Reference for the raw HTTP endpoints