Skip to main content

Attachments

VK-IO provides specialized attachment classes for all VK media types. All attachment classes extend the base Attachment class.

Base Attachment Class

The base class for all attachments.

Properties

type
string
The attachment type (e.g., ‘photo’, ‘video’, ‘audio’, ‘doc’)
id
number
The attachment ID
ownerId
number
The owner ID (user or community)
accessKey
string | undefined
Access key for private attachments
isFilled
boolean
Whether the attachment has full data loaded
canBeAttached
boolean
Whether the attachment can be attached via string representation

Methods

fromString(attachment, api)

Parses an attachment from a string.
attachment
string
required
Attachment string (e.g., “photo123_456” or “photo123_456_abc”)
api
API
required
API instance
const attachment = Attachment.fromString('photo123_456', vk.api);
Returns: Attachment

equals(attachment)

Checks if this attachment is equivalent to another.
attachment
Attachment | string
required
Attachment to compare with
if (attachment1.equals('photo123_456')) {
  console.log('Same attachment');
}
Returns: boolean

toString()

Returns the string representation for VK API.
const str = attachment.toString(); // "photo123_456" or "photo123_456_abc"
Returns: string

toJSON()

Returns JSON representation of the attachment. Returns: object

PhotoAttachment

Represents a photo attachment.

Properties

userId
number | undefined
ID of the user who uploaded the photo
albumId
number | undefined
Album ID containing the photo
text
string | undefined
Photo caption
createdAt
number | undefined
Upload timestamp (Unix time)
width
number | undefined
Photo width in pixels
height
number | undefined
Photo height in pixels
smallSizeUrl
string | undefined
URL of small photo (130 or 75px)
mediumSizeUrl
string | undefined
URL of medium photo (807, 604px or less)
largeSizeUrl
string | undefined
URL of large photo (2560, 1280px or less)
sizes
IPhotoSize[] | undefined
Array of all available photo sizes

Methods

loadAttachmentPayload()

Loads full photo data from VK API if not already loaded.
await photo.loadAttachmentPayload();
console.log(photo.largeSizeUrl);
Returns: Promise<void>

getSizes(sizeTypes)

Returns photo sizes of specified types.
sizeTypes
string[]
required
Array of size type identifiers (e.g., [‘w’, ‘z’, ‘y’])
const largeSizes = photo.getSizes(['w', 'z']);
Returns: IPhotoSize[]

IPhotoSize

Usage Example

const photo = new PhotoAttachment({
  api: vk.api,
  payload: {
    id: 456,
    owner_id: 123,
    sizes: [/* ... */],
  },
});

await photo.loadAttachmentPayload();
console.log(photo.largeSizeUrl);
console.log(photo.width, photo.height);

VideoAttachment

Represents a video attachment.

Properties

title
string | undefined
Video title
description
string | undefined
Video description
duration
number | undefined
Video duration in seconds
createdAt
number | undefined
Upload timestamp
addedAt
number | undefined
Added to user’s videos timestamp
viewsCount
number | undefined
Number of views
commentsCount
number | undefined
Number of comments
player
string | undefined
URL to the video player page
platformName
string | undefined
Platform name for external videos
isRepeat
boolean | undefined
Whether the video is repeatable
isCanAdd
boolean | undefined
Whether user can add the video
isCanEdit
boolean | undefined
Whether user can edit the video
isProcessing
boolean | undefined
Whether the video is being processed
isBroadcast
boolean | undefined
Whether the video is a live broadcast
isUpcoming
boolean | undefined
Whether the video is an upcoming broadcast
isFavorited
boolean | undefined
Whether the video is bookmarked

Methods

loadAttachmentPayload()

Loads full video data from VK API. Returns: Promise<void>

AudioAttachment

Represents an audio attachment.

Properties

title
string | undefined
Track title
artist
string | undefined
Artist name
duration
number | undefined
Track duration in seconds
url
string | undefined
Audio file URL
lyricsId
number | undefined
Lyrics identifier
albumId
number | undefined
Album identifier
genreId
number | undefined
Genre identifier
createdAt
number | undefined
Upload timestamp
isHq
boolean | undefined
Whether the audio is high quality

Methods

loadAttachmentPayload()

Loads full audio data from VK API. Returns: Promise<void>

DocumentAttachment

Represents a document attachment.

Properties

title
string | undefined
Document title
size
number | undefined
File size in bytes
extension
string | undefined
File extension
url
string | undefined
Download URL
createdAt
number | undefined
Upload timestamp
typeId
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | undefined
Document type: 1=text, 2=archive, 3=gif, 4=image, 5=audio, 6=video, 7=e-book, 8=unknown
preview
object | undefined
Preview data (for images, graffiti, voice messages)
isText
boolean | undefined
Whether the document is a text file
isArchive
boolean | undefined
Whether the document is an archive
isGif
boolean | undefined
Whether the document is a GIF
isImage
boolean | undefined
Whether the document is an image
isGraffiti
boolean | undefined
Whether the document is a graffiti
isAudio
boolean | undefined
Whether the document is an audio file
isVoice
boolean | undefined
Whether the document is a voice message
isVideo
boolean | undefined
Whether the document is a video file
isBook
boolean | undefined
Whether the document is an e-book

Methods

loadAttachmentPayload()

Loads full document data from VK API. Returns: Promise<void>

hasPreviewProperty(name)

Checks if the document has a specific preview property.
name
'photo' | 'graffiti' | 'audio_message'
required
Preview property name
Returns: boolean

WallAttachment

Represents a wall post attachment.

Properties

text
string | undefined
Post text
authorId
number | undefined
Author ID
createdAt
number | undefined
Post creation timestamp
postType
string | undefined
Post type
viewsCount
number | undefined
Number of views
likesCount
number | undefined
Number of likes
repostsCount
number | undefined
Number of reposts
commentsCount
number | undefined
Number of comments
attachments
(Attachment | ExternalAttachment)[]
Attachments in the post
copyHistory
WallAttachment[] | undefined
Repost history
signerId
number | undefined
ID of the user who signed the post
isPinned
boolean | undefined
Whether the post is pinned
isFavorited
boolean | undefined
Whether the post is bookmarked
hasComments
boolean | undefined
Whether the post has comments
hasAds
boolean | undefined
Whether the post contains ads
hasUserLike
boolean | undefined
Whether the current user liked the post
isCanEdit
boolean | undefined
Whether the user can edit the post
isCanDelete
boolean | undefined
Whether the user can delete the post

Methods

loadAttachmentPayload()

Loads full post data from VK API. Returns: Promise<void>

PollAttachment

Represents a poll attachment.

Properties

question
string | undefined
Poll question
authorId
number | undefined
Poll creator ID
createdAt
number | undefined
Poll creation timestamp
endedAt
number | undefined
Poll end timestamp (0 if unlimited)
votes
number | undefined
Total number of votes
answerIds
number[] | undefined
IDs of answers selected by current user
answers
object[] | undefined
Array of poll answers
friends
number[] | undefined
IDs of up to 3 friends who voted
background
object | undefined
Poll background configuration
photo
PhotoAttachment | undefined
Poll photo
isAnonymous
boolean | undefined
Whether the poll is anonymous
isMultiple
boolean | undefined
Whether multiple answers are allowed
isClosed
boolean | undefined
Whether the poll is closed
isBoard
boolean | undefined
Whether the poll is attached to a discussion
isCanEdit
boolean | undefined
Whether the user can edit the poll
isCanVote
boolean | undefined
Whether the user can vote

Methods

loadAttachmentPayload()

Loads full poll data from VK API. Returns: Promise<void>

StickerAttachment

Represents a sticker attachment.

Properties

id
number
Sticker ID
productId
number
Sticker pack ID
images
IStickerImage[]
Array of sticker images
imagesWithBackground
IStickerImage[]
Array of sticker images with backgrounds

IStickerImage


Other Attachment Types

VK-IO also provides these attachment classes:
  • AudioMessageAttachment - Voice messages
  • GiftAttachment - Gifts
  • GraffitiAttachment - Graffiti images
  • LinkAttachment - Shared links
  • MarketAttachment - Market items
  • MarketAlbumAttachment - Market collections
  • StoryAttachment - Stories
  • WallReplyAttachment - Wall comment replies
All follow the same pattern with specific properties for their type.

Helper Functions

transformAttachments(attachments, api)

Transforms raw VK API attachment data into typed attachment instances.
attachments
object[]
required
Raw attachment data from VK API
api
API
required
API instance
import { transformAttachments } from 'vk-io';

const attachments = transformAttachments(rawAttachments, vk.api);
Returns: (Attachment | ExternalAttachment)[]

Usage Example

import { PhotoAttachment, VideoAttachment } from 'vk-io';

// Create from payload
const photo = new PhotoAttachment({
  api: vk.api,
  payload: {
    id: 456,
    owner_id: 123,
    sizes: [/* ... */],
  },
});

// Parse from string
const video = Attachment.fromString('video123_456', vk.api) as VideoAttachment;

// Load full data
await video.loadAttachmentPayload();
console.log(video.title, video.duration);

// Use in messages
await vk.api.messages.send({
  peer_id: userId,
  message: 'Check this out!',
  attachment: [photo.toString(), video.toString()].join(','),
});

Build docs developers (and LLMs) love