Stories API¶

Posting a Story with metadata¶

POST /story

First upload a stories video via /video/upload
and get uploaded file info via /video/{id}/metadata
(see "VideoRequests" for details)

Create and publish a new story using the metadata from the uploaded video.

All contacts (either all friends if isForAll is true, or contacts from includeLists will receive WebSocket event newStory).

Provide chatId to create chat or channel story. Should have Admin rights for that chat/channel.

Parameters (JSON body)¶

name type data type description

isForAll required boolean true if story is available to all contacts

fileLink required string playback.hls from metadata

preview required string thumbnail from metadata

duration required number duration of the story

includeLists optional array list of sharing lists IDs

price optional number price for the story

chatId optional string to post Chat or Channel story

Responses¶

http code content-type response

200 application/json {"id": "SYDY5qXsnv2aJnkoI9qF8E20"}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Request¶

{
  "isForAll": true,
  "fileLink": "https://...video.m3u8",
  "preview": "https://...thumbnail.jpg",
  "duration": 1,
  "includeLists": ["listId"],
  "price": 0
}

Example Response¶

{
  "id": "string"
}

WebSocket event `newStory` payload¶

Field	Type	Example	Possible Values
userId	string	"_qzjQofkCDvpFe8Da3Nlt2"	User IDs
storyId	string	"SYDY5qXsnv2aJnkoI9qF8E20"	Story IDs
userAvatar?	string	"https://example.com/picture.jpg"	URL
storyPreview	string	https://cloudflare.com/dsdfsf/preview.jpg	URL

POST /story/includes

Create or update a sharing list for stories.
If pass JSON object with ID defined - old stored object will be updated.
Provide chatId to create chat or channel story. Should have Admin rights for that chat/channel.

Parameters (JSON body)¶

name type data type description

id optional string list ID (set ID to update object)

type required boolean true for inclusion, false for exclusion

caption required string list name

iconUrl optional string URL for list icon

users required array list of user IDs

chatId optional string to use with Chat or Channel story

Responses¶

http code content-type response

200 application/json {"id": "SYDY5qXsnv2aJnkoI9qF8E20"}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Request¶

{
  "type": true,
  "caption": "string",
  "iconUrl": "URL",
  "users": [ "userId" ]
}

Example Response¶

{
  "id": "SYDY5qXsnv2aJnkoI9qF8E20"
}

GET /story/includes

Retrieve a list of own Sharing lists.
To get list items call /story/includes/{id}
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.

Responses¶

http code content-type response

200 application/json array of JOSN with number of items in the list

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

[
  {
    "id": "string",
    "type": true,
    "caption": "string",
    "iconUrl": "string",
    "usersNumber": 0
  }    
]

GET /story/includes/{id}?chatId={chatId}

Retrieve a list of own Sharing lists.
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.
To get list items call /story/includes/{id}?chatId={chatId}

Parameters (path / query)¶

name type data type description

id required string list ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json JOSN with array of user IDs

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Exclude list not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{
  "id": "string",
  "type": true,
  "caption": "string",
  "iconUrl": "string",
  "users": [ "user1", "user2" ]
}

DELETE /story/includes/{id}?chatId={chatId}

Delete Story include/exclude list.

All contacts (all friends will receive WebSocket event removedStory)

Parameters (path)¶

name type data type description

id required string list ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json {"id": "SYDY5qXsnv2aJnkoI9qF8E20"}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Exclude list not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{
  "id": "string"
}

WebSocket event `removedStory` payload¶

Field	Type	Example	Possible Values
userId	string	"_qzjQofkCDvpFe8Da3Nlt2"	User IDs
storyId	string	"SYDY5qXsnv2aJnkoI9qF8E20"	Story IDs

Getting a list of own stories¶

GET /story?chatId={chatId}

Retrieve a list of own stories.
Objects does not include sharing lists and stats.
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.

Responses¶

http code content-type response

200 application/json array of JSON story objects

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

[
    {
      "isForAll": true,
      "fileLink": "URL",
      "preview": "URL",
      "duration": 1,
      "price": 0,
      "id": "R4yvEIax",
      "created": 172555804,
      "published": 0
    }
]

Getting a list of archived own stories¶

GET /story/archived?chatId={chatId}

Retrieve a list of own stories (Archived).
Objects does not include sharing lists and stats.
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.

Responses¶

http code content-type response

200 application/json array of JSON story objects

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

[
    {
      "isForAll": true,
      "fileLink": "URL",
      "preview": "URL",
      "duration": 1,
      "price": 0,
      "id": "R4yvEIax",
      "created": 172555804,
      "published": 172555804,
      "archived": 172555804
    }
]

Getting own Story info¶

GET /story/{id}?chatId={chatId}

Retrieve own story by ID.
NOTE: If no active story with ID - trying to get it from Archived.
Includes sharing lists but not includes stats.
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.

Parameters (path)¶

name type data type description

id required string story ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json array of JSON story objects

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

    {
      "isForAll": true,
      "fileLink": "URL",
      "preview": "URL",
      "duration": 1,
      "price": 0,
      "id": "R4yvEIax",
      "created": 172555804,
      "published": 0,
      "includeLists": [ "listId" ]
    }

Getting own Story Statistics¶

GET /story/stats/{id}?chatId={chatId}

Full statistics for the Story
(only statistics, no story's metadata)
(reactions grouped by type)
Provide chatId to get chat or channel stories. Should have Admin rights for that chat/channel.

Parameters (path)¶

name type data type description

id required string story ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json array of JSON objects

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{
"id": "string",
"reactions": [
  {
    "reactionType": "string",
    "reactions": [
      {
        "userId": "string",
        "timestamp": 0
      }
    ]
  }
  ],
"views": [
    {
      "userId": "string",
      "timestamp": 0
    }
  ],
"payments": [
    {
      "userId": "string",
      "timestamp": 0
    }
  ]
}

Deleting a story¶

(deprecated) - use UnPublish

DELETE /story/{id}?chatId={chatId}

Delete a specific story and its associated statistics.

Parameters (path)¶

name type data type description

id required string story ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json {}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{ }

UnPublish a story¶

POST /story/unpublish

UnPublish Story and move it to Archive.
Provide chatId to work with chat or channel stories. Should have Admin rights for that chat/channel.

Parameters (body)¶

name type data type description

id required string story ID

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json {}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{ }

Change settings for Stories¶

POST /story/settings

Change settings for Stories. Currently only Paid settings are supported.
If paymentMethod is set to userDefined - user can pay any amount to get access to the Story.
Provide chatId to work with chat or channel stories. Should have Admin rights for that chat/channel.
If stories isPaid is set than passing price when creating a new Story will override the default price.

Parameters (body)¶

name type data type description

chatId optional string Chat ID

isPaid optional boolean will new stories require payment or not

price optional number price for view

paymentMethod optional string "subscription" or "userDefined"

Responses¶

http code content-type response

200 application/json {}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Request¶

{
  "chatId": "SKgyugbhs%R^5465",
  "isPaid": true,
  "price": 25,
  "paymentMethod": "subscription"
}

Example Response¶

{ }

Get settings for Stories¶

GET /story/settings

Settings for Stories. Currently only Paid settings are supported.
Provide chatId to work with chat or channel stories. Should have Admin rights for that chat/channel.

Parameters (query)¶

name type data type description

chatId optional string Chat ID

Responses¶

http code content-type response

200 application/json {}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{
  "chatId": "SKgyugbhs%R^5465",
  "isPaid": true,
  "price": 25,
  "paymentMethod": "subscription"
}

Retrieve stories for subscribers¶

GET /stories

Fetch a list of stories available for viewing, including the current user's status (e.g., reaction, isSeen, isPurchased).
The response is sorted by freshness, with users having the most recent stories listed first.
If provided id - gets viewable stories from a specific author (userId) or group (chatId) or channel (channelId).
type in response will indicate source of Story ("user" | "group" | "channel")
If price is undefined - story view is free. If price is defined - story view is paid. If price is 0 - story view is paid, but the user should decide how much he wants to pay.

Responses¶

http code content-type response

200 application/json array of JSON objects

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

[
  {
    "id": "2vCYv2iInfPvLl_Ql6mOb",
    "avatarUrl": "https://example.com/avatar.jpg",
    "name": "Ivan Ivanov",
    "verified": true,    
    "type": "group", 
    "stories": [
      {
        "isForAll": true,
        "fileLink": "string",
        "preview": "string",
        "duration": 0,
        "price": 0,
        "storyId": "string",
        "userId": "string",
        "published": 0,
        "isSeen": true,
        "isPurchased": true,
        "reaction": "string"
      }
    ]
  }
]

Retrieve stories for a specific author¶

GET /stories/{id}

Fetch all viewable stories from a specific author (id).
If provided id - gets viewable stories from a specific author (userId) or group (chatId) or channel (channelId).

Parameters (path)¶

name type data type description

id required string user/group/channel ID

Responses¶

See /stories responses

Retrieve actual story info & statistics¶

GET /stories/{id}/{storyid}

Fetch detailed statistics and metadata for a specific story (storyid) by a given user/channel/group (id). If provided id - gets viewable stories from a specific author (userId) or group (chatId) or channel (channelId).

Parameters (path)¶

name type data type description

id required string user/group/channel

storyid required string story ID

Responses¶

http code content-type response

200 application/json JOSN with story Info

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{
  "isForAll": true,
  "fileLink": "string",
  "preview": "string",
  "duration": 0,
  "price": 0,
  "id": "string",
  "created": 0,
  "published": 0,
  "views": 0,
  "reactions": [
      {
          "reactionType": "string",
          "counter": 0
      }
  ]
}

Add reactions to a story¶

POST /stories/like

Set or remove a reaction to a specific story.
reaction is required but is not taken into account when isSet is false.
Setting isSet to false will remove any previous reaction of this user.

NOTE: x-timestamp header required NOTE: userId is not required in latest API version

Parameters (body)¶

name type data type description

~~userId~~ ~~required~~ ~~string~~ ~~ID of the story's author~~

storyId required string ID of the story

reaction required string The emoji reaction (e.g., 👍)

isSet required boolean true to add a reaction, false to remove it

Responses¶

http code content-type response

200 application/json {}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{}

Can be sent via WebSocket as request likeStory

WS request payload¶

name type data type description

storyId required string ID of the story

reaction required string The emoji reaction (e.g., 👍)

isSet required boolean true to add a reaction, false to remove it

Mark a story as viewed¶

POST /stories/setview

Mark a story as viewed. Repeated views by the same user are ignored. NOTE: userId is not required in latest API version

Parameters (JSON)¶

name type data type description

~~userId~~ ~~required~~ ~~string~~ ~~ID of the story's author~~

storyId required string ID of the story

Responses¶

http code content-type response

200 application/json {}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{}

Can be sent via WebSocket as request viewStory

WS request payload¶

name type data type description

storyId required string ID of the story

Purchase a story¶

POST /stories/purchase

Mark a story as purchased.
NOTE: userId is not required in latest API version

Parameters (JSON)¶

name type data type description

~~userId~~ ~~required~~ ~~string~~ ~~ID of the story's author~~

storyId required string ID of the story

Responses¶

http code content-type response

200 application/json {}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

404 application/json {"error": "Story not found","timestamp": 1737195610743,"status": 404}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{}

Can be sent via WebSocket as request purchaseStory

WS request payload¶

name type data type description

storyId required string ID of the story

Hide/unhide stories from specific users (or chats/channels)¶

POST /stories/hide

Hide or unhide stories from specific users.
Does not check for user (author) existence.
Hiding stories remove all stories of that author from list of available.

Parameters (JSON)¶

name type data type description

userId required string ID of the story's author

isHidden required boolean true to hide stories, false to unhide them

Responses¶

http code content-type response

200 application/json {}

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

{}

Can be sent via WebSocket as request hideStories

WS request payload¶

name type data type description

userId required string ID of the story's author

isHidden required boolean true to hide stories, false to unhide them

Retrieve hidden users (or chats/channels)¶

GET /stories/hidden

Fetch a list of users whose stories have been hidden, including minimal user information.

Responses¶

http code content-type response

200 application/json array of JSON objects

400 application/json {"error": "Failed...","timestamp": 1737195610743,"status": 400}

401 application/json {"error": "Unauthorized","timestamp": 1737195610743,"status": 401}

500 application/json {"error": "Something went wrong","timestamp": 1737195610743,"status": 500}

Example Response¶

[
  {
      "id": "2vCYv2iInfPvLl_Ql6mOb",
      "avatarUrl": "https://example.com/avatar.jpg",
      "name": "Ivan Ivanov",
      "verified": true
  }
]

name	type	data type	description
isForAll	required	boolean	true if story is available to all contacts
fileLink	required	string	playback.hls from metadata
preview	required	string	thumbnail from metadata
duration	required	number	duration of the story
includeLists	optional	array	list of sharing lists IDs
price	optional	number	price for the story
chatId	optional	string	to post Chat or Channel story

http code	content-type	response
`200`	`application/json`	`{"id": "SYDY5qXsnv2aJnkoI9qF8E20"}`
`400`	`application/json`	`{"error": "Failed...","timestamp": 1737195610743,"status": 400}`
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

name	type	data type	description
id	optional	string	list ID (set ID to update object)
type	required	boolean	true for inclusion, false for exclusion
caption	required	string	list name
iconUrl	optional	string	URL for list icon
users	required	array	list of user IDs
chatId	optional	string	to use with Chat or Channel story

http code	content-type	response
`200`	`application/json`	array of JOSN with number of items in the list
`400`	`application/json`	`{"error": "Failed...","timestamp": 1737195610743,"status": 400}`
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

http code	content-type	response
`200`	`application/json`	JOSN with array of user IDs
`400`	`application/json`	`{"error": "Failed...","timestamp": 1737195610743,"status": 400}`
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`404`	`application/json`	`{"error": "Exclude list not found","timestamp": 1737195610743,"status": 404}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

http code	content-type	response
`200`	`application/json`	array of JSON story objects
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

http code	content-type	response
`200`	`application/json`	array of JSON objects
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`404`	`application/json`	`{"error": "Story not found","timestamp": 1737195610743,"status": 404}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

http code	content-type	response
`200`	`application/json`	`{}`
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`404`	`application/json`	`{"error": "Story not found","timestamp": 1737195610743,"status": 404}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

name	type	data type	description
id	required	string	user/group/channel
storyid	required	string	story ID

http code	content-type	response
`200`	`application/json`	JOSN with story Info
`400`	`application/json`	`{"error": "Failed...","timestamp": 1737195610743,"status": 400}`
`401`	`application/json`	`{"error": "Unauthorized","timestamp": 1737195610743,"status": 401}`
`404`	`application/json`	`{"error": "Story not found","timestamp": 1737195610743,"status": 404}`
`500`	`application/json`	`{"error": "Something went wrong","timestamp": 1737195610743,"status": 500}`

name	type	data type	description
~~userId~~	~~required~~	~~string~~	~~ID of the story's author~~
storyId	required	string	ID of the story
reaction	required	string	The emoji reaction (e.g., `👍`)
isSet	required	boolean	`true` to add a reaction, `false` to remove it

Stories API¶

Posting a Story with metadata¶

Parameters (JSON body)¶

Responses¶

Example Request¶

Example Response¶

WebSocket event newStory payload¶

Creating or updating a sharing list¶

Parameters (JSON body)¶

Responses¶

Example Request¶

Example Response¶

Getting a list of own Sharing lists¶

Responses¶

Example Response¶

Getting a Sharing list with items¶

Parameters (path / query)¶

Responses¶

Example Response¶

Deleting Sharing list¶

Parameters (path)¶

Responses¶

Example Response¶

WebSocket event removedStory payload¶

Getting a list of own stories¶

Responses¶

Example Response¶

Getting a list of archived own stories¶

Responses¶

Example Response¶

Getting own Story info¶

Parameters (path)¶

Responses¶

Example Response¶

Getting own Story Statistics¶

Parameters (path)¶

Responses¶

Example Response¶

Deleting a story¶

Parameters (path)¶

Responses¶

Example Response¶

UnPublish a story¶

Parameters (body)¶

Responses¶

Example Response¶

Change settings for Stories¶

Parameters (body)¶

Responses¶

Example Request¶

Example Response¶

Get settings for Stories¶

Parameters (query)¶

Responses¶

Example Response¶

Retrieve stories for subscribers¶

Responses¶

Example Response¶

Retrieve stories for a specific author¶

Parameters (path)¶

Responses¶

Retrieve actual story info & statistics¶

Parameters (path)¶

Responses¶

Example Response¶

Add reactions to a story¶

Parameters (body)¶

Responses¶

Example Response¶

WS request payload¶

Mark a story as viewed¶

Parameters (JSON)¶

Responses¶

Example Response¶

WS request payload¶

Purchase a story¶

Parameters (JSON)¶

Responses¶

Example Response¶

WS request payload¶

WebSocket event `newStory` payload¶

WebSocket event `removedStory` payload¶