Apps API

getUserInfoGET#

The profile of the player who opened the game. Calling it on startup is common practice — you usually need the name, avatar and language right away.

lang is the player's account language ("ru" or "en"). It is their own choice on the platform, so it beats the browser and system locale. It is simpler to drive localisation with zloy.lang: the same language, but right away, without a request, and for guests too.

const {user} = await zloy.getUserInfo();
nameLabel.textContent = user.nickname;
if (user.avatar) avatarImg.src = user.avatar;
setLocale(zloy.lang);            // 'ru' | 'en' — the same language as user.lang

// Response:
// { "ok": true, "user": { "user_id": 42, "username": "zloysega",
//   "nickname": "Sergey", "avatar": "…", "lang": "ru",
//   "premium": false } }

const {user}: UserInfo = await zloy.getUserInfo();
render(user);
i18n.locale = user.lang;         // 'ru' | 'en'

getUserFriendsGET#

The player's friends, paginated: offset (default 0) and limit (default and maximum 100). The response also carries total.

The list includes friends with a public profile and friends who installed your game. A friend with a private profile who never played is left out: the game gets no data about them without their consent.

const {total, friends} = await zloy.getUserFriends(0, 100);
console.log(`friends: ${total}`);

// Response:
// { "ok": true, "total": 152, "offset": 0, "limit": 100,
//   "friends": [ { "user_id": 7, "nickname": "Alice", … } ] }

const page: FriendsPage = await zloy.getUserFriends(0, 100);
page.friends.forEach(renderFriend);

getUserFriendsInAppGET#

Same shape, but only friends who already installed your game. Good for “invite your friends” and for showing who you can play with right now.

const {friends} = await zloy.getUserFriendsInApp();
showInviteList(friends);

const {friends}: FriendsPage = await zloy.getUserFriendsInApp();

getUserInstalledAppsGET#

Games the player has installed, paginated like the friend list. Useful for cross-promotion between your own games.

const {apps} = await zloy.call('getUserInstalledApps');

// Response:
// { "ok": true, "total": 3, "offset": 0, "limit": 100,
//   "apps": [ { "app_id": 1, "slug": "darkrunner", "name": "Dark Runner",
//     "icon": "https://zloy.net/uploads/appicons/a1-abc.png",
//     "summary": "Run in the dark.",
//     "url": "https://zloy.net/darkrunner" } ] }

interface App {
  app_id: number; slug: string; name: string;
  icon: string; summary: string; url: string;
}
interface AppsPage { ok: boolean; total: number; apps: App[] }

postResultGET#

Publishes a result on the player's own wall. The post appears at zloy.net/<player>/<seq>, where seq is the post number within that player's page (so zloy.net/alice/7 and zloy.net/bob/7 are different posts). The player is the author; the request IP is stored alongside, as required by Russian social-network law.

text is required, up to 280 characters. Posting is allowed one week after the player registered, otherwise the response is posting_locked. An hourly per-player limit guards against spam — rate_limited.

const r = await zloy.postResult(`Scored ${score} points!`);
if (r.ok) window.open(r.url, '_blank');

// Response:
// { "ok": true, "post_id": 812, "seq": 34,
//   "url": "https://zloy.net/alice/34" }

const r: {ok: boolean; post_id: number; seq: number; url: string} =
  await zloy.postResult(`Scored ${score} points!`);

sendToWallPOST#

Puts an achievement on the game's own page (zloy.net/<game_slug>game): a markdown results table and a screenshot or a short clip. The post is signed by the player the call came from, so it also lands in their friends' feeds. The media joins the page gallery.

text — markdown, up to 4000 characters; image — a canvas, Blob or File: we accept png, jpeg, gif, bmp, webp (up to 4 MB, side up to 1920). video — a Blob or File in any format the server can read (webm from MediaRecorder, mp4, mov, mkv): up to 200 MB and up to 180 seconds. No need to compress before sending — we will.

text_en — the same post in English (optional, also up to 4000 characters). Send both and the post is bilingual: readers see the text in their language with a ru | en switch, and text is taken as Russian. Only text_en — the post is English.

No links and no code in the text. You may only link to zloy.net and *.zloy.net (the page, the game site); a URL with a scheme to another domain, www., a bare domain like something.com, t.me/… and an @name mention of five or more characters are refused with bad_text and reason: "link". HTML tags, ``` blocks, backticks and javascript: — bad_text with reason: "code". The post is signed by the player and goes to their friends' feeds, and with the page owner's permission to the owner's channels too: someone else's address under a record in a real person's name is exactly what must not happen here. Tables, bold, italics, versions like "v1.2" and scores like "3.5" pass. postResult follows the same rule.

Cross-posting. If the page owner has linked Telegram or MAX channels and allowed game posts there in Zloy Studio, the post goes there too — with its media (a clip already transcoded and watermarked) and a link to the game. You don't need to do anything for it, and by default game posts don't go to channels.

A screenshot or a clip, but not both (otherwise image_and_video): a post card has one place for media, and the platform will not choose for you which one to show. At least one of the three — text, image or video — is required.

The screenshot is always stored as JPEG, whatever you send: a game frame is a photograph by nature, and PNG would keep it five times more expensively with no visible gain. Transparency is lost in the process — whatever was transparent turns black. A clip is always MP4 720p (H.264 + AAC): a game records with whatever is at hand, while the post is watched from someone else's phone via a link in a feed, and it gets no second try. 1080p and 4K are scaled down to 720p — invisible in a feed, three times lighter.

Clips are transcoded in a queue, and the post appears before the clip does. The reply comes back at once carrying media_status: "processing"; the clip itself reaches the post tens of seconds later, and until then the page says it is being prepared. The platform will not hold your call for all that time: a minute of waiting is a frozen screen for the player and a request timed out on your side. Rejections that are visible immediately (not a video, too long, too large) come back as normal errors — no waiting needed.

Only games upload media to zloy.net. People cannot — a stream of arbitrary pictures and clips is something we have no way to moderate; a game answers for what it posts with its key. Files are served from a separate domain, s.zloy.net.

The platform stamps the watermark itself — on screenshots and on clips alike: a black plate with the zloy.net icon and your game's address in the bottom-left corner (3% of the frame height). The post travels into friends' feeds and onwards through reposts, and the mark is the only thing that leads back to the game. You do not need to draw your own — but keep the bottom-left corner of the frame free: a score or a button there ends up under the plate.

The reply carries the address of the POST, not of the file. What gets published is the record: it has an address, a deadline, reactions and comments, and it is what you show the player. The image_url and video_url fields are gone — for a clip the file does not even exist yet when we reply.

A post lives 30 days, after which the platform deletes both the record and the file (the deadline comes back in expires_at). A game page is not an archive: last season's table crowds out today's.

Rate — one post per hour and at most 12 per day per player in this game. The limit belongs to the game: how much the player posted in other games does not touch yours, and the other way round. Over the limit you get rate_limited together with retry_after in seconds; retrying sooner is pointless. It is not a failure: say “you can share this later” rather than showing an error. If the game has no promo page yet the answer is no_page — there is nowhere to post. Until the first approved release the page is closed and the answer is not_released: nothing from the draft is posted there, including by the game. Nothing is posted from the sandbox (dev=1) either, even for a released game — the answer is sandbox: otherwise testing the button would land on the live page and in friends' feeds. Test everything up to the send in the sandbox, and the send itself in the published version.

Upload progress — onProgress. A clip is tens of megabytes; on a poor connection that is minutes, and without a bar the player decides the game has frozen. The handler gets {loaded, total, fraction}, fraction from 0 to 1. Once it reaches 1 the file is on the server, but the reply comes a few seconds later: the server is still checking the clip. Show “processing” meanwhile, not a frozen 100%.

A failure comes back as a reply, not an exception: a dropped connection is network, a reply from something on the way rather than our server is http_error. The reason in words comes from zloy.wallErrorText(r, lang) — in Russian or English, for rate_limited already with “how long to wait”. Show the player that, not the code.

const r = await zloy.sendToWall({
  text: `**Season closed!**\n\n| place | player | score |\n|---|---|---|\n| 1 | Alice | 9120 |`,
  image: document.querySelector('canvas'),   // canvas | Blob | File
});

if (r.ok) console.log(r.url, 'expires', r.expires_at);
else if (r.error === 'rate_limited') laterMsg(r.retry_after);

// Response — about the POST, not the file:
// { "ok": true, "seq": 41,
//   "url": "https://zloy.net/darkrunnergame/41",
//   "expires_at": "2026-09-16T21:03:11Z" }

// A CLIP — instead of a screenshot. Record it straight off the game canvas:
const stream = document.querySelector('canvas').captureStream(30);
const rec = new MediaRecorder(stream, { mimeType: 'video/webm' });
const parts = [];
rec.ondataavailable = (e) => parts.push(e.data);
rec.start();
setTimeout(() => rec.stop(), 8000);        // 8 seconds of the trick
rec.onstop = async () => {
  const clip = new Blob(parts, { type: 'video/webm' });
  const r = await zloy.sendToWall({
    text: 'What a run!', video: clip,
    onProgress: (p) => ring.set(p.fraction),   // upload ring by the button
  });
  if (!r.ok) reason.textContent = zloy.wallErrorText(r, me.lang);
  // { "ok": true, "seq": 42, "url": "https://zloy.net/darkrunnergame/42",
  //   "expires_at": "…", "media_status": "processing" }
  // You can show the link right away: the post exists, the clip catches up.
};

interface WallPost {
  ok: boolean; seq: number; url: string;
  expires_at: string;
  media_status?: 'processing';   // the clip is still being transcoded
  error?: 'sandbox' | 'no_page' | 'not_released' | 'empty' | 'text_too_long' | 'image_too_large'
        | 'image_and_video' | 'video_too_large' | 'video_too_long'
        | 'bad_video' | 'video_unsupported' | 'bad_text'
        | 'rate_limited' | 'posting_locked' | 'banned'
        | 'network' | 'aborted' | 'http_error';   // failure on the way, not a server reply
  reason?: 'link' | 'code';   // only with bad_text
  retry_after?: number;   // seconds, only with rate_limited
}

const r: WallPost = await zloy.sendToWall({ text: 'New record!' });

buyallowlisted#

An in-game purchase. The game names the item and its price in Zloy Coin — and that is all it does: the platform draws the window with the amount and consent, charges the player and puts the item into the game bank as a currency named after the item. The result comes as a zloy-purchase event on the game's window.

In Telegram (the game runs in a bot, zloy.platform === 'tg') the same call is paid in Stars: the Stars price comes from the developer's rate and prices in the Studio (“External platforms”). The game changes nothing.

In MAX (zloy.platform === 'max') there is no in-messenger payment: the platform opens the zloy.net payment page in a browser, and the game immediately gets zloy-purchase with paid: false, status: 'external' — the decision happens elsewhere. An item paid on the website lands in the game bank.

The truth about a purchase lives in the game bank: the window can be closed and the connection can drop. Check the item balance, not just the event.

window.addEventListener('zloy-purchase', e => {
  if (e.detail.paid) giveItem(e.detail.item_id, e.detail.count);
});
// item "gem", "Gem", 10 Zloy Coin each, 3 pieces
await zloy.buy('gem', 'Gem', 10, 3);

type Purchase = {type: 'zloy-purchase'; paid: boolean;
  item_id?: string; count?: number; error?: string};
window.addEventListener('zloy-purchase', (e: CustomEvent<Purchase>) => {
  if (e.detail.paid) giveItem(e.detail.item_id!, e.detail.count!);
});
await zloy.buy('gem', 'Gem', 10, 3);

payallowlisted#

The SDK shows a “Top up” overlay with a description and an amount in roubles; once the player confirms, a payment is created (GET /v1/createPayment?amount=<₽>&description=…) and the browser follows the returned url to the payment provider.

Payments are available to an allowlisted set of games. If your game is not on the list the call quietly resolves to {ok: false, error: 'payments_not_allowed'} and shows nothing. Check with GET /v1/paymentsAllowed → {"ok":true,"allowed":true|false}.

In Telegram pay returns {ok: false, error: 'use_buy'}: leaving for a payment system is forbidden there by Telegram rules — purchases go through buy.

Where the purchase is credited (which bank cube and currency) is configured in the game's settings — see the bank cube.

const r = await zloy.pay('100 crystals', 199);
// r.ok === true       → confirmed, redirecting to the payment provider
// r.error === 'payments_not_allowed' | 'cancelled'

const r: {ok: boolean; error?: 'payments_not_allowed' | 'cancelled'} =
  await zloy.pay('100 crystals', 199);