Skip to content

IExpressions

v1 stable

/IExpressions/v1/

Read a space's sticker and custom emoji packs and add to them. Bots change only the packs and items they made, and never delete or reorder. Writing takes CreateExpressions among the bot's required entitlements; a space that installed the bot before it asked for it grants that only once the owner approves.

Authentication required

All endpoints require Authorization: Bot <token> header. Get a token →

POST /IExpressions/v1/AddItem CreateExpressions

Adds a sticker or emoji to a pack (multipart). file, and thumb for an animated item (a first-frame WEBP of the same size), are parts, attach://<part> references or fileIds from IFiles/Upload. PNG is stored as WEBP. Each call adds a new item; deduplicating a re-import is the bot's job, e.g. keep tg:<file_unique_id> as a keyword and check List first. Needs CreateExpressions; existing installs grant it after the owner re-approves the bot.

Form Fields multipart/form-data

Each field is a text part; a list repeats its field once per value, or sends one field holding a JSON array. A file field is a part of that name, or a text field holding attach://<part> that names another part of the request. Where a route reuses uploads, it also takes the fileId of an IFiles/Upload. See Stickers & Custom Emoji → Files.

Field Type
spaceId
uuid
packId
uuid
name
string
file
file

A file: the part of this name itself, or a text field holding attach://<name> (another part of the request) or the fileId of an IFiles/Upload.

emoji
string[] optional
keywords
string[] optional
textColor
boolean optional
thumb
file optional

A file: the part of this name itself, or a text field holding attach://<name> (another part of the request) or the fileId of an IFiles/Upload.

<part>
file optional

A part an attach://<name> reference names.

Response BotExpressionItemV1

Field Type
itemId uuid
packId uuid
spaceId uuid
kind "sticker" | "emoji"
format "static" | "lottie" | "video"
name string
url string | null
thumbUrl string | null
width int32
height int32
fileSize int32
emoji string[]
keywords string[]
textColor boolean
sortOrder int32
creatorId uuid | null
createdByBot boolean

Errors

Status Code Description
400 invalid_format A title, slug, name, emoji, keyword or external id is not acceptable, or the file is not (format, dimensions, duration, frame rate).
400 invalid_request The form could not be read: a field is missing or malformed, or an attach:// reference names no part.
400 missing_space_id spaceId is required.
403 insufficient_permissions Bot lacks CreateExpressions in this space, or the pack or item is not one it made. Bots never delete or reorder.
403 not_a_member Bot is not a member of this space.
404 not_found The pack, item or file does not exist.
409 name_taken The slug or the emoji name is already used in this space.
413 too_large The request, or a file in it, is over the size limit.
422 content_rejected Moderation refused the file.
422 quota_exceeded The space's packs or slots, the pack, or the bot's unclaimed uploads are full.
429 space_rate_limited The bots' budget for sticker and emoji changes in this space is spent for the minute; see Retry-After.

Example

curl -X POST \
     -H "Authorization: Bot YOUR_TOKEN" \
     -F "spaceId=..." \
     -F "packId=..." \
     -F "name=..." \
     -F "file=@./file" \
     https://gateway.argon.zone/IExpressions/v1/AddItem
POST /IExpressions/v1/CreatePack CreateExpressions

Creates a sticker or emoji pack. Repeating it with the slug of a pack this bot made returns that pack. Needs CreateExpressions; existing installs grant it after the owner re-approves the bot.

Request Body CreatePackRequest

Field Type
spaceId
uuid
kind
"sticker" | "emoji"
title
string
slug
string

Response BotExpressionPackV1

Field Type
packId uuid
spaceId uuid
kind "sticker" | "emoji"
title string
slug string
coverItemId uuid | null
sortOrder int32
version int64
items BotExpressionItemV1[]
↳ itemId uuid
↳ packId uuid
↳ spaceId uuid
↳ kind "sticker" | "emoji"
↳ format "static" | "lottie" | "video"
↳ name string
↳ url string | null
↳ thumbUrl string | null
↳ width int32
↳ height int32
↳ fileSize int32
↳ emoji string[]
↳ keywords string[]
↳ textColor boolean
↳ sortOrder int32
↳ creatorId uuid | null
↳ createdByBot boolean
creatorId uuid | null
createdByBot boolean

Errors

Status Code Description
400 invalid_format A title, slug, name, emoji, keyword or external id is not acceptable, or the file is not (format, dimensions, duration, frame rate).
400 missing_space_id spaceId is required.
403 insufficient_permissions Bot lacks CreateExpressions in this space, or the pack or item is not one it made. Bots never delete or reorder.
403 not_a_member Bot is not a member of this space.
409 name_taken The slug or the emoji name is already used in this space.
422 quota_exceeded The space's packs or slots, the pack, or the bot's unclaimed uploads are full.
429 space_rate_limited The bots' budget for sticker and emoji changes in this space is spent for the minute; see Retry-After.

Example

curl -X POST \
     -H "Authorization: Bot YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"spaceId":"...","kind":"...","title":"...","slug":"..."}' \
     https://gateway.argon.zone/IExpressions/v1/CreatePack
GET /IExpressions/v1/GetPack

Gets one pack with its items, by packId or by slug.

Query Parameters

Field Type
spaceId
uuid
packId
uuid | null
slug
string | null

Response BotExpressionPackV1

Field Type
packId uuid
spaceId uuid
kind "sticker" | "emoji"
title string
slug string
coverItemId uuid | null
sortOrder int32
version int64
items BotExpressionItemV1[]
↳ itemId uuid
↳ packId uuid
↳ spaceId uuid
↳ kind "sticker" | "emoji"
↳ format "static" | "lottie" | "video"
↳ name string
↳ url string | null
↳ thumbUrl string | null
↳ width int32
↳ height int32
↳ fileSize int32
↳ emoji string[]
↳ keywords string[]
↳ textColor boolean
↳ sortOrder int32
↳ creatorId uuid | null
↳ createdByBot boolean
creatorId uuid | null
createdByBot boolean

Errors

Status Code Description
400 invalid_request The form could not be read: a field is missing or malformed, or an attach:// reference names no part.
400 missing_space_id spaceId is required.
403 not_a_member Bot is not a member of this space.
404 not_found The pack, item or file does not exist.

Example

curl -X GET \
     -H "Authorization: Bot YOUR_TOKEN" \
     "https://gateway.argon.zone/IExpressions/v1/GetPack?spaceId=...&packId=...&slug=..."
GET /IExpressions/v1/GetQuota

How many packs, stickers and emoji the space holds against its limits, which grow with its boost level.

Query Parameters

Field Type
spaceId
uuid

Response BotQuotaV1

Field Type
packs BotQuotaUsageV1
↳ used int32
↳ max int32
stickers BotQuotaUsageV1
↳ used int32
↳ max int32
emoji BotQuotaUsageV1
↳ used int32
↳ max int32
itemsPerPack BotItemsPerPackV1
↳ sticker int32
↳ emoji int32
boostLevel int32

Errors

Status Code Description
400 missing_space_id spaceId is required.
403 not_a_member Bot is not a member of this space.

Example

curl -X GET \
     -H "Authorization: Bot YOUR_TOKEN" \
     "https://gateway.argon.zone/IExpressions/v1/GetQuota?spaceId=..."
GET /IExpressions/v1/List

Lists the space's packs with their items. Pass the version you hold as known: packs is null while it is still current.

Query Parameters

Field Type
spaceId
uuid
known
string | null

Response ExpressionsListResponse

Field Type
version string
packs BotExpressionPackV1[] | null
↳ packId uuid
↳ spaceId uuid
↳ kind "sticker" | "emoji"
↳ title string
↳ slug string
↳ coverItemId uuid | null
↳ sortOrder int32
↳ version int64
↳ items BotExpressionItemV1[]
↳ itemId uuid
↳ packId uuid
↳ spaceId uuid
↳ kind "sticker" | "emoji"
↳ format "static" | "lottie" | "video"
↳ name string
↳ url string | null
↳ thumbUrl string | null
↳ width int32
↳ height int32
↳ fileSize int32
↳ emoji string[]
↳ keywords string[]
↳ textColor boolean
↳ sortOrder int32
↳ creatorId uuid | null
↳ createdByBot boolean
↳ creatorId uuid | null
↳ createdByBot boolean

Errors

Status Code Description
400 missing_space_id spaceId is required.
403 not_a_member Bot is not a member of this space.

Example

curl -X GET \
     -H "Authorization: Bot YOUR_TOKEN" \
     "https://gateway.argon.zone/IExpressions/v1/List?spaceId=...&known=..."
PATCH /IExpressions/v1/UpdateItem CreateExpressions

Changes the name, associated emoji, keywords or text colouring of an item this bot made. Fields left out are kept. Needs CreateExpressions; existing installs grant it after the owner re-approves the bot.

Request Body UpdateItemRequest

Field Type
spaceId
uuid
itemId
uuid
name
string | null
emoji
string[] | null
keywords
string[] | null
textColor
boolean | null

Response BotExpressionItemV1

Field Type
itemId uuid
packId uuid
spaceId uuid
kind "sticker" | "emoji"
format "static" | "lottie" | "video"
name string
url string | null
thumbUrl string | null
width int32
height int32
fileSize int32
emoji string[]
keywords string[]
textColor boolean
sortOrder int32
creatorId uuid | null
createdByBot boolean

Errors

Status Code Description
400 invalid_format A title, slug, name, emoji, keyword or external id is not acceptable, or the file is not (format, dimensions, duration, frame rate).
400 missing_space_id spaceId is required.
403 insufficient_permissions Bot lacks CreateExpressions in this space, or the pack or item is not one it made. Bots never delete or reorder.
403 not_a_member Bot is not a member of this space.
404 not_found The pack, item or file does not exist.
409 name_taken The slug or the emoji name is already used in this space.
429 space_rate_limited The bots' budget for sticker and emoji changes in this space is spent for the minute; see Retry-After.

Example

curl -X PATCH \
     -H "Authorization: Bot YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"spaceId":"...","itemId":"...","name":null,"emoji":null,"keywords":null,"textColor":null}' \
     https://gateway.argon.zone/IExpressions/v1/UpdateItem
PATCH /IExpressions/v1/UpdatePack CreateExpressions

Changes the title or the cover item of a pack this bot made. Fields left out are kept. Needs CreateExpressions; existing installs grant it after the owner re-approves the bot.

Request Body UpdatePackRequest

Field Type
spaceId
uuid
packId
uuid
title
string | null
coverItemId
uuid | null

Response BotExpressionPackV1

Field Type
packId uuid
spaceId uuid
kind "sticker" | "emoji"
title string
slug string
coverItemId uuid | null
sortOrder int32
version int64
items BotExpressionItemV1[]
↳ itemId uuid
↳ packId uuid
↳ spaceId uuid
↳ kind "sticker" | "emoji"
↳ format "static" | "lottie" | "video"
↳ name string
↳ url string | null
↳ thumbUrl string | null
↳ width int32
↳ height int32
↳ fileSize int32
↳ emoji string[]
↳ keywords string[]
↳ textColor boolean
↳ sortOrder int32
↳ creatorId uuid | null
↳ createdByBot boolean
creatorId uuid | null
createdByBot boolean

Errors

Status Code Description
400 invalid_format A title, slug, name, emoji, keyword or external id is not acceptable, or the file is not (format, dimensions, duration, frame rate).
400 missing_space_id spaceId is required.
403 insufficient_permissions Bot lacks CreateExpressions in this space, or the pack or item is not one it made. Bots never delete or reorder.
403 not_a_member Bot is not a member of this space.
404 not_found The pack, item or file does not exist.
429 space_rate_limited The bots' budget for sticker and emoji changes in this space is spent for the minute; see Retry-After.

Example

curl -X PATCH \
     -H "Authorization: Bot YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"spaceId":"...","packId":"...","title":null,"coverItemId":null}' \
     https://gateway.argon.zone/IExpressions/v1/UpdatePack