Sociogram Platform API

Welcome to the official Sociogram Platform API! This backend SDK empowers developers to build powerful mini-applications with capabilities for sending notifications, managing in-app purchases, processing payouts, and verifying user actions within the Sociogram platform.

Core Concepts

The Sociogram Platform API provides a comprehensive backend SDK that enables your mini-app to interact with the Sociogram platform from your server.

Backend SDK: Your server uses the @sociogram-dev/platform-api SDK to make authenticated API calls to Sociogram services.
Sociogram Platform: The main Sociogram application that processes your requests and sends webhook events back to your server.
Webhook Communication: The platform sends webhook events to your server for purchase validation, confirmation, and other interactions.

API Reference

User Notifications

Your Mini App can send notifications to users of your application. Users will have the option to disable notifications from specific applications.

Using Backend SDK

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const userId = 1337;
const message = 'Congratulation! You Reach 5 Level! Claim a reward in app';

const isSuccess = await sdk.notifyUser(userId, message);

Params:

uid (number): ID of the user to send the notification to. Required. Example: 1337
message (string, up to 500 characters in UTF-8): The notification message. Required. Example: "Congratulation! You Reach 5 Level!"

Rate Limits:

General (App Level): No more than 30 notifications per second per app.
User Specific: No more than 1 notification per second per user.

Direct API Endpoint

This functionality is also available via a direct API endpoint if you are not using the Node.js SDK. The backend SDK likely wraps this API.

In-App Purchases

Sociogram allows mini-apps to sell digital goods. Supported cryptocurrencies are solana (SOL) and usd (USDT). Earnings are saved to the mini-app balance, manageable on the dev portal.

The process involves your backend and the Sociogram platform:

Step 1 - Invoice Generation

Your backend should implement a method to create an invoice object. This object is then sent to your Mini App's frontend, which passes it to the Sociogram client using Sociogram.MiniApp.openInvoice() or window.parent.postMessage({ action: 'OPEN_INVOICE', invoice }, '*').

Use the @sociogram-dev/platform-api SDK's createInvoice method:

javascript

import { Currency } from '@sociogram-dev/platform-api'; // Assuming Currency enum exists

// Assuming 'sdk' is an initialized SociogramDevKit instance
const title = '100 fish';
const prices = [
  {
    amount: 1.5,
    currency: Currency.Sol, // Or 'sol' if Currency.Sol is not defined in your version
  },
  // You can add another price object for USDT if desired
  // { amount: 1.5, currency: Currency.Usd }
];

const payload = JSON.stringify({
  // user id of user that buy goods
  userId: 123,
  // goods id that user want to purchase
  goodId: 'fish',
  // count of goods that user want to purchase
  count: 100,
  // purchase identifier
  purchseId: 456,
});

const invoice = sdk.createInvoice({ title, prices, payload });

// Send this 'invoice' object to your Mini App's frontend.

createInvoice Params:

title (string): Goods name shown to the user in the confirmation modal. Required. Example: "100 fish"
prices (Array): Array of allowed prices. Each element should have a different currency. Required.
- amount (number): Amount of currency. Required. Example: 1.5
- currency (string/enum): Currency ("sol" or "usdt"). Required.
payload (string): Any useful data to identify the purchase (e.g., JSON string). Accessible in subsequent steps. Required.

Step 2 - Webhook Setup

Instead of creating separate endpoints, you now need to implement a single webhook route that handles all Sociogram communications:

javascript

import { MiniAppUpdate } from '@sociogram-dev/platform-api/dist/api/api.utils'

async listenSociogramEvents(update: MiniAppUpdate) {
    return this.sdk.processUpdate(update)
}

Set up event listeners for purchase validation and confirmation using callbacks:

javascript

import { UpdateEvent } from '@sociogram-dev/platform-api/dist/api/api.utils';

this.sdk.on(UpdateEvent.PurchaseValidate, this.validatePurchase);
this.sdk.on(UpdateEvent.PurchaseConfirmed, this.deliverPurchase);

Step 3 - Purchase Callbacks

Create your validation and confirmation callback methods:

javascript

// Purchase validation callback
validatePurchase = (purchaseData) => {
  // Your validation logic here
  // Return true if purchase is valid, false otherwise
  // Access purchaseData.payload, purchaseData.prices, etc.
  return true; // or false
};

// Purchase confirmation callback
deliverPurchase = (purchaseData) => {
  // Your goods delivery logic here
  // Access purchaseData.payload to identify the purchase
  // Return true if goods were successfully delivered
  return true;
};

Configuration:

Set your webhook URL in the Dev Portal to point to your listenSociogramEvents endpoint
The SDK will automatically route purchase events to your registered callbacks
No need to handle HTTP headers or manual authentication - the SDK manages this internally

App Balance Withdrawal

After purchases, funds are transferred to the Mini App balance. To withdraw, open the Dev Portal, transfer funds from the Mini App balance to your user balance on Sociogram, and then withdraw them through the balance page on Sociogram.

Payouts

Sociogram allows your app to transfer funds from its Mini App balance to your app users or to your developer account. This corresponds to the deposit_money_to_the_internal_user_balance API functionality.

Using Backend SDK

Payout to User

javascript

import { Currency } from '@sociogram-dev/platform-api'; // Assuming Currency enum exists

// Assuming 'sdk' is an initialized SociogramDevKit instance
const userId = 1377;
const amount = 0.35;
const currency = Currency.Sol; // Or 'sol'

await sdk.payoutToUser({ uid: userId, amount, currency });

Params:

uid (number): Receiver's user ID. Required. Example: 1337
amount (number): Transferred amount. Required. Example: 23.5
currency (string/enum): Currency ("usd" for USDT, "sol" for Solana). Required.

Payout to Dev Account

javascript

import { Currency } from '@sociogram-dev/platform-api'; // Assuming Currency enum exists

// Assuming 'sdk' is an initialized SociogramDevKit instance
const amount = 12.5; // Optional: if not passed, transfers all available amount for the currency
const currency = Currency.Usd; // Or 'usd'

await sdk.payoutToDev({ amount, currency });

Params:

currency (string/enum): Currency. Required.
amount (number): Transferred amount. Optional. If not passed, transfers the entire balance for that currency.

The backend SDK allows you to verify various user actions on the Sociogram platform.

Publication Search

Check if a user has made posts matching certain criteria. Corresponds to New_post_created API verification.

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const authorId = '67bdb851166c0be755fac39a';
const search = 'CatGame'; // Text the publication needs to include
const from = '2023-08-31T12:42:57.000+00:00'; // Optional: minimal creation date
const to = '2024-02-12T12:42:57.000+00:00'; // Optional: maximal creation date

const publications = await sdk.searchPublications({ authorId, search, from, to });

// publications.rows will contain an array of matching publications
// publications.cursor for pagination

Params:

authorId (string): User ID whose posts to search. Required.
search (string): Text that the publication must include. Required.
from (string, ISO Date): Optional. Minimal publication creation date.
to (string, ISO Date): Optional. Maximal publication creation date.
cursor (string): Optional. Pagination value.
limit (number): Optional. Count of items per request (default: 20, max: 100).

Result: { rows: Array<Publication>, cursor: string | null } Publication object includes authorId, text, likes, etc.

Engagement Check

Check if a user liked, reposted, commented, or reacted to a specific publication. Corresponds to Add like to post or comment (like verification) and repost_done API verification.

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const userId = 1337;
const publicationId = '67bdb851166c0be755fac39a'; // This should be the ID of the publication

const engagement = await sdk.checkEngagement({ uid: userId, publicationId });

// engagement.liked, engagement.commented, engagement.reposted, engagement.reacted

Params:

uid (number): User ID whose engagement is checked. Required.
publicationId (string): Publication ID to check engagement with. Required.

Result: Object with boolean fields: liked, commented, reposted, and reacted (array of reaction types).

Deposit Check

Check if a user deposited funds (reward or tips) to a publication. Corresponds to Add reward to the post and Add tips to the post API verification.

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const userId = 1337;
const pid = 1716301523324; // Numeric publication ID
const minAmount = 3.5; // Optional: minimal deposit amount in USD equivalent

const isDeposited = await sdk.checkDeposit({ uid: userId, pid, minAmount });

// isDeposited will be true or false

Params:

userId (number): User ID whose deposit is checked. Required.
pid (number): Numeric ID of the publication. Required.
minAmount (number): Optional. Minimal deposit amount (in USD equivalent) to check for.

Result: Boolean (true if user made a deposit meeting criteria).

Comment Search

Check if a user left comments matching certain criteria. Can be used for Add like to post or comment (comment existence verification).

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const authorId = '67bdb851166c0be755fac39a';
const search = 'Join me in CatGame';
const from = '2023-08-31T12:42:57.000+00:00'; // Optional
const to = '2024-02-12T12:42:57.000+00:00'; // Optional
const limit = 1; // Optional

const result = await sdk.searchComments({ authorId, search, from, to, limit });
const comment = result.rows[0]; // If any

// result.rows contains matching comments, result.cursor for pagination

Params:

authorId (string): User ID whose comments to search. Required.
search (string): Text that the comment must include. Required.
from, to, cursor, limit: Same as searchPublications.

Result: { rows: Array<Comment>, cursor: string | null } Comment object includes authorId, text, likes, etc.

Follow Check

Check if a user is following another target user/profile. Corresponds to Check following API.

javascript

// Assuming 'sdk' is an initialized SociogramDevKit instance
const miniAppAuthorId = 1911; // Target user's slug or ID
const userId = 1337; // User who should be following

const isFollowed = await sdk.checkFollow({
  targetSlug: miniAppAuthorId,
  userSlug: userId,
});

// isFollowed will be true or false

Params:

targetSlug (number): The user/profile that userSlug should be following. Required.
userSlug (number): The user whose following status is being checked. Required.

Result: Boolean (true if userSlug follows targetSlug).

Direct API Endpoints

For functionalities not covered by the @sociogram-dev/platform-api SDK or if you prefer direct integration, you can use these API endpoints. Your backend will make HTTP requests to these endpoints, authenticating with your MiniAppToken.

Post Management

Provides API operations for posts: create, edit, delete, repost, pin.

Functionality:

Create posts with pre-filled text/images (requires user confirmation if called from API without Mini App context, like Twitter).
Add currency to Community Reward during post creation.
The system records the app from which the post was made (for future display).
Returns True/False for action status.
Check for the existence of a post with specified text within a given period (e.g., last 24 hours UTC).
Returns a unique ID for created posts/comments and user info.
Returns counts of comments, likes, reposts, and pin status for a post.

Notes: Done.

Comment Management

Provides API operations for comments: create, delete.

Functionality:

Create comments with pre-filled text/images under a specific post (requires user confirmation if called from API without Mini App context).
Returns True/False for action status.
Check for the existence of any comment under a post.
Check for the existence of a comment with specified text by a user within a given period (e.g., last 24 hours UTC).
Returns a unique ID for created comments and user info.

Notes: Done.

Create Poll

API for creating polls.

Functionality:

Create polls with custom parameters for participation (similar to Giveaways).
Ability to check if an end-user participated in a non-anonymous poll.

Notes: No status, likely pending or requires direct API spec.

Create Giveaway

API for creating Giveaways with a post.

Functionality:

Create Giveaways with parameters similar to the frontend version.
Includes a randomizer.
Setting to allow joining Giveaway only if game conditions are met.

Notes: No status, likely pending or requires direct API spec.

User Information

Information about the current user is available to your Mini App.

Basic Information

Basic user information is typically provided when the Mini App initializes (e.g., through Sociogram.MiniApp.initData) or upon user login to the Mini App. This includes:

User name
User ID
Wallet address
Profile image URL
Background profile image URL
Address domain (ENS, etc.)
Bio
Location
Twitter handle
Website
Balance (USDT) - Note: Access to balances might be restricted or require specific permissions.
first_tx date
User's device platform (Web: macOS, Windows, Linux; iOS; Android)
App version (for iOS, Android)
User device language
User time zone

An example of user data structure:

json

{
  "address": "0xa2de8e98a88c7a814196e71a626986b24a1f8798",
  "avatar": null,
  "cover": null,
  "walletUsdt": "0",
  "bio": null,
  "name": null,
  "location": null,
  "website": null,
  "domain": null,
  "twitterId": null,
  "twitterName": null,
  "twitterFollowers": "0",
  "_id": "6807708bf52149bdf4dd56ab",
  "uid": 1337,
  "firstTxDate": "0",
  "totalEarned": "0",
  "hash": "1d5894549c231ed1618cbe168df7f...",
  "provider": "sociogram",
  "startApp": null,
  "languageCode": "en",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X...",
  "platform": "macOS",
  "timezone": "Europe/London"
}

Additional Information

Some user information, like the amount of followers, following, friend list count, total earned on SG, and amount of posts on SG, might be fetched via separate API endpoints to optimize login speed.

The frontend SDK methods getFollowers, getFollowing, getFriends can retrieve lists and counts.
Other specific data points like "Total earned on SG" or "Amount of posts on SG" might require dedicated API calls if not included in the basic user object or covered by existing SDK methods.

Sociogram Platform API ​

Core Concepts ​

API Reference ​

User Notifications ​

Using Backend SDK ​

Direct API Endpoint ​

In-App Purchases ​

Step 1 - Invoice Generation ​

Step 2 - Webhook Setup ​

Step 3 - Purchase Callbacks ​

App Balance Withdrawal ​

Payouts ​

Using Backend SDK ​

Payout to User ​

Payout to Dev Account ​

User Actions & Verification ​

Publication Search ​

Engagement Check ​

Deposit Check ​

Comment Search ​

Follow Check ​

Direct API Endpoints ​

Post Management ​

Comment Management ​

Create Poll ​

Create Giveaway ​

User Information ​

Basic Information ​

Additional Information ​

Sociogram Platform API

Core Concepts

API Reference

User Notifications

Using Backend SDK

Direct API Endpoint

In-App Purchases

Step 1 - Invoice Generation

Step 2 - Webhook Setup

Step 3 - Purchase Callbacks

App Balance Withdrawal

Payouts

Using Backend SDK

Payout to User

Payout to Dev Account

User Actions & Verification

Publication Search

Engagement Check

Deposit Check

Comment Search

Follow Check

Direct API Endpoints

Post Management

Comment Management

Create Poll

Create Giveaway

User Information

Basic Information

Additional Information